Get Started

Enrich People Data

Suggest Edits

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.

🚧

Email Credits and Export Credits

Using this endpoint potentially consumes your account’s email and export 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:

  1. Call the People Enrichment endpoint:
POST <https://api.apollo.io/v1/people/match>
  1. Add email as a query parameter. For this example, Apollo is going to use [email protected] as the value for the parameter.
  2. 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 -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "X-Api-Key: YOUR_API_KEY" -d '{  
    "email": "[email protected]"  
}' "<https://api.apollo.io/v1/people/match">

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:

ElementDescription
"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:

  1. Call the People Enrichment endpoint:
POST <https://api.apollo.io/v1/people/match>
  1. Add the following query parameters:
ParameterValue for this ExampleNotes
"first_name" and "last_name"

OR

"name"		"David"and "Malpass"

OR

"David Malpass"		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.

  1. 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 -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "X-Api-Key: YOUR_API_KEY" -d '{  
    "first_name": "David",  
    "last_name": "Malpass",  
    "domain": "apollo.io"  
}' "<https://api.apollo.io/v1/people/match">

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": "60ffd2c3a1823c00015edbb9",
        "first_name": "David",
        "last_name": "Malpass",
        "name": "David Malpass",
        "linkedin_url": "http://www.linkedin.com/in/davidmalpass",
        "title": "SVP Marketing - We're Hiring!",
        "email_status": "verified",
        "photo_url": "https://media.licdn.com/dms/image/D5603AQF1DUD-XN5viQ/profile-displayphoto-shrink_200_200/0/1695771597297?e=2147483647\u0026v=beta\u0026t=RQZH8hOZlsfL6K6TW1As8lHn-7QDvjfRCLZtgHgkXxY",
        "twitter_url": "https://twitter.com/davidmalpass",
        "github_url": null,
        "facebook_url": null,
        "extrapolated_email_confidence": null,
        "headline": "SVP Marketing @ Apollo. Formerly led mktg @ Autodesk, BuildingConnected (acq by ADSK), InVision, Prezi, Redkix (acq by Meta)",
        "email": "[email protected]",
        "organization_id": "5e66b6381e05b4008c8331b8",
        "employment_history": [
            {
                "_id": "6684152c70a57300019c4319",
                "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": "2022-10-01",
                "title": "SVP Marketing - We're Hiring!",
                "updated_at": null,
                "id": "6684152c70a57300019c4319",
                "key": "6684152c70a57300019c4319"
            },
...
        ],
        "state": "California",
        "city": "San Francisco",
        "country": "United States",
        "contact_id": "6596ea42d05a3e00014cf630",
...
}%

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

ElementDescription
"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.

Updated 2 months ago

What’s Next