> ## Documentation Index
> Fetch the complete documentation index at: https://orbisearch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Find Email by Name and Domain

> Find a person's deliverable email address from their first name, last name, and company domain. Returns a verified result. Costs 1 credit; cached results are free for 24 hours.

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`](/docs/api-reference/verify-email).

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`](/docs/api-reference/verify-email) and [`/v1/bulk`](/docs/api-reference/bulk-submit). Exceeding it returns a `429 Too Many Requests` response. See [errors](/docs/api-reference/errors) for how to handle rate limit responses.


## OpenAPI

````yaml POST /v1/email-lookup
openapi: 3.1.0
info:
  title: OrbiSearch Public API
  version: 1.0.0
  description: >-
    Email verification API for developers and agents. [Get your API key
    →](https://orbisearch.com/dashboard/api-keys)


    **Rate limiting:** requests are limited per API key (20 requests per second
    by default). Every response includes `X-RateLimit-Limit`,
    `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers describing the
    current per-key window so clients can self-throttle; `429` responses also
    include a `Retry-After` header with the suggested backoff in seconds.
  contact:
    name: Get API Key
    url: https://orbisearch.com/dashboard/api-keys
servers:
  - url: https://api.orbisearch.com
    description: OrbiSearch Public API
security:
  - ApiKeyAuth: []
paths:
  /v1/email-lookup:
    post:
      tags:
        - Public API v1
      summary: Find Email by Name and Domain
      description: >-
        Find a person's deliverable email address from their first name, last
        name,

        and company domain. Provide at least one of first or last name. Returns
        the

        discovered email together with the same

        enrichment fields as `/v1/verify` (`status`, `substatus`, `explanation`,

        `email_provider`, `mx_record`, `is_domain_catch_all`,

        `is_secure_email_gateway`, `is_disposable`, `is_role_account`,
        `is_free`).


        Timeout parameter (optional):

        - Range: 30-90 seconds

        - Default: 90 seconds


        Costs 1 credit per returned response. Refunds are issued only when

        OrbiSearch infrastructure cannot complete the request (HTTP 502).

        Every returned response is charged. Results are cached for 24 hours;

        identical queries within that window are returned from cache at no

        credit cost.


        Rate limit: 20 requests per second per API key, shared with `/v1/verify`

        and `/v1/bulk`. For verifying a list of email addresses you already
        have,

        use the asynchronous `/v1/bulk` endpoint instead.
      operationId: lookup_email_v1_email_lookup_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailLookupRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailLookupResponse'
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 20
            X-RateLimit-Remaining:
              description: Requests remaining in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 13
            X-RateLimit-Reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                type: integer
                examples:
                  - 1751700000
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              example:
                detail: API key required in X-API-Key header
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Insufficient credits
          content:
            application/json:
              example:
                detail: Insufficient credits. You have 0.15 credits but need 0.2.
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 20
            X-RateLimit-Remaining:
              description: Requests remaining in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 13
            X-RateLimit-Reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                type: integer
                examples:
                  - 1751700000
        '422':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                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
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 20
            X-RateLimit-Remaining:
              description: Requests remaining in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 13
            X-RateLimit-Reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                type: integer
                examples:
                  - 1751700000
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              description: >-
                Seconds the client should wait before retrying. Computed from
                the remaining rate-limit window (typically 1 for the per-second
                limit, longer when the limit is exceeded by 3x or more); for
                endpoints with a daily quota, seconds until the quota resets.
              schema:
                type: integer
                examples:
                  - 1
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 20
            X-RateLimit-Remaining:
              description: Requests remaining in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 13
            X-RateLimit-Reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                type: integer
                examples:
                  - 1751700000
          content:
            application/json:
              example:
                detail: >-
                  Rate limit exceeded. Maximum 20 requests per second per API
                  key. Contact us to discuss higher limits.
                code: rate_limited
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '503':
          description: Email-lookup service not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                detail: Email lookup is not available in this environment
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 20
            X-RateLimit-Remaining:
              description: Requests remaining in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 13
            X-RateLimit-Reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                type: integer
                examples:
                  - 1751700000
      security:
        - ApiKeyAuth: []
components:
  schemas:
    EmailLookupRequest:
      properties:
        first_name:
          type: string
          maxLength: 255
          title: First Name
          description: >-
            Person's first name. Optional individually — provide at least one of
            first or last name.
          default: ''
          examples:
            - Jane
        last_name:
          type: string
          maxLength: 255
          title: Last Name
          description: >-
            Person's last name. Optional individually — provide at least one of
            first or last name.
          default: ''
          examples:
            - Doe
        domain:
          type: string
          maxLength: 255
          minLength: 3
          title: Domain
          description: Company domain to search within.
          examples:
            - acme.com
        timeout:
          type: integer
          maximum: 97
          minimum: 30
          title: Timeout
          description: Lookup timeout in seconds (30–97).
          default: 97
          examples:
            - 97
      type: object
      required:
        - domain
      title: EmailLookupRequest
      description: Find a deliverable email from a name and company domain.
      example:
        domain: acme.com
        first_name: Jane
        last_name: Doe
        timeout: 97
    EmailLookupResponse:
      properties:
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
          description: >-
            The deliverable email address discovered for this person at this
            domain. Null when no deliverable address could be confirmed.
          examples:
            - jane.doe@acme.com
        status:
          type: string
          enum:
            - safe
            - unknown
          pattern: ^(safe|unknown)$
          title: Status
          description: >-
            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).
          examples:
            - safe
        substatus:
          anyOf:
            - type: string
              pattern: ^(deliverable|no_address_found|timeout)$
            - type: 'null'
          enum:
            - deliverable
            - no_address_found
            - timeout
          title: Substatus
          description: >-
            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.
          examples:
            - deliverable
        explanation:
          type: string
          title: Explanation
          description: Plain-English explanation of the lookup result.
          examples:
            - Safe to email. The mailbox exists and is deliverable.
        email_provider:
          type: string
          title: Email Provider
          description: >-
            Email service provider of the returned address (Google Workspace,
            Microsoft Outlook, etc.).
          examples:
            - Google Workspace
        mx_record:
          anyOf:
            - type: string
            - type: 'null'
          title: Mx Record
          description: >-
            The main mail server the domain uses to receive email. Null if the
            domain has no mail server configured.
          examples:
            - aspmx.l.google.com
        is_domain_catch_all:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Domain Catch All
          description: >-
            True if the domain accepts mail for any username (catch-all). Null
            if we could not determine whether the domain is catch-all.
          examples:
            - false
        is_secure_email_gateway:
          type: boolean
          title: Is Secure Email Gateway
          description: >-
            True if the domain is protected by a secure email gateway —
            Proofpoint, Mimecast, Barracuda, or Trend Micro.
          default: false
          examples:
            - false
        is_disposable:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Disposable
          description: >-
            True if this is a temporary/disposable email service, false if not,
            null if unknown.
          examples:
            - false
        is_role_account:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Role Account
          description: >-
            True if this is a generic role-based email (info@, support@, etc.),
            false if not, null if unknown.
          examples:
            - false
        is_free:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Free
          description: >-
            True if this is from a free email provider (gmail.com, yahoo.com,
            etc.), false if not, null if unknown.
          examples:
            - false
        credits_consumed:
          type: integer
          title: Credits Consumed
          description: Credits charged for this lookup.
          examples:
            - 1
        first_name:
          type: string
          title: First Name
          description: The first name supplied in the request.
          examples:
            - Jane
        last_name:
          type: string
          title: Last Name
          description: The last name supplied in the request.
          examples:
            - Doe
        domain:
          type: string
          title: Domain
          description: The domain supplied in the request.
          examples:
            - acme.com
        confidence:
          anyOf:
            - type: integer
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Confidence
          description: >-
            How certain we are in the verdict on a 0–100 scale. See
            EmailVerificationResponse.confidence for the full scale.
          examples:
            - 99
      type: object
      required:
        - status
        - explanation
        - email_provider
        - credits_consumed
        - first_name
        - last_name
        - domain
      title: EmailLookupResponse
      description: >-
        Lookup result — best deliverable email found for a (first_name,
        last_name, domain).
      example:
        confidence: 99
        credits_consumed: 1
        domain: acme.com
        email: jane.doe@acme.com
        email_provider: Google Workspace
        explanation: Safe to email. The mailbox exists and is deliverable.
        first_name: Jane
        is_disposable: false
        is_domain_catch_all: false
        is_free: false
        is_role_account: false
        is_secure_email_gateway: false
        last_name: Doe
        mx_record: aspmx.l.google.com
        status: safe
        substatus: deliverable
    ApiErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Human-readable description of what went wrong.
          examples:
            - API key required in X-API-Key header
        code:
          anyOf:
            - type: string
            - type: 'null'
          title: Code
          description: >-
            Stable machine-readable error code, present on conditions a client
            may want to branch on (for example `rate_limited` for the per-second
            limit versus `daily_quota_exceeded` for the daily cap). Absent on
            errors that need no further disambiguation.
          examples:
            - daily_quota_exceeded
        errors:
          anyOf:
            - items:
                $ref: '#/components/schemas/ValidationErrorDetail'
              type: array
            - type: 'null'
          title: Errors
          description: >-
            Individual validation failures, one entry per invalid parameter or
            field. Present only on 422 responses; when the request has a single
            problem, `detail` carries the same message. Absent on all other
            error codes.
      type: object
      required:
        - detail
      title: ApiErrorResponse
      description: Error response body.
    ValidationErrorDetail:
      properties:
        loc:
          type: string
          title: Loc
          description: >-
            Where in the request the problem is, as a dot-separated path (e.g.
            `query.email`, `body.0`).
          examples:
            - query.email
        msg:
          type: string
          title: Msg
          description: Human-readable description of this validation error.
          examples:
            - 'Missing required query parameter: email.'
        type:
          type: string
          title: Type
          description: >-
            Machine-readable error category (e.g. `missing`, `less_than_equal`,
            `string_too_long`).
          examples:
            - missing
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationErrorDetail
      description: One request-validation failure.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: API key for authentication
      in: header
      name: X-API-Key

````