Retrieve Mobile Phone Numbers for Contacts

Overview

Use Apollo API to retrieve available phone numbers for a person, including mobile and direct-dial numbers.

Phone enrichment runs asynchronously. Apollo immediately returns the standard people enrichment response, then sends the phone enrichment results to the webhook URL included in your request.

Use the people enrichment endpoint to retrieve phone numbers for one person. To retrieve phone numbers for up to 10 people in a single request, use the bulk people enrichment endpoint.

🚧
Credits
Retrieving phone numbers may use credits based on the data returned, your Apollo plan, and your enrichment configuration. Check out Apollo API pricing and credits for details.

1: Retrieve Phone Numbers for One Person

To retrieve phone numbers for one person:

Call the people enrichment endpoint:

POST https://api.apollo.io/api/v1/people/match

Add the following query parameters:

Parameter	Value for this Example	Notes
`email`	`[email protected]`	Identifies the person to enrich. You can also use other supported identifiers, such as a name and company domain.
`reveal_phone_number`	`true`	Requests available phone numbers for the person.
`webhook_url`	`https://example.com/webhooks/apollo`	The publicly accessible HTTPS URL where Apollo sends the phone enrichment results.

If you don't provide a valid webhook_url, Apollo returns an error similar to the following:

{
  "error": "Please add a valid 'webhook_url' parameter when using 'reveal_phone_number'"
}

Add the following keys and values to the header of your request:
1. Content-Type: application/json
2. Cache-Control: no-cache
3. x-api-key: Enter your Apollo API key.

📘
Test Your Webhook
To test this workflow before configuring your production endpoint, use a webhook testing service such as webhook.site and include the generated HTTPS URL as the webhook_url.

cURL Request

The following shows the example as a cURL request:

curl --request POST \
     --url 'https://api.apollo.io/api/v1/people/match?email=maya%40lumenridge.com&reveal_personal_emails=false&reveal_phone_number=true&webhook_url=https%3A%2F%2Fexample.com%2Fwebhooks%2Fapollo' \
     --header 'Cache-Control: no-cache' \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     --header 'x-api-key: YOUR_API_KEY'

Postman Request

As an example, here's how the request can be formatted in Postman. If you prefer to pass parameters via the body of the request, use the raw option instead of form-data.

Synchronous Response

A successful request returns a 200 response status and the standard people enrichment response.

The synchronous response may include the person's employer phone number, but it doesn't include the asynchronously retrieved mobile or direct-dial numbers. Apollo sends those results separately to the provided webhook URL.

{
  "person": {
    "id": "68a7ff0cc4dfae00013df1b7",
    "first_name": "Maya",
    "last_name": "Ellison",
    "name": "Maya Ellison",
    "title": "Vice President of Partnerships",
    "email": "[email protected]",
    "organization": {
      "name": "Lumen Ridge",
      "primary_domain": "lumenridge.com",
      "phone": "+1 202-555-0100"
    }
  }
}

Webhook Response

When phone enrichment finishes, Apollo sends a POST request to the provided webhook URL with JSON data similar to the following response:

{
  "status": "success",
  "total_requested_enrichments": 1,
  "unique_enriched_records": 1,
  "missing_records": 0,
  "credits_consumed": 8,
  "people": [
    {
      "id": "68a7ff0cc4dfae00013df1b7",
      "status": "success",
      "phone_numbers": [
        {
          "_id": "68dbe6d172c24f00017b9b73",
          "confidence_cd": "high",
          "created_at": null,
          "direct_dial_source_cd": "contact_trusted",
          "dnc_other_info": {
            "country": "United States"
          },
          "dnc_status_cd": "not_found",
          "dnc_status_updated_at": "2026-04-15T20:57:53.108+00:00",
          "position": 0,
          "raw_number": "+1 202-555-0116",
          "sanitized_number": "+12025550116",
          "status_cd": "valid_number",
          "type_cd": "mobile",
          "updated_at": null,
          "id": "68dbe6d172c24f00017b9b73",
          "key": "68dbe6d172c24f00017b9b73"
        },
        {
          "_id": "68dbe6d172c24f00017b9b74",
          "confidence_cd": "high",
          "created_at": null,
          "direct_dial_source_cd": "contact_trusted",
          "dnc_other_info": {
            "country": "United States"
          },
          "dnc_status_cd": "not_found",
          "dnc_status_updated_at": "2026-04-15T20:57:53.267+00:00",
          "position": 1,
          "raw_number": "+1 202-555-0142",
          "sanitized_number": "+12025550142",
          "status_cd": "valid_number",
          "type_cd": "work_direct",
          "updated_at": null,
          "id": "68dbe6d172c24f00017b9b74",
          "key": "68dbe6d172c24f00017b9b74"
        }
      ]
    }
  ]
}

The following table details some key elements of the webhook response:

Element	Description
`credits_consumed`	The number of credits consumed by the enrichment request. Actual usage depends on the data returned, your Apollo plan, and your enrichment configuration.
`people`	The people included in the enrichment results.
`status`	Indicates whether phone enrichment succeeded for the person.
`phone_numbers`	The available phone numbers returned for the person.
`raw_number`	The phone number in a human-readable format.
`sanitized_number`	The phone number in E.164-style format without spaces or punctuation.
`type_cd`	The phone-number type, such as `mobile` or `work_direct`.
`status_cd`	The validation status of the phone number.

The credits_consumed value in this example is illustrative. Don't use it to estimate the cost of every phone enrichment request. Check out Apollo API pricing and credits for current credit guidance.

Overview

Credits

1: Retrieve Phone Numbers for One Person

Test Your Webhook

cURL Request

Postman Request

Synchronous Response

Webhook Response

What’s Next