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

# Find a business email

> Only explicitly requested contact research runs discovery/verification. Check evidence, source dates and email outcomes; unknown source dates stay null. All operations accept dry_run and max_credits.

The assistant tool is `find_work_email`. Use a canonical `person_id` or an exact public LinkedIn `/in/` URL on explicit
contact-research intent. This runs actual discovery for the identified person's
observed employer and strictly verifies at most one employer-domain candidate.

On the published plan for new signups, 2 credits are settled only for `status: valid`, a non-catch-all business address
with a current check and an employer-domain association. Discovery includes
verification, with no validation surcharge or implicit profile charge. `no_data`,
`unverified`, `catch_all`, `unknown` and `unavailable` cost zero. An explicitly
requested employer-associated business candidate may be returned as
`status: unverified`, with a clear UNVERIFIED label. Email assessment,
verification status, catch-all uncertainty and assessment dates remain separate.
Never treat an unknown catch-all verdict as false. Known-invalid, personal,
disposable and unrelated-domain candidates are withheld. This does not prove
ownership or delivery.

The 24-hour discovery receipt is shared with `get_person_profile` including `work_email`.
Use `dry_run: true` for a maximum estimate with no data lookup, and `max_credits` to
bound a real request. See [email outcomes](https://docs.datalayer.so/work-email.md) and [safe retries](https://docs.datalayer.so/api-reference/usage.md).


## OpenAPI

````yaml POST /v1/email/find
openapi: 3.1.0
info:
  title: Datalayer API
  version: '2026-10-19'
  description: >-
    People and Company intelligence. New accounts receive 100 one-time trial
    credits for 14 days, no card or automatic refill. The published plan for new
    signups is USD 49/month for 1,500 shared credits with monthly expiry and no
    rollover. USD 39 manual packs buy 1,000 credits valid for 12 months,
    available to active paid subscribers. An earlier purchase keeps the
    allowance, rates and expiry recorded for that purchase. On the published
    plan, a company or people search with results costs 1 credit, and an empty
    or failed search costs zero. get_account_details and saved viewing cost
    zero. Delivered company/person profiles with requested available context
    cost one credit. A verified work email costs 2 credits, including
    verification; standalone discovery has no implicit profile charge.
    Unverified employer-associated business candidates are explicitly labelled,
    retain independent assessment and catch-all evidence, and cost zero email
    credits. Conclusive valid OR invalid standalone email checks cost one;
    catch-all/unknown/unavailable cost zero. find_job_postings costs 1 credit
    when a successful page returns at least one posting, and zero for an empty
    page or a failure. That rate does not change any other rate. get_tech_stack
    costs 1 credit when the returned page lists at least one technology, and
    zero when that page is empty or the call fails. The same domain, after a
    leading www. is removed, repeats free for 24 hours. find_sites_using_tech
    costs 1 credit when a page returns at least one site, and zero when that
    page is empty or the call fails. The identical slug, limit and offset repeat
    free for 24 hours. list_technologies costs zero and returns one cached
    directory page. These rates do not change any other rate.
    get_company_profile does not include a technology summary. Eligible
    purchased-result repeats and added profile context cost zero for 24 hours
    from the paid anchor. Former profile quantities are the same number of
    credits. REST and MCP use the same authoritative account ledger. List filter
    lookup and preview cost zero credits and do not return billable record IDs.
    build_list reserves 1 credit per 100 requested IDs, rounded up, at most
    10000 IDs, and settles on the IDs returned. Empty or failed lists release
    the reservation. Full profile enrichment stays at the existing profile
    price. Funding, mobile/app data and monitoring are excluded.
servers:
  - url: https://api.datalayer.so
    description: Production API
security:
  - bearerAuth: []
paths:
  /v1/email/find:
    post:
      summary: find work email
      description: >-
        Only explicitly requested contact research runs discovery/verification.
        Check evidence, source dates and email outcomes; unknown source dates
        stay null. All operations accept dry_run and max_credits.
      operationId: find_work_email
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/find_work_emailInput'
      responses:
        '200':
          description: A settled result or a maximum estimate with no data lookup.
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    required:
                      - data
                      - meta
                    properties:
                      data:
                        $ref: '#/components/schemas/find_work_emailData'
                      meta:
                        $ref: '#/components/schemas/UsageMetadata'
                    additionalProperties: false
                  - type: object
                    required:
                      - data
                      - meta
                    properties:
                      data:
                        $ref: '#/components/schemas/CreditEstimate'
                      meta:
                        $ref: '#/components/schemas/UsageMetadata'
                    additionalProperties: false
        '400':
          description: Invalid input or idempotency key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized, disconnected or revoked credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: No active allowance, credit budget or available credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No matching identity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            Ambiguous/mismatched identity, changed/expired key or request in
            progress
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Request exceeds 16KB
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Account rate limit: 60/minute'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Lookup or normalized contract failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Unavailable, cancelled or settlement interrupted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '504':
          description: Lookup or search timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Recommended for every paid operation. Account-scoped and bound to
        normalized operation/input. Retry exactly the same key after transport
        loss: a committed credit result is replayed from persisted normalized
        bytes without a data lookup or another debit. Changed input, key expiry
        or paid-anchor expiry returns 409. In-flight requests return
        request_in_progress. Network delivery and D1 commit are not atomic. If
        omitted a request ID is created.
      schema:
        type: string
        pattern: ^[A-Za-z0-9_-]{1,128}$
        minLength: 1
        maxLength: 128
  schemas:
    find_work_emailInput:
      type: object
      properties:
        person_id:
          type: string
          pattern: ^[1-9][0-9]{0,19}$
        profile_url:
          type: string
          maxLength: 2000
          format: uri
        max_credits:
          description: >-
            Advanced: highest number of credits this call may spend. The call is
            refused before any lookup when the estimate is higher.
          type: integer
          minimum: 0
          maximum: 3
        dry_run:
          description: >-
            Advanced: return the maximum credit estimate without looking up
            data.
          type: boolean
      additionalProperties: false
      oneOf:
        - required:
            - person_id
        - required:
            - profile_url
    find_work_emailData:
      type: object
      properties:
        status:
          type: string
          enum:
            - not_requested
            - valid
            - unverified
            - invalid
            - catch_all
            - unknown
            - unavailable
            - no_data
        email:
          anyOf:
            - type: string
              maxLength: 254
              format: email
              pattern: >-
                ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
            - type: 'null'
        person_id:
          anyOf:
            - type: string
              pattern: ^[1-9][0-9]{0,19}$
            - type: 'null'
        employer_domain:
          anyOf:
            - type: string
              pattern: ^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$
            - type: 'null'
        employer_domain_match:
          type:
            - boolean
            - 'null'
        checked_at:
          anyOf:
            - type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            - type: 'null'
        is_catch_all:
          type:
            - boolean
            - 'null'
        verification_status:
          default: not_checked
          type: string
          enum:
            - not_checked
            - valid
            - invalid
            - catch_all
            - unknown
            - unavailable
        provider_assessment:
          default: null
          deprecated: true
          description: Deprecated. Read email_assessment. The value is the same.
          anyOf:
            - type: string
              enum:
                - valid
                - ambiguous
                - maybe_valid
                - invalid
                - malformed
                - uncached
                - temp_error
                - perm_error
            - type: 'null'
        email_assessment:
          description: Email assessment. Prefer this field. It matches provider_assessment.
          anyOf:
            - type: string
              enum:
                - valid
                - ambiguous
                - maybe_valid
                - invalid
                - malformed
                - uncached
                - temp_error
                - perm_error
            - type: 'null'
        discovery_assessment:
          default: null
          anyOf:
            - type: string
              enum:
                - valid
                - ambiguous
                - maybe_valid
                - invalid
                - malformed
                - uncached
                - temp_error
                - perm_error
            - type: 'null'
        provider_checked_at:
          default: null
          deprecated: true
          description: Deprecated. Read assessment_checked_at. The value is the same.
          anyOf:
            - type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            - type: 'null'
        assessment_checked_at:
          description: >-
            When the email assessment was checked. Prefer this field. It matches
            provider_checked_at.
          anyOf:
            - type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            - type: 'null'
        evidence:
          default: null
          anyOf:
            - type: object
              properties:
                source:
                  type: string
                  maxLength: 200
                source_url:
                  anyOf:
                    - type: string
                      maxLength: 2000
                      format: uri
                    - type: 'null'
                source_updated_at:
                  anyOf:
                    - type: string
                      maxLength: 10000
                    - type: 'null'
                retrieved_at:
                  type: string
                  format: date-time
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                coverage_note:
                  type: string
                  maxLength: 2000
              required:
                - source
                - source_url
                - source_updated_at
                - retrieved_at
                - coverage_note
              additionalProperties: false
            - type: 'null'
        note:
          type: string
          maxLength: 2000
      required:
        - status
        - email
        - person_id
        - employer_domain
        - employer_domain_match
        - checked_at
        - is_catch_all
        - verification_status
        - provider_assessment
        - discovery_assessment
        - provider_checked_at
        - evidence
        - note
      additionalProperties: false
    UsageMetadata:
      type: object
      required:
        - retrieved_at
        - billing_status
        - profiles_used
      properties:
        request_id:
          type: string
        contract_version:
          const: '2026-10-19'
        credit_version:
          type: string
          enum:
            - datalayer_credits_v1
            - datalayer_credits_v2
        retrieved_at:
          type: string
          format: date-time
        upstream_requests:
          type: integer
          minimum: 0
          maximum: 8
          deprecated: true
          description: Deprecated. Read lookup_requests. The count is the same.
        lookup_requests:
          type: integer
          minimum: 0
          maximum: 8
          description: >-
            Lookup calls for this response. Prefer this field. It matches
            upstream_requests. Zero on replay.
        billing_status:
          type: string
          enum:
            - credits_settled
            - estimate_included
            - search_included
            - profile_deducted
            - repeat_included
            - idempotent_replay
        credits_used:
          type: integer
          minimum: 0
          maximum: 3
          description: >-
            Credits newly deducted by this invocation. Zero on replay. Not the
            remaining balance.
        profiles_used:
          type: integer
          minimum: 0
          maximum: 1
          deprecated: true
          description: >-
            Deprecated. Credit responses report credits_used and set this to 0.
            Older clients may still read it.
        receipt:
          $ref: '#/components/schemas/CreditReceipt'
        replayed:
          type: boolean
      additionalProperties: false
    CreditEstimate:
      type: object
      properties:
        contract_version:
          type: string
          const: '2026-10-19'
        credit_version:
          type: string
          enum:
            - datalayer_credits_v1
            - datalayer_credits_v2
        maximum_credits:
          type: integer
          minimum: 0
          maximum: 100
        minimum_credits:
          type: number
          const: 0
        provider_calls:
          type: number
          const: 0
          deprecated: true
          description: Deprecated. Read lookup_calls. The value is the same.
        lookup_calls:
          description: >-
            Lookup calls in this estimate. Prefer this field. It matches
            provider_calls and is 0 because an estimate makes no lookup.
          type: number
          const: 0
        repeat_window_hours:
          type: number
          const: 24
        note:
          type: string
      required:
        - contract_version
        - credit_version
        - maximum_credits
        - minimum_credits
        - provider_calls
        - repeat_window_hours
        - note
      additionalProperties: false
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
          additionalProperties: false
      additionalProperties: false
    CreditReceipt:
      type: object
      properties:
        version:
          type: string
          enum:
            - datalayer_credits_v1
            - datalayer_credits_v2
        request_id:
          type: string
          minLength: 1
          maxLength: 128
        reserved:
          type: integer
          minimum: 0
          maximum: 100
        settled:
          type: integer
          minimum: 0
          maximum: 100
        released:
          type: integer
          minimum: 0
          maximum: 100
        items:
          maxItems: 100
          type: array
          items:
            type: object
            properties:
              kind:
                type: string
                enum:
                  - company
                  - person
                  - work_email
                  - validation
                  - jobs_search
                  - tech_stack
                  - tech_sites
                  - segment_export
                  - company_search
                  - people_search
              reference:
                type: string
                maxLength: 254
              credits:
                anyOf:
                  - type: number
                    const: 0
                  - type: number
                    const: 1
                  - type: number
                    const: 2
              repeat:
                type: boolean
            required:
              - kind
              - reference
              - credits
              - repeat
            additionalProperties: false
      required:
        - version
        - request_id
        - reserved
        - settled
        - released
        - items
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Datalayer API key
      description: >-
        Send Authorization: Bearer dl_live_<64 lowercase hexadecimal
        characters>. Signed-in users can create account-scoped, revocable keys
        in the Datalayer dashboard. A key does not grant credits. Dashboard
        session cookies are not API credentials.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.