Email finder (credits)
Submit Bulk Email Finder Job
Submit a bulk email finder job: a list of LinkedIn profile URLs, or of names and company domains. Returns a job ID at once; poll GET /v1/bulk-lookup/ for progress.
POST
/
v1
/
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": [
{
"linkedin_url": "https://www.linkedin.com/in/jane-doe"
},
{
"linkedin_url": "https://www.linkedin.com/in/john-smith"
}
]
}
'
{
"job_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "submitted",
"total_rows": 500,
"credits_consumed": 500
}{
"detail": "API key required in X-API-Key header"
}{
"detail": "Insufficient credits. You have 0.15 credits but need 0.2."
}{
"detail": "Invalid request body field '0': Input should be a valid string.",
"errors": [
{
"loc": "body.0",
"msg": "Invalid request body field '0': Input should be a valid string.",
"type": "string_type"
}
]
}{
"detail": "Rate limit exceeded. Maximum 20 requests per second per account. Contact us to discuss higher limits.",
"code": "rate_limited"
}{
"detail": "Email finder is not available in this environment"
}Use this endpoint to submit a list of people (LinkedIn profile URLs, or first name, last name, and company domain) as a bulk email finder job. The API accepts your list, deduplicates it, charges your credit balance upfront, and returns a
job_id immediately. Searches run 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.
This endpoint is credit-metered. On an unlimited plan, use POST /v1/unlimited/bulk-lookup instead (same request and response shape).
Deduplication and async processing
OrbiSearch deduplicates your list before processing. If you submit 600 rows but 100 are duplicates (matched case-insensitively on first name + last name + domain, or on the profile for LinkedIn URLs),total_rows will be 500 and you will only be charged for 500 searches.
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 behavior
Each unique row costs1 credit, charged upfront at submission time. Every returned row is charged, except a value that isn’t a LinkedIn profile URL: it’s returned with substatus: invalid_linkedin_url and costs nothing. 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,000rows per submission. Larger lists must be split across multiple jobs. - Each row carries either
linkedin_url(up to 2,048 characters) or adomainwith at least one offirst_nameandlast_name(names up to 64 characters, domain up to 253). - One input type per job: every row a
linkedin_url, or every row a name and domain. A list that mixes them returns422before any charge, naming the first row of the other kind.
Rate limits
This endpoint shares the20 requests per second per account 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
API key for authentication
Body
application/json
Submission payload for POST /v1/bulk-lookup.
Rows to search: every row a linkedin_url, or every row a first/last name and a company domain. One input type per job; a list that mixes them is refused with 422. Duplicate rows are deduplicated before billing. Maximum 10,000 rows per submission.
Required array length:
1 - 10000 elementsShow child attributes
Show child attributes
Response
Successful Response
Response when submitting a bulk email finder job.
Unique job identifier. Pass this to GET /v1/bulk-lookup/{job_id} to poll status.
Example:
"123e4567-e89b-12d3-a456-426614174000"
Submission acknowledgement status.
Available options:
submitted Allowed value:
"submitted"Example:
"submitted"
Number of unique rows submitted after deduplication.
Example:
500
Credits deducted for this submission: 1 per unique row on pay-as-you-go keys, except invalid_linkedin_url rows, which are free; 0 on unlimited plans (rows draw on the daily cap instead).
Example:
500
⌘I
curl --request POST \
--url https://api.orbisearch.com/v1/bulk-lookup \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"input": [
{
"linkedin_url": "https://www.linkedin.com/in/jane-doe"
},
{
"linkedin_url": "https://www.linkedin.com/in/john-smith"
}
]
}
'
{
"job_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "submitted",
"total_rows": 500,
"credits_consumed": 500
}{
"detail": "API key required in X-API-Key header"
}{
"detail": "Insufficient credits. You have 0.15 credits but need 0.2."
}{
"detail": "Invalid request body field '0': Input should be a valid string.",
"errors": [
{
"loc": "body.0",
"msg": "Invalid request body field '0': Input should be a valid string.",
"type": "string_type"
}
]
}{
"detail": "Rate limit exceeded. Maximum 20 requests per second per account. Contact us to discuss higher limits.",
"code": "rate_limited"
}{
"detail": "Email finder is not available in this environment"
}