Enrich Email Finder API

openapi: 3.2.0
info:
  title: Enrich So Email Finder API
  version: '3.0'
  contact:
    name: Enrich
    url: https://www.enrich.so
  description: 'Operations tagged Email Finder across 2 of this provider''s published API definitions: enrich-so-openapi.yml, enrich-so-v3-harvested-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://dev.enrich.so/api/v3
  description: Enrich API v3
tags:
- name: Email Finder
  description: Find a professional email from a name and company domain.
paths:
  /email-finder:
    post:
      operationId: findProfessionalEmail
      tags:
      - Email Finder
      summary: Find a professional email
      description: Finds a person's professional email address from first name, last name, and company domain. 10 credits per successful find; not charged when found is false.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailFinderRequest'
      responses:
        '200':
          description: Email found (or found=false).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailFinderResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
      - apiKeyHeader: []
      - bearerAuth: []
    servers:
    - url: https://dev.enrich.so/api/v3
      description: Enrich API v3
  /email-finder/batch:
    post:
      operationId: findEmailsBatch
      tags:
      - Email Finder
      summary: Find emails in batch
      description: Submits multiple name+domain rows for asynchronous email finding.
      x-endpoint-modeled: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchEmailFinderRequest'
      responses:
        '202':
          description: Batch accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchSubmitResponse'
      security:
      - apiKeyHeader: []
      - bearerAuth: []
    servers:
    - url: https://dev.enrich.so/api/v3
      description: Enrich API v3
  /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: {}
          x-apidog-name: OK
        '401':
          description: Your API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope_2'
              example:
                type: https://dev.enrich.so/errors/unauthorized
                title: Unauthorized
                status: 401
                detail: The API key provided is invalid or has been revoked
          headers: {}
          x-apidog-name: Unauthorized
        '404':
          description: The resource you requested doesn't exist or doesn't belong to your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope_2'
              example:
                type: https://dev.enrich.so/errors/not-found
                title: Not Found
                status: 404
                detail: No batch found with that ID
          headers: {}
          x-apidog-name: Not Found
        '429':
          description: You've sent too many requests — wait and try again
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope_2'
              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
          x-apidog-name: Too Many Requests
      security:
      - ApiKeyHeader: []
        x-apidog:
          schemeGroups:
          - id: ITulbGf-iaBy1jastxLFZ
            schemeIds:
            - ApiKeyHeader
          - id: MRl9ot_U0Hi0CGtsoDsHI
            schemeIds:
            - BearerToken
          required: true
          use:
            id: ITulbGf-iaBy1jastxLFZ
          scopes:
            MRl9ot_U0Hi0CGtsoDsHI: {}
      x-apidog-folder: Email Finder
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/1189032/apis/api-27483197-run
    servers:
    - url: https://dev.enrich.so/api/v3
      description: Enrich API v3 (base URL published at https://doc.enrich.so/api-reference-1951025m0)
  /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: {}
          x-apidog-name: OK
        '401':
          description: Your API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope_2'
              example:
                type: https://dev.enrich.so/errors/unauthorized
                title: Unauthorized
                status: 401
                detail: The API key provided is invalid or has been revoked
          headers: {}
          x-apidog-name: Unauthorized
        '404':
          description: The resource you requested doesn't exist or doesn't belong to your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope_2'
              example:
                type: https://dev.enrich.so/errors/not-found
                title: Not Found
                status: 404
                detail: No batch found with that ID
          headers: {}
          x-apidog-name: Not Found
        '429':
          description: You've sent too many requests — wait and try again
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope_2'
              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
          x-apidog-name: Too Many Requests
      security:
      - ApiKeyHeader: []
        x-apidog:
          schemeGroups:
          - id: ITulbGf-iaBy1jastxLFZ
            schemeIds:
            - ApiKeyHeader
          - id: MRl9ot_U0Hi0CGtsoDsHI
            schemeIds:
            - BearerToken
          required: true
          use:
            id: ITulbGf-iaBy1jastxLFZ
          scopes:
            MRl9ot_U0Hi0CGtsoDsHI: {}
      x-apidog-folder: Email Finder
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/1189032/apis/api-27483198-run
    servers:
    - url: https://dev.enrich.so/api/v3
      description: Enrich API v3 (base URL published at https://doc.enrich.so/api-reference-1951025m0)
components:
  schemas:
    BatchEmailFinderRequest:
      type: object
      required:
      - rows
      properties:
        rows:
          type: array
          items:
            $ref: '#/components/schemas/EmailFinderRequest'
    EnrichmentMeta:
      type: object
      description: Metadata returned with every response, including remaining credit balance.
      properties:
        creditsCharged:
          type: integer
        creditsRemaining:
          type: integer
        cached:
          type: boolean
    EmailFinderRequest:
      type: object
      required:
      - firstName
      - lastName
      - domain
      properties:
        firstName:
          type: string
        lastName:
          type: string
        domain:
          type: string
          description: Company domain, e.g. figma.com.
    EmailFinderResponse:
      type: object
      properties:
        success:
          type: boolean
        meta:
          $ref: '#/components/schemas/EnrichmentMeta'
        data:
          type: object
          properties:
            found:
              type: boolean
            email:
              type: string
              format: email
            confidence:
              type: number
    ErrorEnvelope:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
    BatchSubmitResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            batchId:
              type: string
            status:
              type: string
    BatchEmailFinderRequest_2:
      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
      x-apidog-orders:
      - leads
      - webhookUrl
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    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
          x-apidog-orders:
          - requestId
          x-apidog-ignore-properties: []
      x-apidog-orders:
      - success
      - data
      - meta
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    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
      x-apidog-orders:
      - firstName
      - lastName
      - domain
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    EmailFinderRequest_2:
      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
      x-apidog-orders:
      - firstName
      - lastName
      - domain
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    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
      x-apidog-orders:
      - batchId
      - status
      - totalItems
      - processedItems
      - progress
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    EmailFinderResponse_2:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/EmailFinderResult'
        meta:
          $ref: '#/components/schemas/EnrichmentMeta_2'
      x-apidog-orders:
      - success
      - data
      - meta
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    ErrorEnvelope_2:
      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
      x-apidog-orders:
      - type
      - title
      - status
      - detail
      - instance
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    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
      x-apidog-orders:
      - batchId
      - status
      - itemCount
      - originalCount
      - duplicatesRemoved
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    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
          x-apidog-orders:
          - batchId
          - status
          - totalItems
          - processedCount
          - results
          x-apidog-ignore-properties: []
        meta:
          $ref: '#/components/schemas/BatchResultsMeta'
      x-apidog-orders:
      - success
      - data
      - meta
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    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
      x-apidog-orders:
      - firstName
      - lastName
      - domain
      - found
      - email
      - confidence
      - isCatchAll
      - provider
      - message
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    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
      x-apidog-orders:
      - requestId
      - creditsUsed
      - creditsRefunded
      - creditsRemaining
      - totalItems
      - processedItems
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    BatchSubmitResponse_2:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/BatchSubmitData'
        meta:
          $ref: '#/components/schemas/BatchSubmitMeta'
      x-apidog-orders:
      - success
      - data
      - meta
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    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
      x-apidog-orders:
      - requestId
      - creditsReserved
      - creditsPerItem
      - estimatedCredits
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    EnrichmentMeta_2:
      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
      x-apidog-orders:
      - requestId
      - creditsUsed
      - creditsRemaining
      - processingTimeMs
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
  responses:
    InsufficientCredits:
      description: Not enough credits to complete the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Unauthorized:
      description: Missing, invalid, or disabled API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    RateLimited:
      description: Rate limit exceeded. Includes a Retry-After header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: API key (prefixed sk_) passed in the x-api-key header.
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Authorization Bearer token.
    apiKey:
      type: apikey
      name: x-api-key
      in: header
      description: 'Your API key. Keys start with `sk_live_` and are 64 characters long.

        '
    ApiKeyHeader:
      type: apikey
      in: header
      name: x-api-key
      description: API key starting with `sk_live_` (64 characters). Get yours from the [Enrich Dashboard](https://sendkit.ai/dashboard/api-keys).
    BearerToken:
      type: bearer
      scheme: bearer
      description: Same `sk_live_` key passed as a Bearer token in the Authorization header.
x-refined-from:
- enrich-so-openapi.yml
- enrich-so-v3-harvested-openapi.yml