Enrich People Data

Overview

Apollo's database features information for hundreds of millions of people. By providing basic details such as an email address or name, you can retrieve people data from Apollo's Enrichment API to supplement your own data.

🚧
Credits
Using this endpoint potentially consumes your account’s credits. Refer to Apollo’s API pricing page for more details.

The following sections show how to call the Enrichment API using only email addresses, and how to call the API using a combination of names and company domains.

Before You Start: Check Out Reference Docs

Apollo’s API reference docs show the query parameters available for you to use with the Enrichment API. Apollo is going to walk through specific scenarios in this article, but you can address your own cases by combining these examples with the reference information.

Example: Enrich People Data Using Emails

📘
1 Person Only
For this example, Apollo is going to show how to enrich data for a single person.
To enrich data for up to 10 people with a single API call, check out the Bulk People Enrichment endpoint. The same query parameters are available whether you are enriching data for a single person or multiple people.

To retrieve data for a single person using an email address:

Call the People Enrichment endpoint:

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

Add email as a query parameter. For this example, Apollo is going to use [email protected] as the value for the parameter.
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.

cURL Request

The following shows the example as a cURL request:

curl --request POST \
     --url 'https://api.apollo.io/api/v1/people/match?email=joshua.garrison%40apollo.io&reveal_personal_emails=false&reveal_phone_number=false' \
     --header 'Cache-Control: no-cache' \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     --header 'x-api-key: YOUR_API_KEY'

Postman Request

The following image shows how the request can be formatted in Postman. If you prefer to pass the parameters via the body of the request, use the raw option, not form-data.

Response Details

A successful request returns a 200 response status and JSON data similar to the following response:

{
    "person": {
        "id": "587cf802f65125cad923a266",
        "first_name": "Joshua",
        "last_name": "Garrison",
        "name": "Joshua Garrison",
        "linkedin_url": "http://www.linkedin.com/in/joshuapgarrison",
        "title": "VP, Content Marketing \u0026 Product Education",
        "email_status": null,
        "photo_url": "https://media.licdn.com/dms/image/D5603AQH-d1WsQEKwvA/profile-displayphoto-shrink_200_200/0/1695673740828?e=2147483647\u0026v=beta\u0026t=P13G77MMlOa4jKIo642FjK6tJBsEopGahzqoRRfz24Q",
        "twitter_url": null,
        "github_url": null,
        "facebook_url": null,
        "extrapolated_email_confidence": null,
        "headline": "Helping the world sell better @ Apollo | Publisher at Backlit Comics",
        "email": "[email protected]",
        "organization_id": "5e66b6381e05b4008c8331b8",
        "employment_history": [
            {
                "_id": "6682ef0284a1cf00012a7931",
                "created_at": null,
                "current": true,
                "degree": null,
                "description": null,
                "emails": null,
                "end_date": null,
                "grade_level": null,
                "kind": null,
                "major": null,
                "organization_id": "5e66b6381e05b4008c8331b8",
                "organization_name": "Apollo.io",
                "raw_address": null,
                "start_date": "2023-08-01",
                "title": "VP, Content Marketing \u0026 Product Education",
                "updated_at": null,
                "id": "6682ef0284a1cf00012a7931",
                "key": "6682ef0284a1cf00012a7931"
            },
...
        ],
        "state": "California",
        "city": "San Francisco",
        "country": "United States",
        "contact_id": "6462b961ad39c900a3070207",
        "contact": {
            "contact_roles": [],
            "id": "6462b961ad39c900a3070207",
            "first_name": "Joshua",
            "last_name": "Garrison",
            "name": "Joshua Garrison",
            "linkedin_url": "http://www.linkedin.com/in/joshuapgarrison",
            "title": "VP, Content Marketing \u0026 Product Education",
            "contact_stage_id": "6095a710bd01d100a506d4b1",
            "owner_id": "60affe7d6e270a00f5db6fe4",
            "creator_id": "60affe7d6e270a00f5db6fe4",
            "person_id": "587cf802f65125cad923a266",
            "email_needs_tickling": false,
            "organization_name": "Apollo.io",
            "source": "search",
            "original_source": "search",
            "organization_id": "5e66b6381e05b4008c8331b8",
            "headline": "Helping the world sell better @ Apollo | Publisher at Backlit Comics",
            "photo_url": "https://media.licdn.com/dms/image/C5603AQEeHJdige9RDg/profile-displayphoto-shrink_400_400/0/1637602418642?e=1689811200\u0026v=beta\u0026t=iacudGd6PsEq60qcCzpwfPO6n9u46JKf4bgAtfQ0xvU",
            "present_raw_address": "San Francisco Bay Area",
            "linkedin_uid": "161379409",
            "extrapolated_email_confidence": null,
            "salesforce_id": null,
            "salesforce_lead_id": null,
            "salesforce_contact_id": null,
            "salesforce_account_id": null,
            "crm_owner_id": "005Dm000001LaVtIAK",
            "created_at": "2023-05-15T22:59:45.283Z",
            "emailer_campaign_ids": [
                "6480faa352529300f1501086",
                "657c8b7bc0ee7301c689fbbe",
                "65820320ea75fb06b0921560",
                "66186b69391e0901c7dc89b0"
            ],
            "direct_dial_status": "enrichment_successful",
            "direct_dial_enrichment_failed_at": null,
            "email_status": "verified",
            "email_source": "rampedup",
            "account_id": "63f53afe4ceeca00016bdd34",
...

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

Element	Description
`"first_name"`, `"last_name"`, and `"name"`	The first name, last name and complete name of the person.
`"title"`	The value in this object shows the job title for the person.
`"linkedin_url"`	The URL for the person's LinkedIn profile.
`"organization_id"`	This alphanumeric ID is tied to the person's current employer. It can be used with other Apollo API endpoints to retrieve information specific to the organization.
`"employment_history"`	This array provides details for each job a person has previously held. This can include the organization name, job title, and start/end dates.
`"organization": { }`	This object provides more details about the person's current organization. This can include a primary phone number for the business.
`"state"`, `"city"`, and `"country"`	The personal location details for the person. This is not the same as the headquarters location for the person's employer.

Example: Enrich People Data Using Names and Company Domains

📘
1 Person Only
For this example, Apollo is going to show how to enrich data for a single person.
To enrich data for up to 10 people with a single API call, check out the Bulk People Enrichment endpoint. The same query parameters are available whether you are enriching data for a single person or multiple people.

To retrieve data for a single person using names and company domains:

Call the People Enrichment endpoint:

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

Add the following query parameters:

Parameter	Value for this Example	Notes
`"first_name"` and `"last_name"` OR `"name"`	`"Tim"`and `"Zheng"` OR `"Tim Zheng"`	Either use the separate parameters for the first name and last name, or provide the complete name under the single `name` parameter.
`"domain"`	`"apollo.io"`	Provide the web domain (for example, `microsoft.com`) for the person's current employer. Do not provide an entire URL.

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.

cURL Request

The following shows the example as a cURL request:

curl --request POST \
     --url 'https://api.apollo.io/api/v1/people/match?email=joshua.garrison%40apollo.io&reveal_personal_emails=false&reveal_phone_number=false' \
     --header 'Cache-Control: no-cache' \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     --header 'x-api-key: YOUR_API_KEY'

Postman Request

The following image shows how the request can be formatted in Postman. If you prefer to pass the parameters via the body of the request, use the raw option, not form-data.

Response Details

A successful request returns a 200 response status and JSON data similar to the following response:

{
  "person": {
    "id": "671bd2e8c2c9b5000169ba39",
    "first_name": "Tim",
    "last_name": "Zheng",
    "name": "Tim Zheng",
    "linkedin_url": "http://www.linkedin.com/in/tim-zheng",
    "title": "Founder & CEO",
    "email_status": "verified",
    "photo_url": "https://static.licdn.com/aero-v1/sc/h/9c8pery4andzj6ohjkjp54ma2",
    "twitter_url": null,
    "github_url": null,
    "facebook_url": null,
    "extrapolated_email_confidence": null,
    "headline": "Founder & CEO at Apollo",
    "email": "[email protected]",
    "organization_id": "5e66b6381e05b4008c8331b8",
    "employment_history": [
      {
        "_id": "671fd0863bf59b00019b8480",
        "created_at": null,
        "current": true,
        "degree": null,
        "description": null,
        "emails": null,
        "end_date": null,
        "grade_level": null,
        "kind": null,
        "major": null,
        "organization_id": "5e66b6381e05b4008c8331b8",
        "organization_name": "Apollo",
        "raw_address": null,
        "start_date": "2016-01-01",
        "title": "Founder & CEO",
        "updated_at": null,
        "id": "671fd0863bf59b00019b8480",
        "key": "671fd0863bf59b00019b8480"
      },
...
    ],
    "state": "California",
    "city": "San Francisco",
    "country": "United States",
    "contact_id": "60b00154e86fd70001917772",
    "contact": {
      "contact_roles": [],
      "id": "60b00154e86fd70001917772",
      "first_name": "Tim",
      "last_name": "Zheng",
      "name": "Tim Zheng",
      "linkedin_url": "http://www.linkedin.com/in/tim-zheng",
      "title": "Founder & CEO",
      "contact_stage_id": null,
      "owner_id": null,
      "creator_id": "60affe7d6e270a00f5db6fe4",
      "person_id": "671bd2e8c2c9b5000169ba39",
      "email_needs_tickling": null,
      "organization_name": "Apollo.io",
      "source": "search",
      "original_source": "search",
      "organization_id": "5e66b6381e05b4008c8331b8",
      "headline": "Founder & CEO at Apollo",
      "photo_url": "https://media-exp1.licdn.com/dms/image/C5635AQEY4Ror_YXc7Q/profile-framedphoto-shrink_200_200/0/1616772564782?e=1622235600&v=beta&t=u5FG4fdP7hhy3mhb2Zyy-ggplGxiB-bl7lJBwkr5cUk",
      "present_raw_address": "San Francisco, California, United States",
      "linkedin_uid": null,
      "extrapolated_email_confidence": null,
      "salesforce_id": null,
      "salesforce_lead_id": null,
      "salesforce_contact_id": null,
      "salesforce_account_id": null,
      "crm_owner_id": null,
      "created_at": "2021-05-27T20:30:12.328Z",
      "emailer_campaign_ids": [
        "60c0ec0be9da2200a425bfd1",
        "624b4d82f6a95501165cafcc"
      ],
      "direct_dial_status": null,
      "direct_dial_enrichment_failed_at": null,
      "email_status": "verified",
      "email_source": "gmail_directory",
      "account_id": null,
      "last_activity_date": null,
      "hubspot_vid": null,
      "hubspot_company_id": null,
      "crm_id": null,
      "sanitized_phone": "+11234567890",
      "merged_crm_ids": null,
      "updated_at": "2024-05-23T19:51:41.118Z",
      "queued_for_crm_push": null,
      "suggested_from_rule_engine_config_id": null,
      "email_unsubscribed": null,
      "person_deleted": null,
      "call_opted_out": null,
      "label_ids": [],
      "has_pending_email_arcgate_request": false,
      "has_email_arcgate_request": false,
      "existence_level": "full",
      "email": "[email protected]",
      "email_from_customer": null,
      "typed_custom_fields": {},
      "custom_field_errors": null,
      "crm_record_url": null,
      "email_status_unavailable_reason": null,
      "email_true_status": "Verified",
      "updated_email_true_status": true,
      "contact_rule_config_statuses": [],
      "source_display_name": "Requested from Apollo",
      "contact_emails": [],
      "time_zone": "America/Los_Angeles",
      "phone_numbers": [
        {
          "raw_number": "(123) 456-7890",
          "sanitized_number": "+11234567890",
          "type": null,
          "position": 0,
          "status": "valid_number",
          "dnc_status": null,
          "dnc_other_info": null,
          "dialer_flags": null,
          "source_name": "User Managed",
          "vendor_validation_statuses": []
        },
...
      ],
      "account_phone_note": null,
      "free_domain": false,
      "is_likely_to_engage": false
    },
...
}

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

Element	Description
`"first_name"`, `"last_name"`, and `"name"`	The first name, last name and complete name of the person.
`"title"`	The value in this object shows the job title for the person.
`"linkedin_url"`	The URL for the person's LinkedIn profile.
`"organization_id"`	This alphanumeric ID is tied to the person's current employer. It can be used with other Apollo API endpoints to retrieve information specific to the organization.
`"employment_history"`	This array provides details for each job a person has previously held. This can include the organization name, job title, and start/end dates.
`"organization": { }`	This object provides more details about the person's current organization. This can include a primary phone number for the business.
`"state"`, `"city"`, and `"country"`	The personal location details for the person. This is not the same as the headquarters location for the person's employer.

Enrich People Data

Overview

🚧
Credits

Before You Start: Check Out Reference Docs

Example: Enrich People Data Using Emails

📘
1 Person Only

cURL Request

Postman Request

Response Details

Example: Enrich People Data Using Names and Company Domains

📘
1 Person Only

cURL Request

Postman Request

Response Details

Overview

🚧Credits

Before You Start: Check Out Reference Docs

Example: Enrich People Data Using Emails

📘1 Person Only

cURL Request

Postman Request

Response Details

Example: Enrich People Data Using Names and Company Domains

📘1 Person Only

cURL Request

Postman Request

Response Details

🚧
Credits

📘
1 Person Only

📘
1 Person Only