Bulk API
For lists, submit one job instead of looping over single requests. Jobs run in the background, are not subject to the per-second rate limit, and report errors row by row.
Two ways to run a list
In the dashboard, open any product that supports bulk, switch to the Bulk tab and drop a CSV of up to 1,000,000 rows. You map the column, see the credit cost and confirm. Results download with your original columns kept.
From code, use the endpoints below. Both routes produce the same job and appear in the same history.
Run a job
Submit the inputs
POST/v1/bulkRequestcurl -X POST https://api.1lookup.dev/v1/bulk \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 2026-11-19-q4-leads" \ -d '{ "product": "phone-validation", "inputs": [ {"phone_number": "+15125550142"}, {"phone_number": "+13035550177"} ], "webhook_url": "https://example.com/hooks/1lookup" }'productstringrequiredThe product slug to run for every input.
inputsobject[]requiredOne object per row, with the same fields the single endpoint takes.
webhook_urlstring<uri>Called once when the job finishes. See the webhooks guide.
freshbooleanSkip the 7-day cache for every row.
202 Accepted{ "success": true, "data": { "job_id": "job_7c1d9a42", "status": "queued", "product": "phone-validation", "rows": 2, "estimated_credits": 2 }, "meta": { "credits_used": 0, "credits_remaining": 999, "cached": false, "request_id": "req_2b9e61f0a3c4" } }Wait for it to finish
Pass a
webhook_urland we call it once with abulk.completedevent. Or poll the job.GET/v1/bulk/{job_id}Requestcurl https://api.1lookup.dev/v1/bulk/job_7c1d9a42 \ -H "Authorization: Bearer YOUR_API_KEY"200 OK{ "success": true, "data": { "job_id": "job_7c1d9a42", "status": "completed", "product": "phone-validation", "rows": 2, "succeeded": 2, "failed": 0, "duplicates": 0, "cached": 0, "credits_used": 2, "results_url": "https://api.1lookup.dev/v1/bulk/job_7c1d9a42/results" }, "meta": { "credits_used": 0, "credits_remaining": 997, "cached": false, "request_id": "req_5d0c77b1e8aa" } }Status Final Meaning queuedNo Accepted and waiting to start. processingNo Rows are being looked up. succeeded and failed update as it runs. completedYes Every row has a result or a row-level error. cancelledYes You cancelled it. Rows already processed are kept and charged. Fetch the results
GET/v1/bulk/{job_id}/resultsResults come back one entry per input, in input order. Add
?format=csvto download a file.Requestcurl "https://api.1lookup.dev/v1/bulk/job_7c1d9a42/results?format=csv" \ -H "Authorization: Bearer YOUR_API_KEY" \ -o results.csv200 OK{ "success": true, "data": { "results": [ { "row": 0, "input": { "phone_number": "+15125550142" }, "data": { "valid": true, "line_type": "mobile" }, "credits_used": 1 }, { "row": 1, "input": { "phone_number": "12" }, "error": { "code": "invalid_input", "message": "Enter a phone number with 7 to 15 digits." }, "credits_used": 0 } ] } }
Row-level errors
A row that could not be processed carries its own error and costs nothing. It never fails the whole job, so one bad value in a file of thousands does not stop the rest.
Idempotency
Send an Idempotency-Key header with a value that is unique to the job. If the same key arrives again within 24 hours, for example after a timeout on your side, you get the original job back instead of a second one.
What is charged
Credits are reserved when the job starts and settled as rows finish. Duplicate inputs inside one job are looked up once. Rows served from the 7-day cache and rows that error cost nothing.
If your balance and your pay-as-you-go limit together cannot cover the estimate, the job is rejected with insufficient_credits before anything runs. See credits and billing.