Skip to main content
POST
Find Email by Name and Domain
Use this endpoint when you have a person’s name and their company’s domain but not their email address. OrbiSearch returns the deliverable address if one exists at that domain, together with the same enrichment fields as /v1/verify. The response returns status: safe when a deliverable address is found (substatus: deliverable, email set), or status: unknown otherwise — with substatus: no_address_found if we couldn’t find one, or substatus: timeout if the lookup did not complete within the time budget.

Caching

Results are cached for 24 hours. If you look up the same person (matched by first name, last name, and domain, ignoring casing and whitespace) within that window, the cached result is returned immediately at no credit cost.

Pricing and refund behaviour

  • Each lookup costs 1 credit.
  • Every returned response is charged — including status: unknown / substatus: timeout (the lookup ran but did not complete within your timeout value; for harder-to-find people, use bulk lookup for more time per entry).
  • Refunds are issued only when OrbiSearch infrastructure cannot complete the request (502). Retry the request.

Rate limits

This endpoint shares the 20 requests per second per API key limit with /v1/verify and /v1/bulk. 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

Find a deliverable email from a name and company domain.

domain
string
required

Company domain to search within.

Required string length: 3 - 255
Example:

"acme.com"

first_name
string
default:""

Person's first name. Optional individually — provide at least one of first or last name.

Maximum string length: 255
Example:

"Jane"

last_name
string
default:""

Person's last name. Optional individually — provide at least one of first or last name.

Maximum string length: 255
Example:

"Doe"

timeout
integer
default:97

Lookup timeout in seconds (30–97).

Required range: 30 <= x <= 97
Example:

97

Response

Successful Response

Lookup result — best deliverable email found for a (first_name, last_name, domain).

status
enum<string>
required

Lookup status: safe (a deliverable address was found and is in the email field) or unknown (no deliverable address was found, or the lookup timed out; the email field is null).

Available options:
safe,
unknown
Pattern: ^(safe|unknown)$
Example:

"safe"

explanation
string
required

Plain-English explanation of the lookup result.

Example:

"Safe to email. The mailbox exists and is deliverable."

email_provider
string
required

Email service provider of the returned address (Google Workspace, Microsoft Outlook, etc.).

Example:

"Google Workspace"

credits_consumed
integer
required

Credits charged for this lookup.

Example:

1

first_name
string
required

The first name supplied in the request.

Example:

"Jane"

last_name
string
required

The last name supplied in the request.

Example:

"Doe"

domain
string
required

The domain supplied in the request.

Example:

"acme.com"

email
string | null

The deliverable email address discovered for this person at this domain. Null when no deliverable address could be confirmed.

Example:

"jane.doe@acme.com"

substatus
enum<string>

Specific reason for the status: deliverable (a deliverable address was found — only returned with status=safe), no_address_found (no deliverable address was found for this person at this domain — only returned with status=unknown), timeout (the caller's timeout parameter exhausted before the lookup completed; retry with a larger timeout — only returned from /v1/email-lookup, never from /v1/bulk-lookup, since bulk lookups have no caller-tunable timeout). All substatuses are billable; refunds happen only when OrbiSearch infrastructure cannot complete the request.

Available options:
deliverable,
no_address_found,
timeout
Pattern: ^(deliverable|no_address_found|timeout)$
Example:

"deliverable"

mx_record
string | null

The main mail server the domain uses to receive email. Null if the domain has no mail server configured.

Example:

"aspmx.l.google.com"

is_domain_catch_all
boolean | null

True if the domain accepts mail for any username (catch-all). Null if we could not determine whether the domain is catch-all.

Example:

false

is_secure_email_gateway
boolean
default:false

True if the domain is protected by a secure email gateway — Proofpoint, Mimecast, Barracuda, or Trend Micro.

Example:

false

is_disposable
boolean | null

True if this is a temporary/disposable email service, false if not, null if unknown.

Example:

false

is_role_account
boolean | null

True if this is a generic role-based email (info@, support@, etc.), false if not, null if unknown.

Example:

false

is_free
boolean | null

True if this is from a free email provider (gmail.com, yahoo.com, etc.), false if not, null if unknown.

Example:

false

confidence
integer | null

How certain we are in the verdict on a 0–100 scale. See EmailVerificationResponse.confidence for the full scale.

Required range: 0 <= x <= 100
Example:

99