Skip to main content
POST
Submit Bulk Email Finder Job (Unlimited Plans)
This is the unlimited-plan variant of POST /v1/bulk-lookup. The request body, deduplication behaviour, async processing model, and per-job limit of 10,000 rows are identical; see the counterpart page for those details. What differs is metering: submissions draw from your plan’s daily bulk search quota instead of your credit balance — one search per submitted row. Requests require an Unlimited API key tied to an active unlimited plan. A pay-as-you-go key on this endpoint returns 403 with code: wrong_key_plan; if the plan’s subscription has lapsed, the key returns 402 with code: subscription_inactive until it is reinstated. Poll GET /v1/unlimited/bulk-lookup/{job_id} to track progress, then fetch results via GET /v1/unlimited/bulk-lookup/{job_id}/results.

Daily search quota

  • You can submit an unlimited number of jobs, each up to 10,000 rows.
  • Each accepted submission consumes one search per unique (deduplicated) row from your plan’s daily limit: 10,000 searches per day on Starter, 30,000 on Standard, 75,000 on Professional.
  • The daily window is aligned to UTC midnight. Consumption resets when the UTC day rolls over; GET /v1/unlimited/usage reports the exact reset time in bulk_searches_reset_at.
  • The quota is per account and is shared with dashboard bulk finder jobs run on your plan: searches consumed in the dashboard reduce what this endpoint can accept the same day, and vice versa.
  • A rejected or failed submission consumes nothing. If OrbiSearch infrastructure cannot accept or process the submission, any consumed searches are released and no job is created.
  • No credits are charged; credits_consumed reads 0 on unlimited plans.
If a submission would exceed the day’s remaining quota, the request fails with 429 and code: bulk_searches_limited. The Retry-After header gives the seconds until the quota resets at UTC midnight. See errors for handling.

Rate limits

This endpoint shares the per-key request-rate limit with the rest of the API. The daily search quota, not the request rate, is the practical throughput ceiling for bulk work.

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
Allowed value: "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 on pay-as-you-go keys (1 credit per unique row), 0 on unlimited plans (rows draw on the daily cap instead).

Example:

500