Skip to content
Guides

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

  1. Submit the inputs

    POST/v1/bulk
    Request
    curl -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"
      }'
    productstringrequired

    The product slug to run for every input.

    inputsobject[]required

    One object per row, with the same fields the single endpoint takes.

    webhook_urlstring<uri>

    Called once when the job finishes. See the webhooks guide.

    freshboolean

    Skip 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"
      }
    }
  2. Wait for it to finish

    Pass a webhook_url and we call it once with a bulk.completed event. Or poll the job.

    GET/v1/bulk/{job_id}
    Request
    curl 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"
      }
    }
    StatusFinalMeaning
    queuedNoAccepted and waiting to start.
    processingNoRows are being looked up. succeeded and failed update as it runs.
    completedYesEvery row has a result or a row-level error.
    cancelledYesYou cancelled it. Rows already processed are kept and charged.
  3. Fetch the results

    GET/v1/bulk/{job_id}/results

    Results come back one entry per input, in input order. Add ?format=csv to download a file.

    Request
    curl "https://api.1lookup.dev/v1/bulk/job_7c1d9a42/results?format=csv" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -o results.csv
    200 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.