Enrich Email Finder API

openapi: 3.1.0
info:
  title: Enrich Email Finder API
  description: 'Find a professional email from a first name, last name and company domain, single or in
    batches of up to 500,000 leads.


    Assembled verbatim from the per-endpoint OpenAPI fragments Enrich publishes on each page of https://doc.enrich.so
    — every documentation page embeds its own OpenAPI fragment, and this document is the union of the
    fragments carrying these tags, with only the components they reference.'
  version: '3.0'
  contact:
    name: Enrich
    url: https://www.enrich.so
  termsOfService: https://www.enrich.so/terms-of-service
servers:
- url: https://dev.enrich.so/api/v3
  description: Enrich API v3 production base URL, published at https://doc.enrich.so/api-reference-1951025m0
security:
- ApiKeyHeader: []
- BearerToken: []
tags:
- name: Email Finder
paths:
  /email-finder:
    post:
      summary: Find a professional email
      deprecated: false
      description: 'Give us a person''s first name, last name, and their company domain, and we''ll

        find their professional email address.


        **Cost:** 10 credits. You are **not** charged if we can''t find an email

        (`found: false`).

        '
      operationId: findEmail
      tags:
      - Email Finder
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailFinderRequest'
            example:
              firstName: Emily
              lastName: Zhang
              domain: figma.com
      responses:
        '200':
          description: Finder result returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailFinderResponse'
              example:
                success: true
                data:
                  firstName: Emily
                  lastName: Zhang
                  domain: figma.com
                  found: true
                  email: emily.zhang@figma.com
                  confidence: high
                  isCatchAll: false
                  provider: GOOGLE
                  message: Email found with high confidence
                meta:
                  requestId: 665b0a7f3e4c9200138eaf01
                  creditsUsed: 10
                  creditsRemaining: 24990
                  processingTimeMs: 912
          headers: {}
        '400':
          description: Something is wrong with the request — check the `detail` field for specifics
          content:
            application/json:
              schema: &id001
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                type: https://dev.enrich.so/errors/validation-error
                title: Validation Error
                status: 400
                detail: body/email Invalid email
                instance: /requests/3fa85f64-5717-4562-b3fc-2c963f66afa6
          headers: {}
        '401':
          description: Your API key is missing or invalid
          content:
            application/json:
              schema: *id001
              example:
                type: https://dev.enrich.so/errors/unauthorized
                title: Unauthorized
                status: 401
                detail: The API key provided is invalid or has been revoked
          headers: {}
        '402':
          description: You don't have enough credits for this request
          content:
            application/json:
              schema: *id001
              example:
                type: https://dev.enrich.so/errors/insufficient-credits
                title: Insufficient Credits
                status: 402
                detail: 'Not enough credits. Required: 10, available: 3'
          headers: {}
        '429':
          description: You've sent too many requests — wait and try again
          content:
            application/json:
              schema: *id001
              example:
                type: https://dev.enrich.so/errors/rate-limit-exceeded
                title: Too Many Requests
                status: 429
                detail: Rate limit exceeded. Please retry after 30 seconds.
          headers:
            Retry-After:
              schema:
                type: string
            X-RateLimit-Limit:
              schema:
                type: string
            X-RateLimit-Remaining:
              schema:
                type: string
            X-RateLimit-Reset:
              schema:
                type: string
        '500':
          description: Something went wrong on our end — try again in a moment
          content:
            application/json:
              schema: *id001
              example:
                type: https://dev.enrich.so/errors/internal-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred. Please try again later.
          headers: {}
      security:
      - ApiKeyHeader: []
      x-run-in-apidog: https://app.apidog.com/web/project/1189032/apis/api-27483195-run
  /email-finder/batch:
    post:
      summary: Find emails in batch
      deprecated: false
      description: "Submit up to **500 000 leads** in one request. Each lead is a combination\nof first\
        \ name, last name, and domain. We deduplicate the list\n(case-insensitive) so you are only charged\
        \ for unique leads.\n\n**Cost:** 10 credits per unique lead, reserved at submission. Unused credits\n\
        are refunded when you fetch results.\n\n### Webhook callbacks\n\nIf you include a `webhookUrl`,\
        \ your server will receive:\n\n1. **A per-result callback** each time a single lead is processed.\
        \ See\n   [emailFinderResult](#tag/Webhooks/operation/webhookEmailFinderResult) for the payload.\n\
        \n2. **A completion callback** once the entire batch is done. See\n   [emailFinderCompletion](#tag/Webhooks/operation/webhookEmailFinderCompletion)\
        \ for the payload.\n"
      operationId: batchFindEmails
      tags:
      - Email Finder
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchEmailFinderRequest'
            example:
              leads:
              - firstName: Emily
                lastName: Zhang
                domain: figma.com
              - firstName: David
                lastName: Kim
                domain: vercel.com
              - firstName: Aisha
                lastName: Johnson
                domain: cloudflare.com
              webhookUrl: https://api.yourapp.com/webhooks/enrich
      responses:
        '200':
          description: Batch submitted — credits have been reserved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchSubmitResponse'
              example:
                success: true
                data:
                  batchId: 665b12cf3e4c9200138eaf10
                  status: queued
                  itemCount: 3
                  originalCount: 3
                  duplicatesRemoved: 0
                meta:
                  requestId: 665b12cf3e4c9200138eaf0f
                  creditsReserved: 30
                  creditsPerItem: 10
                  estimatedCredits: 30
          headers: {}
        '400':
          description: Something is wrong with the request — check the `detail` field for specifics
          content:
            application/json:
              schema: &id002
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                type: https://dev.enrich.so/errors/validation-error
                title: Validation Error
                status: 400
                detail: body/email Invalid email
                instance: /requests/3fa85f64-5717-4562-b3fc-2c963f66afa6
          headers: {}
        '401':
          description: Your API key is missing or invalid
          content:
            application/json:
              schema: *id002
              example:
                type: https://dev.enrich.so/errors/unauthorized
                title: Unauthorized
                status: 401
                detail: The API key provided is invalid or has been revoked
          headers: {}
        '402':
          description: You don't have enough credits for this request
          content:
            application/json:
              schema: *id002
              example:
                type: https://dev.enrich.so/errors/insufficient-credits
                title: Insufficient Credits
                status: 402
                detail: 'Not enough credits. Required: 10, available: 3'
          headers: {}
        '429':
          description: You've sent too many requests — wait and try again
          content:
            application/json:
              schema: *id002
              example:
                type: https://dev.enrich.so/errors/rate-limit-exceeded
                title: Too Many Requests
                status: 429
                detail: Rate limit exceeded. Please retry after 30 seconds.
          headers:
            Retry-After:
              schema:
                type: string
            X-RateLimit-Limit:
              schema:
                type: string
            X-RateLimit-Remaining:
              schema:
                type: string
            X-RateLimit-Reset:
              schema:
                type: string
        '500':
          description: Something went wrong on our end — try again in a moment
          content:
            application/json:
              schema: *id002
              example:
                type: https://dev.enrich.so/errors/internal-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred. Please try again later.
          headers: {}
      security:
      - ApiKeyHeader: []
      x-run-in-apidog: https://app.apidog.com/web/project/1189032/apis/api-27483196-run
  /email-finder/batch/{batchId}:
    get:
      summary: Check batch finder progress
      deprecated: false
      description: 'Poll this endpoint to track your batch. The `status` moves through

        `queued` → `processing` → `completed` (or `failed`).


        **Cost:** Free.

        '
      operationId: getEmailFinderBatchStatus
      tags:
      - Email Finder
      parameters:
      - name: batchId
        in: path
        description: The batch identifier returned when you submitted the job
        required: true
        example: 665a1f4e2c3b7800129dce01
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Current batch status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatusResponse'
              example:
                success: true
                data:
                  batchId: 665b12cf3e4c9200138eaf10
                  status: processing
                  totalItems: 3
                  processedItems: 1
                  progress: 33.3
          headers: {}
        '401':
          description: Your API key is missing or invalid
          content:
            application/json:
              schema: &id003
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                type: https://dev.enrich.so/errors/unauthorized
                title: Unauthorized
                status: 401
                detail: The API key provided is invalid or has been revoked
          headers: {}
        '404':
          description: The resource you requested doesn't exist or doesn't belong to your organization
          content:
            application/json:
              schema: *id003
              example:
                type: https://dev.enrich.so/errors/not-found
                title: Not Found
                status: 404
                detail: No batch found with that ID
          headers: {}
        '429':
          description: You've sent too many requests — wait and try again
          content:
            application/json:
              schema: *id003
              example:
                type: https://dev.enrich.so/errors/rate-limit-exceeded
                title: Too Many Requests
                status: 429
                detail: Rate limit exceeded. Please retry after 30 seconds.
          headers:
            Retry-After:
              schema:
                type: string
            X-RateLimit-Limit:
              schema:
                type: string
            X-RateLimit-Remaining:
              schema:
                type: string
            X-RateLimit-Reset:
              schema:
                type: string
      security:
      - ApiKeyHeader: []
      x-run-in-apidog: https://app.apidog.com/web/project/1189032/apis/api-27483197-run
  /email-finder/batch/{batchId}/results:
    get:
      summary: Get batch finder results
      deprecated: false
      description: 'Retrieve the results once the batch has finished. Results are paginated.


        **Credit settlement:** On the first call after the batch reaches a terminal

        status, we settle the final credit charge. Leads where no email was found

        are not charged, and the difference is refunded.

        '
      operationId: getEmailFinderBatchResults
      tags:
      - Email Finder
      parameters:
      - name: batchId
        in: path
        description: The batch identifier returned when you submitted the job
        required: true
        example: 665a1f4e2c3b7800129dce01
        schema:
          type: string
          minLength: 1
      - name: page
        in: query
        description: 'Page number (default: 1)'
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        description: 'Results per page (default: 100, max: 1 000)'
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 100
      responses:
        '200':
          description: Paginated finder results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailFinderBatchResultsResponse'
              example:
                success: true
                data:
                  batchId: 665b12cf3e4c9200138eaf10
                  status: completed
                  totalItems: 3
                  processedCount: 3
                  results:
                  - firstName: Emily
                    lastName: Zhang
                    domain: figma.com
                    found: true
                    email: emily.zhang@figma.com
                    confidence: high
                    isCatchAll: false
                    provider: GOOGLE
                    message: Email found with high confidence
                  - firstName: David
                    lastName: Kim
                    domain: vercel.com
                    found: true
                    email: david.kim@vercel.com
                    confidence: medium
                    isCatchAll: false
                    provider: GOOGLE
                    message: Email found with medium confidence
                  - firstName: Aisha
                    lastName: Johnson
                    domain: cloudflare.com
                    found: false
                    message: No professional email could be found for this person
                meta:
                  requestId: 665b18a03e4c9200138eaf20
                  creditsUsed: 20
                  creditsRefunded: 10
                  creditsRemaining: 24970
                  totalItems: 3
                  processedItems: 3
          headers: {}
        '401':
          description: Your API key is missing or invalid
          content:
            application/json:
              schema: &id004
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                type: https://dev.enrich.so/errors/unauthorized
                title: Unauthorized
                status: 401
                detail: The API key provided is invalid or has been revoked
          headers: {}
        '404':
          description: The resource you requested doesn't exist or doesn't belong to your organization
          content:
            application/json:
              schema: *id004
              example:
                type: https://dev.enrich.so/errors/not-found
                title: Not Found
                status: 404
                detail: No batch found with that ID
          headers: {}
        '429':
          description: You've sent too many requests — wait and try again
          content:
            application/json:
              schema: *id004
              example:
                type: https://dev.enrich.so/errors/rate-limit-exceeded
                title: Too Many Requests
                status: 429
                detail: Rate limit exceeded. Please retry after 30 seconds.
          headers:
            Retry-After:
              schema:
                type: string
            X-RateLimit-Limit:
              schema:
                type: string
            X-RateLimit-Remaining:
              schema:
                type: string
            X-RateLimit-Reset:
              schema:
                type: string
      security:
      - ApiKeyHeader: []
      x-run-in-apidog: https://app.apidog.com/web/project/1189032/apis/api-27483198-run
components:
  schemas:
    BatchEmailFinderRequest:
      type: object
      required:
      - leads
      properties:
        leads:
          type: array
          minItems: 1
          maxItems: 500000
          items:
            $ref: '#/components/schemas/Lead'
          description: The list of people to search for (up to 500 000)
        webhookUrl:
          type: string
          format: uri
          description: 'A URL on your server where we should send webhook callbacks.

            You''ll receive one POST per lead, plus one final completion POST.

            '
          examples:
          - https://api.yourapp.com/webhooks/enrich
    BatchResultsMeta:
      type: object
      description: Metadata returned when you fetch batch results (includes credit settlement)
      properties:
        requestId:
          type: string
          description: Unique ID for this request
          examples:
          - 665a23bc2c3b7800129dce10
        creditsUsed:
          type: number
          minimum: 0
          description: Actual credits charged after settlement
          examples:
          - 80
        creditsRefunded:
          type: number
          minimum: 0
          description: Credits refunded (difference between reserved and actual cost)
          examples:
          - 20
        creditsRemaining:
          type: number
          minimum: 0
          description: Your remaining credit balance after settlement
          examples:
          - 24920
        totalItems:
          type: integer
          minimum: 0
          description: Total items in the batch
          examples:
          - 10
        processedItems:
          type: integer
          minimum: 0
          description: Items that were processed
          examples:
          - 10
    BatchStatusData:
      type: object
      description: Progress information for a batch job
      required:
      - batchId
      - status
      properties:
        batchId:
          type: string
          description: The batch identifier
          examples:
          - 665a1f4e2c3b7800129dce01
        status:
          type: string
          description: 'Current status: `queued`, `processing`, `completed`, or `failed`'
          examples:
          - processing
        totalItems:
          type: integer
          minimum: 0
          description: Total items in the batch
          examples:
          - 100
        processedItems:
          type: integer
          minimum: 0
          description: Items processed so far
          examples:
          - 50
        progress:
          type: number
          minimum: 0
          maximum: 100
          description: Completion percentage (0–100)
          examples:
          - 50
    BatchStatusResponse:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/BatchStatusData'
        meta:
          type: object
          properties:
            requestId:
              type: string
              description: Request tracking ID
    BatchSubmitData:
      type: object
      description: Returned when you submit any batch job
      required:
      - batchId
      - status
      - itemCount
      properties:
        batchId:
          type: string
          description: The unique identifier for this batch — use it to poll status and fetch results
          examples:
          - 665a1f4e2c3b7800129dce01
        status:
          type: string
          description: The initial status (usually `queued`)
          examples:
          - queued
        itemCount:
          type: integer
          minimum: 0
          description: Number of unique items in the batch (after deduplication)
          examples:
          - 100
        originalCount:
          type: integer
          minimum: 0
          description: How many items you submitted before deduplication
          examples:
          - 110
        duplicatesRemoved:
          type: integer
          minimum: 0
          description: How many duplicate items were removed
          examples:
          - 10
    BatchSubmitMeta:
      type: object
      description: Metadata returned when you submit a batch job
      properties:
        requestId:
          type: string
          description: Unique ID for this request
          examples:
          - 665a1f4e2c3b7800129dce00
        creditsReserved:
          type: number
          minimum: 0
          description: Total credits reserved for the batch
          examples:
          - 100
        creditsPerItem:
          type: number
          minimum: 0
          description: Cost per item
          examples:
          - 10
        estimatedCredits:
          type: number
          minimum: 0
          description: Estimated total cost (same as creditsReserved)
          examples:
          - 100
    BatchSubmitResponse:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/BatchSubmitData'
        meta:
          $ref: '#/components/schemas/BatchSubmitMeta'
    EmailFinderBatchResultsResponse:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
          required:
          - batchId
          - status
          properties:
            batchId:
              type: string
              description: The batch identifier
              examples:
              - 665b12cf3e4c9200138eaf10
            status:
              type: string
              description: Final batch status
              examples:
              - completed
            totalItems:
              type: integer
              minimum: 0
              description: Total leads in the batch
              examples:
              - 3
            processedCount:
              type: integer
              minimum: 0
              description: Leads that were processed
              examples:
              - 3
            results:
              type: array
              items:
                $ref: '#/components/schemas/EmailFinderResult'
              description: The finder results
        meta:
          $ref: '#/components/schemas/BatchResultsMeta'
    EmailFinderRequest:
      type: object
      required:
      - firstName
      - lastName
      - domain
      properties:
        firstName:
          type: string
          minLength: 1
          maxLength: 100
          description: The person's first name
          examples:
          - Emily
        lastName:
          type: string
          minLength: 1
          maxLength: 100
          description: The person's last name
          examples:
          - Zhang
        domain:
          type: string
          minLength: 1
          maxLength: 253
          description: The company domain to search (e.g. `figma.com`)
          examples:
          - figma.com
    EmailFinderResponse:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/EmailFinderResult'
        meta:
          $ref: '#/components/schemas/EnrichmentMeta'
    EmailFinderResult:
      type: object
      description: The result of searching for one person's email
      required:
      - firstName
      - lastName
      - domain
      - found
      - message
      properties:
        firstName:
          type: string
          description: The first name you searched for
          examples:
          - Emily
        lastName:
          type: string
          description: The last name you searched for
          examples:
          - Zhang
        domain:
          type: string
          description: The domain you searched
          examples:
          - figma.com
        found:
          type: boolean
          description: Whether we found an email for this person
          examples:
          - true
        email:
          type: string
          description: The email address we found (only present when `found` is `true`)
          examples:
          - emily.zhang@figma.com
        confidence:
          type: string
          enum:
          - high
          - medium
          - low
          description: How confident we are that this is the right address
          examples:
          - high
        isCatchAll:
          type: boolean
          description: Whether the domain is a catch-all (accepts any address)
          examples:
          - false
        provider:
          type: string
          description: The email provider detected for this domain (e.g. GOOGLE, MICROSOFT, ZOHO, FASTMAIL,
            PROTONMAIL)
          examples:
          - GOOGLE
        message:
          type: string
          description: A human-readable explanation
          examples:
          - Email found with high confidence
    EnrichmentMeta:
      type: object
      description: Metadata included with every enrichment response
      properties:
        requestId:
          type: string
          description: Unique ID for this request — useful for support tickets
          examples:
          - 664f2b3c9a1e4d0012abcdef
        creditsUsed:
          type: number
          minimum: 0
          description: How many credits this request consumed
          examples:
          - 10
        creditsRemaining:
          type: number
          minimum: 0
          description: Your remaining credit balance after this request
          examples:
          - 24990
        processingTimeMs:
          type: number
          description: How long the lookup took, in milliseconds
          examples:
          - 420
    ErrorEnvelope:
      type: object
      description: RFC 9457 Problem Details error response.
      required:
      - type
      - title
      - status
      properties:
        type:
          type: string
          format: uri
          description: URI reference that identifies the problem type.
          examples:
          - https://dev.enrich.so/errors/validation-error
        title:
          type: string
          description: Short, human-readable summary of the problem.
          examples:
          - Validation Error
        status:
          type: integer
          description: HTTP status code.
          examples:
          - 400
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence.
          examples:
          - body/email Invalid email
        instance:
          type: string
          description: URI reference that identifies the specific occurrence.
          examples:
          - /requests/3fa85f64-5717-4562-b3fc-2c963f66afa6
    Lead:
      type: object
      description: A single person to find an email for
      required:
      - firstName
      - lastName
      - domain
      properties:
        firstName:
          type: string
          minLength: 1
          maxLength: 100
          description: First name
          examples:
          - Emily
        lastName:
          type: string
          minLength: 1
          maxLength: 100
          description: Last name
          examples:
          - Zhang
        domain:
          type: string
          minLength: 1
          maxLength: 253
          description: Company domain
          examples:
          - figma.com
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: API key in the x-api-key header. Documented at https://doc.enrich.so/authentication-1951026m0
    BearerToken:
      type: http
      scheme: bearer
      description: 'The same API key sent as an Authorization: Bearer token.'