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

# Find phone numbers

> Asynchronous. Starts a job that finds phone numbers for up to 500 people and returns 202 with the job; poll GET /enrichment/jobs/{jobID} until status is completed or failed (with webhookURL, each person's result is also posted as it is ready), then page through GET /enrichment/jobs/{jobID}/results. On succeeded results the found value is in payload.phoneNumber.

Consumes credits: your account's phone price per person found. A value your account obtained in the last 30 days, through the API or the app, is returned free and is not reserved or charged; an older value is looked up again and charged if found. For every other person the job reserves that price upfront, and at completion charges only the people found; the rest of the reservation is released.

Input, two mutually exclusive modes: (1) personIDs - IDs returned by POST /search; (2) people - objects with either linkedinURL (e.g. "https://www.linkedin.com/in/example-profile") or firstName + lastName + a company signal (companyDomain such as "salesforge.ai" is preferred over a company name such as "Salesforge"). Max 500 items. Each result echoes the linkedinURL, firstName, lastName and company you sent in inputLinkedinURL, inputFirstName, inputLastName and inputCompany, and externalID as is, for correlation (companyDomain is not echoed). In personIDs mode, IDs that match no person are skipped and do not count in total; if none match, the request fails with 400.

People entries are deduplicated by normalized linkedinURL, by case-insensitive firstName + lastName + companyDomain (or company when no domain is given), and when they resolve to the same person; only one result is returned per unique person, and charged once; that result carries the externalID of the first matching entry, with linkedinURL entries taking precedence, so send unique people if you need every externalID back. Each person may carry an optional externalID (max 128 chars), a passthrough value persisted with the result and echoed back in the webhook payload and the results; it is not supported in personIDs mode. A linkedinURL that is not a valid profile URL is ignored: the entry is matched by firstName + lastName + company when you sent them, and is returned not_found otherwise.

Example with people: {"people": [{"linkedinURL": "https://www.linkedin.com/in/example-profile", "externalID": "crm-42"}, {"firstName": "Jane", "lastName": "Smith", "companyDomain": "salesforge.ai"}], "webhookURL": "https://example.com/webhook"}. Example with personIDs: {"personIDs": ["6f1e2d3c-4b5a-5968-8776-a5b4c3d2e1f0", "0a9b8c7d-6e5f-5a4b-9c3d-2e1f0a9b8c7d"]}.

Idempotency-Key: a repeat with the same key for the same channel returns the existing job as is, in whatever status and whatever its body, for as long as that job exists; the body must still be valid, or the repeat gets 400. Send a repeat only after the previous attempt has returned or timed out. A repeat does not count against the concurrent jobs limit, but it is still subject to the rate limit and can get 429; retry it with the same key.

Webhook: one POST per person as their result is recorded, with the result object (as in GET /enrichment/jobs/{jobID}/results) as the body. Webhooks can start arriving right after the 202 response, so accept one for a jobID you have not stored yet. There is no job-level webhook, so poll the job for its final status. A delivery that fails with a 5xx, 429 or network error is retried immediately and then redelivered in the background for up to 24h; other 4xx responses are not retried. Each attempt waits up to 8 seconds for a response. Redirects are not followed: a 3xx response is a failed delivery and is not retried. Every attempt for a result carries the same X-Webhook-Delivery-Id header (one ID per result) so repeated deliveries can be deduplicated; also deduplicate on jobID + personID and keep the latest. A result is readable through GET /enrichment/jobs/{jobID}/results by the time its webhook is sent. 2xx = delivered. webhookURL must be a public http or https URL with a domain name, not an IP address, or the request fails with 400; use https, since webhook bodies carry personal data.



## OpenAPI

````yaml https://api.leadsforge.ai/public/swagger/doc.json post /enrichment/phones
openapi: 3.1.0
info:
  description: >-
    Search B2B leads, find their work emails, phone numbers and LinkedIn
    profiles, and discover lookalike companies, company page followers and local
    businesses.


    Authenticate every request with your API key in the `Authorization` header:
    the raw key, no `Bearer` prefix. Create the key in the Leadsforge app under
    Settings -> API & MCP.


    Paid operations consume credits from your account balance, and each
    operation says whether it is paid. Long-running operations are asynchronous:
    they return a job that you poll (or receive by webhook) and then page
    through its results.


    Errors return a JSON body with a human-readable `message` and, except for an
    unknown path (404), a stable `code`. Program against `code`. A JSON body
    with a field the operation does not accept is rejected with 400 bad_request,
    listing the unknown fields in data.validations. A request still running when
    the server timeout is reached is cut off with 503 and an empty body.
  license:
    name: Proprietary
    url: https://www.leadsforge.ai/terms
  termsOfService: https://www.leadsforge.ai/terms
  title: Leadsforge API
  version: '1.0'
servers:
  - url: https://api.leadsforge.ai/public/v1
security: []
tags:
  - description: Your account's credit balance.
    name: Balance
  - description: >-
      Find people by role, seniority, company, location and other filters.
      Searches and counts are free up to a monthly allowance, then each one
      costs credits; finding contact details is charged separately.
    name: Search
  - description: >-
      Accepted values for the controlled filters of POST /search and POST
      /search/count, and a resolver for location strings. All free.
    name: Search filters
  - description: >-
      Find work emails, phone numbers and LinkedIn profiles. Asynchronous jobs
      take up to 500 people; synchronous calls take one person and answer in the
      same response.
    name: Enrichment
  - description: >-
      Find companies similar to the domains you give. Previews are free up to a
      monthly allowance, then each one costs credits; the search consumes
      credits per company returned.
    name: Lookalikes
  - description: >-
      Find the people who follow a LinkedIn company page. Asynchronous jobs that
      consume credits per follower collected.
    name: Company followers
  - description: >-
      Find local businesses in an area you choose, then find their owners'
      emails and phone numbers. Both steps are asynchronous jobs that consume
      credits.
    name: Maps discovery
  - description: Scrape LinkedIn Sales Navigator searches.
    name: salesnav
externalDocs:
  description: Leadsforge API guides
  url: >-
    https://developer.salesforge.ai/leadsforge-api/concepts/search-and-enrichment
paths:
  /enrichment/phones:
    post:
      tags:
        - Enrichment
      summary: Find phone numbers
      description: >-
        Asynchronous. Starts a job that finds phone numbers for up to 500 people
        and returns 202 with the job; poll GET /enrichment/jobs/{jobID} until
        status is completed or failed (with webhookURL, each person's result is
        also posted as it is ready), then page through GET
        /enrichment/jobs/{jobID}/results. On succeeded results the found value
        is in payload.phoneNumber.


        Consumes credits: your account's phone price per person found. A value
        your account obtained in the last 30 days, through the API or the app,
        is returned free and is not reserved or charged; an older value is
        looked up again and charged if found. For every other person the job
        reserves that price upfront, and at completion charges only the people
        found; the rest of the reservation is released.


        Input, two mutually exclusive modes: (1) personIDs - IDs returned by
        POST /search; (2) people - objects with either linkedinURL (e.g.
        "https://www.linkedin.com/in/example-profile") or firstName + lastName +
        a company signal (companyDomain such as "salesforge.ai" is preferred
        over a company name such as "Salesforge"). Max 500 items. Each result
        echoes the linkedinURL, firstName, lastName and company you sent in
        inputLinkedinURL, inputFirstName, inputLastName and inputCompany, and
        externalID as is, for correlation (companyDomain is not echoed). In
        personIDs mode, IDs that match no person are skipped and do not count in
        total; if none match, the request fails with 400.


        People entries are deduplicated by normalized linkedinURL, by
        case-insensitive firstName + lastName + companyDomain (or company when
        no domain is given), and when they resolve to the same person; only one
        result is returned per unique person, and charged once; that result
        carries the externalID of the first matching entry, with linkedinURL
        entries taking precedence, so send unique people if you need every
        externalID back. Each person may carry an optional externalID (max 128
        chars), a passthrough value persisted with the result and echoed back in
        the webhook payload and the results; it is not supported in personIDs
        mode. A linkedinURL that is not a valid profile URL is ignored: the
        entry is matched by firstName + lastName + company when you sent them,
        and is returned not_found otherwise.


        Example with people: {"people": [{"linkedinURL":
        "https://www.linkedin.com/in/example-profile", "externalID": "crm-42"},
        {"firstName": "Jane", "lastName": "Smith", "companyDomain":
        "salesforge.ai"}], "webhookURL": "https://example.com/webhook"}. Example
        with personIDs: {"personIDs": ["6f1e2d3c-4b5a-5968-8776-a5b4c3d2e1f0",
        "0a9b8c7d-6e5f-5a4b-9c3d-2e1f0a9b8c7d"]}.


        Idempotency-Key: a repeat with the same key for the same channel returns
        the existing job as is, in whatever status and whatever its body, for as
        long as that job exists; the body must still be valid, or the repeat
        gets 400. Send a repeat only after the previous attempt has returned or
        timed out. A repeat does not count against the concurrent jobs limit,
        but it is still subject to the rate limit and can get 429; retry it with
        the same key.


        Webhook: one POST per person as their result is recorded, with the
        result object (as in GET /enrichment/jobs/{jobID}/results) as the body.
        Webhooks can start arriving right after the 202 response, so accept one
        for a jobID you have not stored yet. There is no job-level webhook, so
        poll the job for its final status. A delivery that fails with a 5xx, 429
        or network error is retried immediately and then redelivered in the
        background for up to 24h; other 4xx responses are not retried. Each
        attempt waits up to 8 seconds for a response. Redirects are not
        followed: a 3xx response is a failed delivery and is not retried. Every
        attempt for a result carries the same X-Webhook-Delivery-Id header (one
        ID per result) so repeated deliveries can be deduplicated; also
        deduplicate on jobID + personID and keep the latest. A result is
        readable through GET /enrichment/jobs/{jobID}/results by the time its
        webhook is sent. 2xx = delivered. webhookURL must be a public http or
        https URL with a domain name, not an IP address, or the request fails
        with 400; use https, since webhook bodies carry personal data.
      operationId: startPhoneEnrichment
      parameters:
        - description: >-
            Idempotency key - a repeat with the same key for the same channel
            returns the existing job as is; it can still get 429 from the rate
            limit, retry it with the same key
          in: header
          name: Idempotency-Key
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartEnrichmentRequest'
              description: Find request
              summary: body
        description: Find request
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichmentJobResponse'
          description: Job created
          headers:
            Location:
              description: Path of the new job, same as statusURL
              schema:
                type: string
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: 'bad_request: the body or a parameter is invalid'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            missing_api_key, invalid_api_key, or unauthorized when your account
            is blocked
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            insufficient_credits: the balance does not cover the credits this
            request reserves
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            account_frozen: credit spending is paused for your account; contact
            support
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            rate_limited: too many requests (retry later; Retry-After is set
            when known), or your account already runs its maximum number of
            concurrent enrichment jobs (all channels count)
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: 'internal: unexpected server error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    StartEnrichmentRequest:
      properties:
        clientRequestID:
          example: my-request-123
          maxLength: 128
          type: string
        people:
          items:
            $ref: '#/components/schemas/EnrichmentPerson'
          maxItems: 500
          minItems: 1
          type: array
          uniqueItems: false
        personIDs:
          items:
            type: string
          maxItems: 500
          minItems: 1
          type: array
          uniqueItems: false
        saveToList:
          description: >-
            SaveToList, when true, also shows this job as a list on the
            Enrichments page of the Leadsforge app. Default false.
          example: false
          type: boolean
        webhookURL:
          example: https://example.com/webhook
          type: string
      type: object
    EnrichmentJobResponse:
      properties:
        channel:
          enum:
            - email
            - phone
            - linkedin
          type: string
        clientRequestID:
          type: string
        completedAt:
          type: string
        consumedCredits:
          type: number
        createdAt:
          type: string
        failed:
          type: integer
        jobID:
          type: string
        processed:
          type: integer
        reservedCredits:
          type: number
        resultsURL:
          description: >-
            ResultsURL is the path of this job's results on the API host, e.g.
            /public/v1/enrichment/jobs/{jobID}/results.
          type: string
        status:
          enum:
            - in_progress
            - completed
            - failed
          type: string
        statusURL:
          description: >-
            StatusURL is the path of this job on the API host, e.g.
            /public/v1/enrichment/jobs/{jobID}.
          type: string
        succeeded:
          type: integer
        total:
          type: integer
        updatedAt:
          type: string
        webhookURL:
          type: string
      type: object
    ApiError:
      properties:
        code:
          description: >-
            Code is the stable, machine-readable error code; each endpoint lists
            the codes it returns.
          type: string
        data:
          description: >-
            Data carries details for some errors; on validation errors it is
            {"validations": ["..."]}, one message per

            invalid field.
        message:
          type: string
      type: object
    EnrichmentPerson:
      properties:
        company:
          example: Salesforge
          type: string
        companyDomain:
          example: salesforge.ai
          type: string
        externalID:
          example: crm-contact-42
          maxLength: 128
          type: string
        firstName:
          example: John
          type: string
        lastName:
          example: Doe
          type: string
        linkedinURL:
          example: https://www.linkedin.com/in/example-profile
          type: string
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: >-
        Your API key, sent as is (no `Bearer` prefix). Create it in the
        Leadsforge app under Settings -> API & MCP.
      in: header
      name: Authorization
      type: apiKey

````

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