Skip to main content
POST
/
v1
/
bulk-lookup
Submit Bulk Lookup
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"
    }
  ]
}
'
{
  "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

Response

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