Submit Bulk Lookup Job

Submit a list of (first name, last name, domain) tuples for bulk email lookup. Returns a job ID immediately. Poll GET /v1/bulk-lookup/ to track progress.

POST /v1/bulk-lookup

Submit Bulk Lookup

cURL

curl --request POST \
  --url https://api.orbisearch.com/v1/bulk-lookup \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "input": [
    {
      "domain": "acme.com",
      "first_name": "Jane",
      "last_name": "Doe"
    },
    {
      "domain": "bigcorp.io",
      "first_name": "John",
      "last_name": "Smith"
    }
  ]
}
'

202

{
  "credits_consumed": 500,
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "submitted",
  "total_rows": 500
}

Use this endpoint to submit a list of people (first name, last name, and company domain) for asynchronous email lookup. The API accepts your list, deduplicates it, charges your credit balance upfront, and returns a job_id immediately. Lookups happen in the background — poll GET /v1/bulk-lookup/{job_id} to track progress, then fetch results via GET /v1/bulk-lookup/{job_id}/results when the job is complete.

Deduplication and async processing

OrbiSearch deduplicates your list before processing. If you submit 600 tuples but 100 are duplicates (matched case-insensitively on first name + last name + domain), total_rows will be 500 and you will only be charged for 500 lookups.

Because bulk jobs run asynchronously, this endpoint returns immediately after accepting the job. Use the returned job_id to poll GET /v1/bulk-lookup/{job_id} until the status field reaches completed. Then fetch results via GET /v1/bulk-lookup/{job_id}/results.

Pricing and refund behaviour

Each unique row costs 1 credit, charged upfront at submission time. Every returned row is charged. Refunds are issued only when OrbiSearch infrastructure cannot accept or process the submission itself — in that case the upfront charge is reversed and no job is created.

If your account has insufficient credits for the deduplicated row count, the request fails with 403 Forbidden.

Limits

• Maximum 10,000 rows per submission. Larger lists must be split across multiple jobs.
• Each row’s first_name, last_name, and domain are required and capped at 255 characters.

Rate limits

This endpoint shares the 20 requests per second per API key limit with the rest of the /v1/* API. Exceeding it returns a 429 Too Many Requests response. See errors for how to handle rate limit responses.

Authorizations

X-API-Key · string · header · required

API key for authentication

Body

application/json

Submission payload for POST /v1/bulk-lookup.

input · BulkLookupInputRow · object[] · required

List of (first_name, last_name, domain) tuples to look up. Duplicate tuples are deduplicated before billing. Maximum 10,000 rows per submission.

Required array length: 1 - 10000 elements

Show child attributes

Response

202

application/json

Successful Response

Response when submitting a bulk lookup job.

job_id · string<uuid> · required

Unique job identifier. Pass this to GET /v1/bulk-lookup/{job_id} to poll status.

Example:

"123e4567-e89b-12d3-a456-426614174000"

status · enum<string> · required

Submission acknowledgement status.

Available options: submitted

Example:

"submitted"

total_rows · integer · required

Number of unique rows submitted after deduplication.

Example:

500

credits_consumed · integer · required

Credits deducted for this submission. Equals total_rows (1 credit per unique row).

Example:

500