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

# Poll a Phone Enrichment

> Returns the current state of a phone enrichment request. While the waterfall is running `status` is `pending` or `processing`. When finished `status` is `completed` (with the numbers in `phone_numbers`) or `not-found` (every eligible provider was exhausted without a number that passed validation). `phone_numbers` is populated only on a `completed` request and is an empty array otherwise. Polling is a fallback for the callback and is safe to call repeatedly — a request is never charged twice.

Returns the current state of a phone enrichment request created with [Request a Phone Enrichment](/api-reference/endpoint/enrich-phone).

Polling is the fallback for the `callback_url` webhook — it is safe to call repeatedly, and a request is **never charged twice** regardless of how often you poll.

### Path Parameters

| Parameter | Type   | Description                                                         |
| --------- | ------ | ------------------------------------------------------------------- |
| `id`      | string | The enrichment request `_id` returned when the request was created. |

### Status lifecycle

| Status       | Meaning                                                                                           |
| ------------ | ------------------------------------------------------------------------------------------------- |
| `pending`    | Accepted, not yet started.                                                                        |
| `processing` | The provider waterfall is running.                                                                |
| `completed`  | The lookup finished — see `phone_numbers`. (1 credit charged, unless the list came back empty.)   |
| `not-found`  | Every eligible provider was exhausted without a number that passed validation. No credit charged. |

<Note>
  `phone_numbers` is returned **only** on a `completed` request. Until then the field is an empty array, even if we already hold numbers for that profile from an earlier lookup.
</Note>

### Response (200) — completed

```json theme={null}
{
  "_id": "507f1f77bcf86cd799439011",
  "linkedin": "https://www.linkedin.com/in/janedoe",
  "linkedin_username": "janedoe",
  "status": "completed",
  "enrichment_type": "contact",
  "phone_numbers": [
    {
      "number": "+14155550123",
      "country_code": "US",
      "type": "mobile",
      "extension": "",
      "source": "prospeo",
      "validation": {
        "phone_number": "+14155550123",
        "is_valid": true,
        "carrier": "AT&T",
        "line_type": "mobile",
        "likely_to_answer": "P1",
        "score": 92,
        "status": "completed"
      }
    }
  ],
  "createdAt": "2026-08-27T10:15:04.221Z",
  "updatedAt": "2026-08-27T10:16:38.904Z"
}
```

`phone_numbers` is everything we hold for that LinkedIn profile, not only what this request discovered — a profile enriched twice returns the accumulated list both times.

### Phone number object

| Field          | Type   | Description                                                                      |
| -------------- | ------ | -------------------------------------------------------------------------------- |
| `number`       | string | The number in E.164 format.                                                      |
| `country_code` | string | ISO 3166-1 alpha-2 country of the number (`US`, `GB`, …) — not a dialing prefix. |
| `type`         | string | `mobile`, `direct`, or `office`.                                                 |
| `extension`    | string | Dial extension, empty when there is none.                                        |
| `source`       | string | The data provider the number came from.                                          |
| `validation`   | object | Result of the phone validation pass — see below.                                 |

### Validation object

| Field              | Type    | Description                                                                |
| ------------------ | ------- | -------------------------------------------------------------------------- |
| `phone_number`     | string  | The number that was validated.                                             |
| `is_valid`         | boolean | Whether the number passed validation. Numbers that fail are never stored.  |
| `carrier`          | string  | Carrier reported by the validator.                                         |
| `line_type`        | string  | Line classification, e.g. `mobile` or `landline`.                          |
| `likely_to_answer` | string  | Answer-likelihood tier — `P1` (best) through `P3`.                         |
| `score`            | number  | Validator confidence score.                                                |
| `status`           | string  | `completed` once validation resolved; `pending` while it is still running. |

A request only completes on a number that is valid, is not a `landline`, and is not tier `P3`; anything else sends the waterfall on to the next provider. Numbers that were rejected on the way may still appear in the array from earlier passes, so filter on `validation` rather than assuming every entry is dial-worthy.

### Response (200) — still running

```json theme={null}
{
  "_id": "507f1f77bcf86cd799439011",
  "linkedin": "https://www.linkedin.com/in/janedoe",
  "linkedin_username": "janedoe",
  "status": "processing",
  "enrichment_type": "contact",
  "phone_numbers": [],
  "createdAt": "2026-08-27T10:15:04.221Z",
  "updatedAt": "2026-08-27T10:15:09.117Z"
}
```

### Errors

| Status | Description                                    |
| ------ | ---------------------------------------------- |
| 404    | No enrichment request found for the given `id` |


## OpenAPI

````yaml GET /v1/api/enrichment/phone/{id}
openapi: 3.0.1
info:
  title: Salesfinity API
  description: >-
    The Salesfinity API is a JSON-over-HTTPS REST API for the Salesfinity
    parallel dialer.

    Use it to manage contact lists, read call logs and AI call scores, pull team
    and SDR

    analytics, and enrich email addresses. Webhook subscriptions are managed in
    the

    Salesfinity application rather than through this API.


    ## Base URL


    All requests go to `https://client-api.salesfinity.co`. There is no separate
    sandbox host;

    see the developer portal for the recommended way to test safely.


    ## Authentication


    Every endpoint requires an API key sent in the `x-api-key` request header.
    Generate a key

    in the Salesfinity dashboard under **Settings -> Connections & API**. A key
    is scoped to a

    single team, and every response is filtered to that team.


    ```bash

    curl https://client-api.salesfinity.co/v1/team \
      --header 'x-api-key: YOUR_API_KEY'
    ```


    ## Errors


    Errors are always JSON and always use the same envelope, so a client can
    parse a failure

    the same way on every endpoint:


    ```json

    { "message": "Forbidden resource", "error": "Forbidden", "statusCode": 403 }

    ```


    `statusCode` matches the HTTP status. `error` is the stable reason phrase to
    branch on.

    `message` is human readable, and is an array of strings when request
    validation fails.

    Note that a missing or invalid API key returns **403**, not 401.


    ## Pagination


    List endpoints accept `page` (1-based) and `limit` query parameters and
    return the matching

    page alongside the total count. The `limit` default varies by endpoint (10,
    50, or 100) and

    is capped at 100 where a cap applies, so read the parameter schema on the
    operation itself.


    ## Rate limits


    Salesfinity does not currently publish a fixed request quota. Treat HTTP 429
    as retryable

    and back off with exponential jitter.
  version: 1.0.0
  termsOfService: https://salesfinity.ai/terms
  contact:
    name: Salesfinity Support
    email: hello@salesfinity.co
    url: https://support.salesfinity.ai
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://client-api.salesfinity.co
    description: Production. The only public Salesfinity API host.
security:
  - ApiKeyAuth: []
tags:
  - name: Contact Lists
    description: >-
      Create, read, merge, and delete CSV contact lists, and add or remove the
      contacts inside them.
  - name: Teams
    description: >-
      Read the team that owns the API key, including its members, licenses, and
      statuses.
  - name: Dispositions
    description: Read the default and custom call outcomes configured for the team.
  - name: Sequences
    description: Read the sequences referenced by the team's call logs.
  - name: Call Logs
    description: >-
      Read the raw call history for the team, with filtering, sorting, and
      pagination.
  - name: Analytics
    description: Aggregated call metrics for the team, by contact list, and by SDR.
  - name: Snoozed Contacts
    description: Read and manage contacts that have been snoozed out of the dialing queue.
  - name: Follow-up Tasks
    description: Read follow-up tasks created from call outcomes.
  - name: Custom Fields
    description: Read the custom field mappings configured for the team.
  - name: Scored Calls
    description: Read AI-scored calls with per-facet scoring and coaching recommendations.
  - name: Notes
    description: >-
      Attach freeform notes to a person or company, list them, and pin the ones
      that matter.
  - name: Enrichment
    description: >-
      Look up phone numbers and work or personal email addresses for a LinkedIn
      profile, and check the team's remaining enrichment credits.
externalDocs:
  description: Salesfinity API documentation
  url: https://docs.salesfinity.ai
paths:
  /v1/api/enrichment/phone/{id}:
    get:
      tags:
        - Enrichment
      summary: Get a phone enrichment result
      description: >-
        Returns the current state of a phone enrichment request. While the
        waterfall is running `status` is `pending` or `processing`. When
        finished `status` is `completed` (with the numbers in `phone_numbers`)
        or `not-found` (every eligible provider was exhausted without a number
        that passed validation). `phone_numbers` is populated only on a
        `completed` request and is an empty array otherwise. Polling is a
        fallback for the callback and is safe to call repeatedly — a request is
        never charged twice.
      operationId: get-phone-enrichment
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: >-
            The enrichment request _id returned by POST
            /v1/api/enrichment/phone.
      responses:
        '200':
          description: Current state of the enrichment request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneEnrichmentRequestDTO'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: >-
            No enrichment request found for the given id. Check the path and any
            ID in it. A 404 also means the resource exists but is not owned by
            the team that the API key belongs to.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Cannot GET /v1/unknown-route
                error: Not Found
                statusCode: 404
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    PhoneEnrichmentRequestDTO:
      type: object
      properties:
        _id:
          type: string
          description: >-
            Enrichment request ID. Use this to poll GET
            /v1/api/enrichment/phone/{id}, and to match the request_id in the
            callback.
          example: 507f1f77bcf86cd799439011
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - not-found
          description: >-
            Current state of the request. `completed` means the waterfall
            finished; `not-found` means no number passed validation. Phone
            enrichment never resolves to `failed`.
        linkedin:
          type: string
          description: The LinkedIn profile URL the request was created with.
          example: https://www.linkedin.com/in/username
        linkedin_username:
          type: string
          description: The username extracted from the LinkedIn URL.
          example: username
        enrichment_type:
          type: string
          enum:
            - contact
          description: Always `contact` for phone enrichment.
        phone_numbers:
          type: array
          description: >-
            Every number held for the profile, not only the ones this request
            discovered. Populated only when status is `completed`; an empty
            array otherwise. Absent from the response to POST
            /v1/api/enrichment/phone.
          items:
            $ref: '#/components/schemas/PhoneNumberDTO'
        createdAt:
          type: string
          format: date-time
          example: '2026-08-27T10:15:04.221Z'
        updatedAt:
          type: string
          format: date-time
          example: '2026-08-27T10:16:38.904Z'
    Error:
      type: object
      title: Error
      description: >-
        The error envelope returned by every Salesfinity API error response. The
        shape is identical across all status codes and all endpoints.
      required:
        - message
        - error
        - statusCode
      properties:
        message:
          description: >-
            Human-readable description of the failure. A string for most errors,
            and an array of strings when request validation fails, with one
            entry per field that did not validate.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          example: Forbidden resource
        error:
          type: string
          description: >-
            Stable HTTP reason phrase for the status code. Branch on this rather
            than on `message`.
          example: Forbidden
        statusCode:
          type: integer
          format: int32
          description: >-
            HTTP status code, repeated in the body so it survives transports
            that drop it.
          example: 403
      example:
        message: Forbidden resource
        error: Forbidden
        statusCode: 403
    PhoneNumberDTO:
      type: object
      properties:
        number:
          type: string
          description: The number in E.164 format.
          example: '+14155550123'
        country_code:
          type: string
          description: ISO 3166-1 alpha-2 country of the number, not a dialing prefix.
          example: US
        type:
          type: string
          enum:
            - mobile
            - direct
            - office
          description: Line category derived from the parsed number.
        extension:
          type: string
          description: Dial extension, empty when there is none.
          example: ''
        source:
          type: string
          description: The data provider the number came from.
          example: prospeo
        validation:
          $ref: '#/components/schemas/PhoneValidationDTO'
    PhoneValidationDTO:
      type: object
      description: >-
        Result of the phone validation pass. A request only completes on a
        number that is valid, is not a landline, and is not tier P3.
      properties:
        phone_number:
          type: string
          example: '+14155550123'
        is_valid:
          type: boolean
          description: >-
            Whether the number passed validation. Numbers that fail are never
            stored.
          example: true
        carrier:
          type: string
          description: Carrier reported by the validator.
          example: AT&T
        line_type:
          type: string
          description: Line classification, e.g. mobile or landline.
          example: mobile
        likely_to_answer:
          type: string
          enum:
            - P1
            - P2
            - P3
          description: Answer-likelihood tier, P1 being the most likely to answer.
        score:
          type: number
          description: Validator confidence score.
          example: 92
        status:
          type: string
          enum:
            - pending
            - completed
          description: >-
            `completed` once validation resolved; `pending` while it is still
            running.
  responses:
    Forbidden:
      description: >-
        Forbidden. The `x-api-key` header is missing, malformed, revoked, or
        belongs to another team. Send a valid key in the `x-api-key` header.
        Salesfinity returns 403 (not 401) for a missing, malformed, revoked, or
        wrong-team key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Forbidden resource
            error: Forbidden
            statusCode: 403
    TooManyRequests:
      description: >-
        Too Many Requests. The client is being throttled and should retry with
        backoff. Back off and retry with exponential jitter. Treat 429 as
        retryable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Too many requests
            error: Too Many Requests
            statusCode: 429
    InternalServerError:
      description: >-
        Internal Server Error. Something went wrong on the Salesfinity side.
        Retry with exponential backoff. If it persists, contact
        hello@salesfinity.co with the request path and timestamp.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Internal server error
            error: Internal Server Error
            statusCode: 500
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Team-scoped API key generated in the Salesfinity dashboard under
        Settings -> Connections & API. A missing or invalid key returns HTTP
        403.

````