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. This endpoint is credit-metered. On an unlimited plan, use POST /v1/unlimited/email-lookup instead (same request and response shape). 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.

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: 1 on pay-as-you-go keys, 0 on unlimited plans (no credits move).

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