Enrich Lead Finder API

openapi: 3.1.0
info:
  title: Enrich Lead Finder API
  description: 'Search, count, reveal, enrich, unlock and export leads across people and organizations,
    with saved searches and async reveal/export jobs.


    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: Lead Finder
paths:
  /lead-finder/count:
    post:
      summary: Count matching leads
      deprecated: false
      description: Get the total count of leads matching your filters. This endpoint is free and does
        not consume credits.
      operationId: countLeads
      tags:
      - Lead Finder
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadCountRequest'
      responses:
        '200':
          description: Count returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadCountResponse'
              example:
                success: true
                data:
                  count: 18420
                  searchType: unified
                  searchedTotalResult: 18420
                meta:
                  requestId: req_664f2b3c9a1e4d0012abcdf0
          headers:
            X-RateLimit-Limit:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Remaining:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Reset:
              required: false
              description: ''
              schema:
                type: string
        '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 Invalid request
                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: {}
        '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:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Limit:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Remaining:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Reset:
              required: false
              description: ''
              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-28165854-run
  /lead-finder/enrich:
    post:
      summary: Enrich contacts with specific fields
      deprecated: false
      description: 'Reveal specific contact fields (email and/or phone) for up to 25 leads.


        **Pricing:**

        - Email: 10 credits per lead

        - Phone: 525 credits per lead


        Previously revealed fields are returned from cache at no cost.


        **Async:** Returns a `jobId` immediately (< 100ms). Poll `GET /lead-finder/reveal-jobs/:jobId`
        every 2 seconds until `status` is `completed` or `failed`. Credits are charged inside the worker
        — insufficient credits cause the job to fail asynchronously (no synchronous 402).'
      operationId: enrichLeads
      tags:
      - Lead Finder
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadEnrichRequest'
      responses:
        '200':
          description: Enrich job submitted — poll the returned jobId for results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevealJobSubmitResponse'
              example:
                success: true
                data:
                  jobId: rj_a1b2c3d4e5f6g7h8
                  status: pending
                  totalLeads: 3
                  fields:
                  - email
                  message: Enrich job submitted. Poll GET /api/v3/lead-finder/reveal-jobs/rj_a1b2c3d4e5f6g7h8
                    for results.
                meta:
                  requestId: req_664f2b3c9a1e4d0012abcdf3
          headers:
            X-RateLimit-Limit:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Remaining:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Reset:
              required: false
              description: ''
              schema:
                type: string
        '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 Invalid request
                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: {}
        '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:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Limit:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Remaining:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Reset:
              required: false
              description: ''
              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-28165857-run
  /lead-finder/export:
    post:
      summary: Export leads to CSV (async)
      deprecated: false
      description: 'Submit an async CSV export job. Returns a `jobId` immediately — poll `GET /lead-finder/export-jobs/{jobId}`
        for status. Once the job reaches `completed` status, download the file via `GET /lead-finder/export-jobs/{jobId}/download`.


        Credits are estimated upfront and deducted during processing. Refunds are issued for leads where
        the requested contact info was not found.


        **Pricing:**

        - Preview fields only: Free

        - `includeEmail`: 10 credits per lead

        - `includePhone`: 525 credits per lead

        - `includeNames`: 1 credit per lead (full last names)

        - `includeContactInfo`: Shorthand for email + phone (535 credits/lead)'
      operationId: exportLeads
      tags:
      - Lead Finder
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadExportRequest'
            example:
              filters:
                jobLevel:
                - C-Suite
                - VP
                domain:
                - stripe.com
                - vercel.com
              maxResults: 500
              includeEmail: true
              includeNames: true
      responses:
        '200':
          description: Export job submitted — poll for status using the returned jobId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncExportResponse'
              example:
                success: true
                data:
                  jobId: ej_a1b2c3d4e5f6a7b8
                  status: pending
                  estimatedRows: 500
                  estimatedCredits: 25000
                  message: Export job queued. Poll GET /lead-finder/export-jobs/ej_a1b2c3d4e5f6a7b8 for
                    status.
                meta:
                  requestId: 665d2f8b9c5b2a0015d0bc0f
          headers:
            X-RateLimit-Limit:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Remaining:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Reset:
              required: false
              description: ''
              schema:
                type: string
        '400':
          description: Something is wrong with the request — check the `detail` field for specifics
          content:
            application/json:
              schema: &id003
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                type: https://dev.enrich.so/errors/validation-error
                title: Validation Error
                status: 400
                detail: body Invalid request
                instance: /requests/3fa85f64-5717-4562-b3fc-2c963f66afa6
          headers: {}
        '401':
          description: Your API key is missing or invalid
          content:
            application/json:
              schema: *id003
              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: *id003
              example:
                type: https://dev.enrich.so/errors/insufficient-credits
                title: Insufficient Credits
                status: 402
                detail: 'Not enough credits. Required: 575, available: 100'
          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:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Limit:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Remaining:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Reset:
              required: false
              description: ''
              schema:
                type: string
        '500':
          description: Something went wrong on our end — try again in a moment
          content:
            application/json:
              schema: *id003
              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-28165855-run
  /lead-finder/export-jobs:
    get:
      summary: List export jobs
      deprecated: false
      description: List recent CSV export jobs for your team (last 30 days). Paginated, optionally filtered
        by status.
      operationId: listExportJobs
      tags:
      - Lead Finder
      parameters:
      - 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: 20, max: 100)'
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: status
        in: query
        description: Filter by job status
        required: false
        schema:
          type: string
          enum:
          - pending
          - processing
          - completed
          - failed
      responses:
        '200':
          description: Paginated list of export jobs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadExportJobListResponse'
              example:
                success: true
                data:
                  jobs:
                  - jobId: ej_a1b2c3d4e5f6a7b8
                    status: completed
                    total: 500
                    processed: 500
                    creditsUsed: 24750
                    creditsRefunded: 250
                    createdAt: '2025-06-03T14:30:00.000Z'
                    completedAt: '2025-06-03T14:35:00.000Z'
                  total: 1
                  page: 1
                  limit: 20
          headers:
            X-RateLimit-Limit:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Remaining:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Reset:
              required: false
              description: ''
              schema:
                type: string
        '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: {}
        '429':
          description: You've sent too many requests — wait and try again
          content:
            application/json:
              schema: *id004
          headers:
            Retry-After:
              required: false
              description: ''
              schema:
                type: string
        '500':
          description: Something went wrong on our end — try again in a moment
          content:
            application/json:
              schema: *id004
          headers: {}
      security:
      - ApiKeyHeader: []
      x-run-in-apidog: https://app.apidog.com/web/project/1189032/apis/api-29249239-run
  /lead-finder/export-jobs/{jobId}:
    get:
      summary: Poll export job status
      deprecated: false
      description: 'Poll the status of a CSV export job. The response shape varies by status:


        - **`pending`** — Job is queued, not yet started.

        - **`processing`** — Job is actively running. Check `progress` for completion percentage.

        - **`completed`** — Job finished successfully. Includes `results` with final credit usage. Download
        the file via `GET /lead-finder/export-jobs/{jobId}/download`.

        - **`failed`** — Job encountered an error. Includes `error` message and any `creditsRefunded`.'
      operationId: getExportJob
      tags:
      - Lead Finder
      parameters:
      - name: jobId
        in: path
        description: 'Export job ID (format: `ej_` followed by 16 hex characters)'
        required: true
        example: ''
        schema:
          type: string
          pattern: ^ej_[a-f0-9]{16}$
          examples:
          - ej_a1b2c3d4e5f6a7b8
      responses:
        '200':
          description: Export job status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadExportJobStatusResponse'
              examples:
                pending:
                  summary: Job is pending
                  value:
                    success: true
                    data:
                      jobId: ej_a1b2c3d4e5f6a7b8
                      status: pending
                      progress:
                        processed: 0
                        total: 500
                      createdAt: '2025-06-03T14:30:00.000Z'
                processing:
                  summary: Job is in progress
                  value:
                    success: true
                    data:
                      jobId: ej_a1b2c3d4e5f6a7b8
                      status: processing
                      progress:
                        processed: 250
                        total: 500
                      createdAt: '2025-06-03T14:30:00.000Z'
                completed:
                  summary: Job completed successfully
                  value:
                    success: true
                    data:
                      jobId: ej_a1b2c3d4e5f6a7b8
                      status: completed
                      progress:
                        processed: 500
                        total: 500
                      results:
                        totalExported: 500
                        creditsUsed: 24750
                        creditsRefunded: 250
                      createdAt: '2025-06-03T14:30:00.000Z'
                      completedAt: '2025-06-03T14:35:00.000Z'
                failed:
                  summary: Job failed
                  value:
                    success: true
                    data:
                      jobId: ej_a1b2c3d4e5f6a7b8
                      status: failed
                      error: An unexpected error occurred during export.
                      creditsRefunded: 25000
                      createdAt: '2025-06-03T14:30:00.000Z'
          headers:
            X-RateLimit-Limit:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Remaining:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Reset:
              required: false
              description: ''
              schema:
                type: string
        '401':
          description: Your API key is missing or invalid
          content:
            application/json:
              schema: &id005
                $ref: '#/components/schemas/ErrorEnvelope'
          headers: {}
        '404':
          description: Export job not found or does not belong to your team
          content:
            application/json:
              schema: *id005
              example:
                type: https://dev.enrich.so/errors/not-found
                title: Not Found
                status: 404
                detail: Export job not found
          headers: {}
        '429':
          description: You've sent too many requests — wait and try again
          content:
            application/json:
              schema: *id005
          headers:
            Retry-After:
              required: false
              description: ''
              schema:
                type: string
        '500':
          description: Something went wrong on our end — try again in a moment
          content:
            application/json:
              schema: *id005
          headers: {}
      security:
      - ApiKeyHeader: []
      x-run-in-apidog: https://app.apidog.com/web/project/1189032/apis/api-29249240-run
  /lead-finder/export-jobs/{jobId}/download:
    get:
      summary: Download export CSV
      deprecated: false
      description: 'Stream the completed CSV file for an export job. Returns the file with `Content-Type:
        text/csv`.


        Returns **409 Conflict** if the job has not yet reached `completed` status or has failed. Poll
        `GET /lead-finder/export-jobs/{jobId}` first to confirm the job is complete before downloading.'
      operationId: downloadExportJob
      tags:
      - Lead Finder
      parameters:
      - name: jobId
        in: path
        description: 'Export job ID (format: `ej_` followed by 16 hex characters)'
        required: true
        example: ''
        schema:
          type: string
          pattern: ^ej_[a-f0-9]{16}$
          examples:
          - ej_a1b2c3d4e5f6a7b8
      responses:
        '200':
          description: CSV file stream
          content:
            text/csv:
              schema:
                type: string
              example: 'First Name,Last Name,Job Title,Company Name,Domain,...

                Sarah,Chen,VP of Engineering,Stripe,stripe.com,...'
          headers:
            Content-Disposition:
              required: false
              description: Suggests a filename for the downloaded file, e.g. `attachment; filename="export-ej_a1b2c3d4e5f6a7b8.csv"`
              schema:
                type: string
            X-Credits-Used:
              required: false
              description: Total credits consumed for this export
              schema:
                type: string
            X-Credits-Refunded:
              required: false
              description: Credits refunded for leads where contact info was not found
              schema:
                type: string
        '401':
          description: Your API key is missing or invalid
          content:
            application/json:
              schema: &id006
                $ref: '#/components/schemas/ErrorEnvelope'
          headers: {}
        '404':
          description: Export job not found or does not belong to your team
          content:
            application/json:
              schema: *id006
              example:
                type: https://dev.enrich.so/errors/not-found
                title: Not Found
                status: 404
                detail: Export job not found
          headers: {}
        '409':
          description: Job is not yet completed or has failed — cannot download
          content:
            application/json:
              schema: *id006
              example:
                type: https://dev.enrich.so/errors/conflict
                title: Conflict
                status: 409
                detail: 'Export job is not yet completed. Current status: processing'
          headers: {}
        '429':
          description: You've sent too many requests — wait and try again
          content:
            application/json:
              schema: *id006
          headers:
            Retry-After:
              required: false
              description: ''
              schema:
                type: string
        '500':
          description: Something went wrong on our end — try again in a moment
          content:
            application/json:
              schema: *id006
          headers: {}
      security:
      - ApiKeyHeader: []
      x-run-in-apidog: https://app.apidog.com/web/project/1189032/apis/api-29249241-run
  /lead-finder/filter-options:
    get:
      summary: Get filter options
      deprecated: false
      description: Returns available values for multi-select filter fields (countries, departments, industries,
        job functions, etc.). Values are fetched from the database and cached for performance. Free endpoint.
      operationId: getFilterOptions
      tags:
      - Lead Finder
      parameters: []
      responses:
        '200':
          description: Filter options returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadFinderFilterOptionsResponse'
              example:
                success: true
                data:
                  countryName:
                  - United States
                  - United Kingdom
                  - Germany
                  - '...'
                  jobFunction:
                  - Engineering
                  - Marketing
                  - Sales
                  - '...'
                  jobLevel:
                  - C-Suite
                  - VP
                  - Director
                  - Manager
                  - '...'
                  industrySicDescription:
                  - Computer Processing & Data Preparation
                  - '...'
                meta:
                  requestId: req_664f2b3c9a1e4d0012abcdf8
          headers:
            X-RateLimit-Limit:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Remaining:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Reset:
              required: false
              description: ''
              schema:
                type: string
        '400':
          description: Something is wrong with the request — check the `detail` field for specifics
          content:
            application/json:
              schema: &id007
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                type: https://dev.enrich.so/errors/validation-error
                title: Validation Error
                status: 400
                detail: body Invalid request
                instance: /requests/3fa85f64-5717-4562-b3fc-2c963f66afa6
          headers: {}
        '401':
          description: Your API key is missing or invalid
          content:
            application/json:
              schema: *id007
              example:
                type: https://dev.enrich.so/errors/unauthorized
                title: Unauthorized
                status: 401
                detail: The API key provided is invalid or has been revoked
          headers: {}
        '429':
          description: You've sent too many requests — wait and try again
          content:
            application/json:
              schema: *id007
              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:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Limit:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Remaining:
              required: false
              description: ''
              schema:
                type: string
            X-RateLimit-Reset:
              required: false
              description: ''
              schema:
                type: string
        '500':
          description: Something went wrong on our end — try again in a moment
          content:
            application/json:
              schema: *id007
              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-28165862-run
  /lead-finder/reveal:
    post:
      summary: Reveal contact info
      deprecated: false
      description: 'Reveal contact info for up to 25 leads. Choose which fields to reveal via the optional
        `fields` parameter:


        - `["email"]` — 10 credits per lead

        - `["phone"]` — 525 credits per lead

        - `["email", "phone"]` — 535 credits per lead (default if omitted)


        Previously revealed contacts are returned from cache at no cost.


        **Async:** Returns a `jobId` immediately (< 100ms). Poll `GET /lead-finder/reveal-jobs/:jobId`
        every 2 seconds until `status` is `completed` or `failed`. Credits are charged inside the worker
        — insufficient credits cause the job to fail asynchronously (no synchronous 402).'
      operationId: revealLeads
      tags:
      - Lead Finder
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadRevealRequest'
            example:
              leads:
              - id: enc_abc123def456
              fields:
              - email
      responses:
        '200':
          description: Reveal job submitted — poll the returned jobId for results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevealJobSubmitResponse'
              example:
                success: true
                data:
                  jobId: rj_a1b2c3d4e5f6g7h8
                  status: pending
                  totalLeads: 1
                  fields:
                  - email
                  message: Reveal job submitted. Poll GET /api/v3/lead-finder/reveal-jobs/rj_a1b2c3d4e5f6g7h8
                    for results.
                meta:
                  requestId: req_664f2b3c9a1e4d0012abcdf2
          headers:
            X-RateLimit-Limit:
              required: false
              description: ''
              schema:
                type: string
            X-RateLi

# --- truncated at 32 KB (128 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/enrich-so/refs/heads/main/openapi/enrich-so-lead-finder-api-openapi.yml