Submit Bulk Lookup Job (Unlimited Plans)
Submit a bulk email lookup job on an unlimited plan. Rows count as searches against your plan’s daily bulk search limit instead of credits.
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,000rows. - 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_consumedreads0on unlimited plans.
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
API key for authentication
Body
Submission payload for POST /v1/bulk-lookup.
List of (first_name, last_name, domain) tuples to look up. Duplicate tuples are deduplicated before billing. Maximum 10,000 rows per submission.
1 - 10000 elementsResponse
Successful Response
Response when submitting a bulk lookup job.
Unique job identifier. Pass this to GET /v1/bulk-lookup/{job_id} to poll status.
"123e4567-e89b-12d3-a456-426614174000"
Submission acknowledgement status.
submitted "submitted""submitted"
Number of unique rows submitted after deduplication.
500
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).
500