Enrich Phone Finder API

openapi: 3.1.0
info:
  title: Enrich Phone Finder API
  description: 'Find phone and mobile numbers for a person from an email address or profile URL, single
    or in bulk.


    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: Phone Finder
paths:
  /reverse-lookup/phones:
    get:
      summary: Find phone numbers
      deprecated: false
      description: 'Find phone numbers associated with a person''s email address or social

        profile URL. You must provide at least one of the two.


        **Cost:** 500 credits. You are **not** charged if no phone numbers are found.

        '
      operationId: phoneLookup
      tags:
      - Phone Finder
      parameters:
      - name: email
        in: query
        description: The person's email address
        required: false
        example: sarah.chen@stripe.com
        schema:
          type: string
          format: email
          maxLength: 254
      - name: linkedin
        in: query
        description: The person's profile URL
        required: false
        example: https://www.example.com/in/sarahchen
        schema:
          type: string
          maxLength: 500
      responses:
        '200':
          description: Phone numbers returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneLookupResponse'
              example:
                success: true
                data:
                  phones:
                  - '+14158009370'
                  - '+14158009371'
                meta:
                  requestId: 665c4d2a7b8e3f00149f0a01
                  creditsUsed: 500
                  creditsRemaining: 24500
                  processingTimeMs: 1340
          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: querystring/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-27483199-run
  /reverse-lookup/phones/bulk:
    post:
      summary: Find phone numbers in batch
      deprecated: false
      description: "Submit up to **500 000 items** (email addresses and/or profile URLs) for\nbulk phone\
        \ lookup. Emails are deduplicated case-insensitively; profile\nURLs are deduplicated as-is.\n\n\
        **Cost:** 10 credits per unique item, reserved upfront. At settlement,\nonly items where phones\
        \ were actually found are charged — the rest are\nrefunded.\n\n### Webhook callbacks\n\nIf you\
        \ include a `webhookUrl`, your server will receive:\n\n1. **A per-result callback** for every\
        \ item as it is processed. See\n   [phoneResult](#tag/Webhooks/operation/webhookPhoneResult) for\
        \ the payload.\n\n2. **A completion callback** when every item has been processed. See\n   [phoneCompletion](#tag/Webhooks/operation/webhookPhoneCompletion)\
        \ for the payload.\n"
      operationId: createPhoneBulkJob
      tags:
      - Phone Finder
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneBatchRequest'
            example:
              emails:
              - sarah.chen@stripe.com
              - james.rodriguez@hubspot.com
              linkedins:
              - https://www.example.com/in/priyapatel
              webhookUrl: https://api.yourapp.com/webhooks/enrich
      responses:
        '200':
          description: Bulk job submitted — credits have been reserved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneBulkJobSubmitResponse'
              example:
                success: true
                data:
                  batchId: 665c52bf7b8e3f00149f0a10
                  status: queued
                  itemCount: 3
                  message: Bulk phone lookup job created
                  originalCount: 3
                  duplicatesRemoved: 0
                meta:
                  requestId: 665c52bf7b8e3f00149f0a0f
                  creditsReserved: 1500
                  creditsPerItem: 500
                  estimatedCredits: 1500
          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-27483200-run
  /reverse-lookup/phones/bulk/{jobId}:
    get:
      summary: Check bulk phone lookup progress
      deprecated: false
      description: 'Poll this endpoint to track the job. The `progress` field is a percentage

        from 0 to 100.


        **Cost:** Free.

        '
      operationId: getPhoneBulkJobStatus
      tags:
      - Phone Finder
      parameters:
      - name: jobId
        in: path
        description: The job identifier (24-character hex string) returned when you submitted the job
        required: true
        example: 665c52bf7b8e3f00149f0a10
        schema:
          type: string
          pattern: ^[a-f0-9]{24}$
          minLength: 24
          maxLength: 24
      responses:
        '200':
          description: Current job status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneBulkJobStatusResponse'
              example:
                success: true
                data:
                  batchId: 665c52bf7b8e3f00149f0a10
                  status: processing
                  totalItems: 3
                  processedItems: 2
                  progress: 66.7
          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-27483201-run
  /reverse-lookup/phones/bulk/{jobId}/results:
    get:
      summary: Get bulk phone lookup results
      deprecated: false
      description: 'Retrieve paginated results. Each item shows the phones found (or an error

        message if the lookup failed).


        **Credit settlement:** Only items where at least one phone number was found

        are charged. Everything else is refunded.

        '
      operationId: getPhoneBulkJobResults
      tags:
      - Phone Finder
      parameters:
      - name: jobId
        in: path
        description: The job identifier (24-character hex string) returned when you submitted the job
        required: true
        example: 665c52bf7b8e3f00149f0a10
        schema:
          type: string
          pattern: ^[a-f0-9]{24}$
          minLength: 24
          maxLength: 24
      - 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 phone lookup results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneBulkJobResultsResponse'
              example:
                success: true
                data:
                  batchId: 665c52bf7b8e3f00149f0a10
                  status: completed
                  totalItems: 3
                  processedItems: 3
                  successful: 2
                  failed: 1
                  results:
                  - email: sarah.chen@stripe.com
                    phones:
                    - '+14158009370'
                  - email: james.rodriguez@hubspot.com
                    phones:
                    - '+16175551234'
                    - '+16175551235'
                  - linkedin: https://www.example.com/in/priyapatel
                    phones: []
                    error: No phone numbers found for this profile
                  page: 1
                  limit: 100
                meta:
                  requestId: 665c5aef7b8e3f00149f0a20
                  creditsUsed: 1000
                  creditsRefunded: 500
                  creditsRemaining: 23500
                  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-27483202-run
components:
  schemas:
    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
    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
    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
    PhoneBatchRequest:
      type: object
      description: 'Submit emails and/or profile URLs for bulk phone lookup.

        You must provide at least one item. The combined total cannot exceed 500 000.

        '
      properties:
        emails:
          type: array
          maxItems: 500000
          items:
            type: string
            format: email
            maxLength: 254
          description: Email addresses to look up
          examples:
          - - sarah.chen@stripe.com
            - james.rodriguez@hubspot.com
        linkedins:
          type: array
          maxItems: 500000
          items:
            type: string
            maxLength: 500
          description: Profile URLs to look up
          examples:
          - - https://www.example.com/in/priyapatel
        webhookUrl:
          type: string
          format: uri
          description: 'A URL on your server where we should send webhook callbacks.

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

            '
          examples:
          - https://api.yourapp.com/webhooks/enrich
    PhoneBulkJobResultsResponse:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
          required:
          - batchId
          - status
          properties:
            batchId:
              type: string
              examples:
              - 665c52bf7b8e3f00149f0a10
            status:
              type: string
              examples:
              - completed
            totalItems:
              type: integer
              minimum: 0
            processedItems:
              type: integer
              minimum: 0
            successful:
              type: integer
              minimum: 0
              description: Items where at least one phone was found
            failed:
              type: integer
              minimum: 0
              description: Items where no phone was found or the lookup errored
            results:
              type: array
              items:
                $ref: '#/components/schemas/PhoneBulkResultItem'
            page:
              type: integer
              minimum: 1
            limit:
              type: integer
              minimum: 1
        meta:
          $ref: '#/components/schemas/BatchResultsMeta'
    PhoneBulkJobStatusData:
      type: object
      required:
      - batchId
      - status
      properties:
        batchId:
          type: string
          examples:
          - 665c52bf7b8e3f00149f0a10
        status:
          type: string
          examples:
          - processing
        totalItems:
          type: integer
          minimum: 0
          examples:
          - 100
        processedItems:
          type: integer
          minimum: 0
          examples:
          - 50
        progress:
          type: number
          minimum: 0
          maximum: 100
          description: Completion percentage (0–100)
          examples:
          - 50
    PhoneBulkJobStatusResponse:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/PhoneBulkJobStatusData'
        meta:
          type: object
          properties:
            requestId:
              type: string
    PhoneBulkJobSubmitData:
      type: object
      description: Returned when you submit a bulk phone lookup job
      required:
      - batchId
      - status
      - itemCount
      properties:
        batchId:
          type: string
          description: The job identifier — use it to poll status and fetch results
          examples:
          - 665c52bf7b8e3f00149f0a10
        status:
          type: string
          examples:
          - queued
        itemCount:
          type: integer
          minimum: 0
          description: Unique items in the job (after deduplication)
          examples:
          - 100
        message:
          type: string
          examples:
          - Bulk phone lookup job created
        originalCount:
          type: integer
          minimum: 0
          description: How many items you submitted before deduplication
          examples:
          - 110
        duplicatesRemoved:
          type: integer
          minimum: 0
          description: How many duplicates were removed
          examples:
          - 10
    PhoneBulkJobSubmitResponse:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/PhoneBulkJobSubmitData'
        meta:
          $ref: '#/components/schemas/BatchSubmitMeta'
    PhoneBulkResultItem:
      type: object
      description: One result from a bulk phone lookup
      properties:
        email:
          type: string
          description: The email address that was looked up (if the item was an email)
          examples:
          - sarah.chen@stripe.com
        linkedin:
          type: string
          description: The profile URL that was looked up (if the item was a profile URL)
          examples:
          - https://www.example.com/in/priyapatel
        phones:
          type: array
          items:
            type: string
          description: Phone numbers found for this person (empty if none found)
          examples:
          - - '+14158009370'
        error:
          type: string
          description: An error message if the lookup failed for this item
          examples:
          - No phone numbers found for this profile
    PhoneLookupResponse:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/PhoneLookupResult'
        meta:
          $ref: '#/components/schemas/EnrichmentMeta'
    PhoneLookupResult:
      type: object
      required:
      - phones
      properties:
        phones:
          type: array
          items:
            type: string
          description: The phone numbers we found
          examples:
          - - '+14158009370'
            - '+14158009371'
  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.'