Table of Contents

• Introduction
• Overview
• Documentation
• Documentation Walkthrough
• Double Checking Your Headers
• Search for a Person
• Search for a Contact
• Enrich a Person's Information

Making API Calls (Requests)

Introduction

This guide will detail each step to making test calls with the Apollo API. For the purposes of the article, we will be using Postman to create example calls. Note that you must have this application set up properly (detailed here) before being able to make calls with it. Previous experience with APIs is recommended, but not required. If you are a developer who is looking to use the Apollo API, then we recommend reading through our technical documentation here first to see if it has what you need to get started.

Overview

The moment you send a request to a server, such as when you log into an app, that is what counts as making an API "call". Some other common examples of API calls include completing an online transaction, or asking a question via a web browser. For the Apollo API, calls correspond to the various actions that you can take within our web app. These include things such as searching for companies, creating a contact, or updating the stage for a group of accounts.

That said, when testing or using our API, please note that we have a set limit on the number of calls that can be made per minute, per hour, and per day. Your specific limits will depend on your plan, as noted on our pricing page (scroll to Compare Plans > CRM > API Access). Calls are only counted when a request is made to our server (such as in the examples shown later in this article). Furthermore, they are not counted differently depending on the number of records that may be returned or updated in a single request.

Documentation

Our API documentation details what types of calls are possible and how they must be configured. All available sections and actions are also listed and linked below:

• Authentication
  • Authentication
• People API (People = records that are in Apollo's database)
  • Search
  • Enrichment
• Organizations API
  • Enrichment
  • Organization Job Postings
• Contacts API (Contacts = records that have been saved to your account)
  • Create a Contact
  • Update a Contact
  • Searching for Contacts
  • Getting a List of Contact Stages
  • Updating Contact Stage
  • Updating Contact Ownership
• Accounts API
  • Searching for Accounts
  • Getting a List of Account Stages
  • Updating Account Stage
  • Updating Account Ownership
• Sequences API
  • Searching for Sequences
  • Adding Contacts to a Sequence
  • Removing Contacts From a Sequence / Marking Contacts as Finished in a Sequence
• Misc.
  • Get a List of Users
  • Get a List of Email Accounts
  • Get a List of All Lists
  • Get a List of All Custom Fields

Documentation Walkthrough

Each page of our API documentation will look something like this:

The People API > Search page is shown above (found here), and you will see a description of what it's for at the top:

And on the right:

For reference, an "endpoint" is a website URL (or, more specifically, the "end" of a URL) that APIs can request information from, or send information to (i.e. call). For the most part, different endpoints are needed for different actions in Apollo.

With that in mind, you will find the endpoint for the action in this example (i.e. searching for people in our database) at the top of the page:

Beneath it, you will see some of the query parameters that can be used (i.e. the specific information being requested or sent) when making a call to the endpoint:

Because the endpoint in this example allows you to search through people in our database, the query parameters reflect the types of things you can search for (in this case, think of them like the filters you can apply from the People page or Companies page in our web app). This section also shows how the query parameters must be formed in order for the call to work (found in the "Example" column above).

And lastly, on the right side of the page, you will see a complete example of what a call to the given endpoint might look like:

• Notes: 
  • Postman (the application we're using to make the API calls shown below) will use the top and bottom lines from examples like this, but in different places.
  • The top line contains the "headers", which are keys and values (detailed below).
  • The bottom line is the endpoint being called.

Next up, the sections below show some examples of how you can leverage all of this information within Postman.

Double Checking Your Headers

Before making any calls to our API, be sure to check that you have the correct headers applied within Postman (as detailed under the "Log in to the Apollo API" section of this article).

The most important header is your API key, which can be found by going to Settings > Integrations and clicking Connect next to the API option:

Once you have that, open the Headers tab in Postman (shown in the screenshot below) and confirm that the following keys and values are entered:

 

Key	Value
Content-Type	application/json
Cache-Control	no-cache
x-api-key	YOUR_API_KEY

• Notes:
  • For "x-api-key", be sure to paste your API key in the value column (mine is blurred in the example below).
  • The first two keys and values can be found in the top lines of example code from our API documentation. These do not change.

As long as these headers are present, you are ready to begin making the example calls detailed below.

Search for a Person

To see the API documentation for this, go here. 

This section details how you can use Postman to search for people in Apollo's database. For this action, you will need to copy and paste the following URL (endpoint) into Postman's "Enter request URL" field: 

https://api.apollo.io/v1/mixed_people/search

From there, check the type of request that must be made, which is specified in the example code from the documentation (here):

curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{
    "api_key": "YOUR API KEY HERE",
    "q_organization_domains": "apollo.io\ngoogle.com",
    "page" : 1,
    "person_titles" : ["sales manager", "engineer manager"]
}' "https://api.apollo.io/v1/mixed_people/search"

Now select the corresponding POST option within the request type dropdown in Postman:

Next, you will need to click on the Body tab within Postman so you can specify the parameters for your call:

In this case, the first parameters you enter should be the attributes you are searching for. For reference, you can find some of the possible parameters - and their required format - in the screen below (found here):

• Note: The "api_key" parameter (shown in the second screen below) is not listed here.

The following example shows how you can use these parameters in Postman:

Here, we are searching for people in our database who both:

1. Have an organization domain that is either google.com, facebook.com, or twitter.com 
2. Have a title that is either product manager or software engineer

• Notes:
  • You must begin and end the call with { and }, and each must be on their own lines.
  • Each parameter must be in quotations " ", and must also have a colon : at the end.
  • Make sure that your call has a coma after every line except for the last.

Finally, for the last step, you will need to click the blue Send button on the right-hand side of Postman. If the call was formatted correctly, then you will see "200 OK" appear in the Status field (highlighted below), followed by a response in the Body section of the response window:

Congratulations! It is within this response that you will see the search results of your API call.

• Notes:
  • This endpoint does not use any credits, so it will not show emails for people you haven't saved yet (it will show "email_not_unlocked@domain.com" instead). To get around this, you must use the enrichment endpoint (here).
  • You might see separate lists of "contacts" (records you have saved to Apollo) and "people" (records you have not saved yet) within the response. 

Search for a Contact

To see the API documentation for this, go here.

This section details how you can use Postman to search for saved contacts in Apollo. For this action, you will need to copy and paste the following URL (endpoint) into Postman's "Enter request URL" field: 

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

From there, check the type of request that must be made, which is specified in the example code from the documentation (here):

curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{
    "api_key": "YOUR API KEY HERE",
    "sort_by_field": "contact_last_activity_date",
    "sort_ascending": false
}' "https://api.apollo.io/v1/contacts/search"

Now select the corresponding POST option within the request type dropdown in Postman:

Next, you will need to click on the Body tab within Postman so you can specify the parameters for your call:

For this action, the first parameter should be for the keywords you are searching for. For reference, you can find some of the possible parameters - and their required format - in the screen below (found here):

• Note: The "api_key" parameter (shown in the second screen below) is not listed here.

The following example shows how you can use these parameters in Postman:

Here, we are searching for a saved contact in our database whose:

1. Name is Tim Zheng
2. Title is CEO
3. Company is Apollo

• Notes:
  • Because we are effectively using a version of the "keywords" filter here (found in the Companies page of our web app), we don't have to specify which parts of the call are the name, title, or company. 
  • You must begin and end the call with { and }, and each must be on their own lines.
  • Each parameter must be in quotations " ", and must also have a colon : at the end.
  • Make sure that your call has a coma , after every line except for the last.

Finally, for the last step, you will need to click the blue Send button on the right-hand side of Postman. If the call was formatted correctly, then you will see "200 OK" appear in the Status field (highlighted below), followed by a response in the Body section of the response window:

Congratulations! It is within this response that you will see the saved contact or contacts that you are searching for.

Enrich a Person's Information

To see the API documentation for this, go here.

This section details how you can use Postman to enrich a person with information from our database. For this action, you will need to copy and paste the following URL (endpoint) into Postman's "Enter request URL" field: 

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

From there, check the type of request that must be made, which is specified in the example code from the documentation (here):

curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{
    "api_key": "YOUR API KEY HERE",
    "id": "583f2f7ed9ced98ab5bfXXXX",
    "first_name": "Tim",
    "last_name": "Zheng",
    "organization_name": "Apollo",
    "email": "tim@apollo.io",
    "domain": "apollo.io"
}' "https://api.apollo.io/v1/people/match"

Now select the corresponding POST option within the request type dropdown in Postman:

Next, you will need to click on the Body tab within Postman so you can specify the parameters for your call:

In this case, the parameters will represent the attributes that identify the person you're trying to enrich. The more attributes you enter, the more likely we can find a match. For reference, you can find some of the possible parameters - and their required format - in the screen below (found here):

• Note: The "api_key" parameter (shown in the second screen below) is not listed here.

The following example shows how you can use these parameters in Postman:

Here, we are attempting to enrich someone with information from our database whose:

1. First name is Tim
2. Last name is Zheng
3. Organization (company) name is Apollo

• Notes:
  • You must begin and end the call with { and }, and each must be on their own lines.
  • Each parameter must be in quotations " ", and must also have a colon : at the end.
  • Make sure that your call has a coma , after every line except for the last.

Finally, for the last step, you will need to click the blue Send button on the right-hand side of Postman. If the call was formatted correctly, then you will see "200 OK" appear in the Status field (highlighted below), followed by a response in the Body section of the response window:

As long as we can find a record that matches the parameters you passed in, then we will show you his or her information in the response section. This includes email, if we have it. And that's how you enrich people with the Apollo API!