Convert Enriched People to Contacts

Overview

When you use Apollo API to enrich your own people data and pull mobile phone numbers, you've likely already consumed credits as part of your Apollo pricing plan. If you call Apollo API to enrich data for the same people in the future, you can potentially use more credits to access the same data you already accessed.

To avoid using credits unnecessarily, use the create a contact endpoint to convert enriched people into contacts. A contact is a person saved to Apollo, which means their data becomes permanently accessible to your organization.

%% arazzo-workflow: convert-enriched-people-to-contacts (generated by node arazzo/build.ts, edit arazzo/tutorials.arazzo.json instead)
%%{init: {"flowchart": {"wrappingWidth": 400}}}%%
flowchart TD
  inputs(["<span class='apl-diagram-kicker'>Input</span><br><a class='apl-diagram-link' href='https://docs.apollo.io/docs/enrich-people-data'>Person data you enriched earlier</a>"]):::apl-diagram-input
  createContact("<a class='apl-diagram-link' href='https://docs.apollo.io/reference/create-a-contact'>Create a Contact</a><br><code>POST /contacts</code>"):::apl-diagram-step
  confirmContact("<span class='apl-diagram-purpose'>Confirm the contact</span><br><a class='apl-diagram-link' href='https://docs.apollo.io/reference/view-a-contact'>View a Contact</a><br><code>GET /contacts/{contact_id}</code>"):::apl-diagram-step
  inputs --> createContact
  createContact -->|"contact ID"| confirmContact
  result(["<span class='apl-diagram-kicker'>Result</span><br>Saved contact"]):::apl-diagram-result
  confirmContact --> result

🚧

New Contacts

Apollo doesn't run any deduplication during this process. If your record contains the same email address, or name and company as an existing contact, Apollo creates a new contact instead of updating the existing contact.

1: Create a Contact

First, retrieve the person data that you previously enriched. In this example, the request includes the following information:

• First name
• Last name
• Email address
• Company name
• Company domain
• Direct phone
• Mobile phone

To create a contact via Apollo API:

1. Call the create a contact endpoint:

POST https://api.apollo.io/api/v1/contacts

2. Add the following query parameters:

3. 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/contacts?first_name=Mark&last_name=Calder&organization_name=Sumware%20Software&email=mark%40sumware.com&website_url=https%3A%2F%2Fwww.sumwaresoftware.com&direct_phone=000-000-0001&mobile_phone=000-000-0002' \
     --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.

Response Details

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

{
    "contact": {
        "contact_roles": [],
        "id": "668463fe9709b70afd54fb5a",
        "first_name": "Mark",
        "last_name": "Calder",
        "name": "Mark Calder",
        "linkedin_url": null,
        "title": null,
        "contact_stage_id": "6095a710bd01d100a506d4ae",
        "owner_id": "60affe7d6e270a00f5db6fe4",
        "creator_id": "60affe7d6e270a00f5db6fe4",
        "person_id": null,
        "email_needs_tickling": null,
        "organization_name": "Sumware Software",
        "source": "api",
        "original_source": "api",
        "organization_id": null,
        "headline": null,
        "photo_url": null,
        "present_raw_address": null,
        "linkedin_uid": null,
...
        "phone_numbers": [
            {
                "raw_number": "000-000-0001",
                "sanitized_number": "+10000000001",
                "type": "work_direct",
                "position": 0,
                "status": "no_status",
                "dnc_status": null,
                "dnc_other_info": null,
                "dialer_flags": null
            },
            {
                "raw_number": "000-000-0002",
                "sanitized_number": "+10000000002",
                "type": "mobile",
                "position": 1,
                "status": "no_status",
                "dnc_status": null,
                "dnc_other_info": null,
                "dialer_flags": null
            }
        ],
...
}

2. Confirm Contact Status

To confirm that Apollo saved the contact:

1. Call the view a contact endpoint with the id of the contact from the step 1 response. For this example, the contact ID is 668463fe9709b70afd54fb5a:

GET https://api.apollo.io/api/v1/contacts/668463fe9709b70afd54fb5a

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.

The contact object in the API response shows the details you saved, including the email address and phone numbers. Viewing a contact doesn't use credits, so you can access this data again at any time.