Find People Using Filters
Overview
Apollo offers a highly accurate database of hundreds of millions of people, enabling you to find and connect with your ideal customers across the world. The People API enables you to find the prospects most likely to benefit from your product or service through targeted search filters.
Credits
Using this endpoint does consume your account’s credits. Refer to Apollo’s API pricing page for more details.
The following section describes how to search for and filter people using Apollo's People API.
Before You Start: Check Out Reference Docs
Apollo’s API reference docs show the query parameters available for you to use with the People 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: Search for Sales Directors Based on the West Coast of the US
To show how the People API can be used with Apollo’s search filters, let’s walk through a scenario: finding people that are currently Sales Directors that are personally located in US states on the west coast (California, Oregon, and Washington).
To find people matching these demographics:
- Call the People Search endpoint:
POST https://api.apollo.io/v1/mixed_people/search
- Add the following query parameters:
| Parameter | Value for this Example | Notes |
|---|---|---|
| person_titles | ["sales director", "director sales", "director, sales"] | Your search filters need to be added as an array of strings. |
| person_locations | ["California, US", "Oregon, US", "Washington, US"] | Your search filters need to be added as an array of strings. The person_locations parameter should be used to find people based on their own location. To search for people based on the headquarters location of their current employer, use the organization_locations parameter. |
| per_page | 5 | Your value should be an integer between 1 and 100. This parameter can be used to specify how many results to return per page. |
- Add the following keys and values to the header of your request:
- Content-Type:
application/json - Cache-Control:
no-cache - X-Api-Key: Enter your Apollo API key.
- Content-Type:
cURL Request
The following code sample shows the example as a cURL request:
curl --request POST \
--url 'https://api.apollo.io/api/v1/mixed_people/search?person_titles[]=sales%20director&person_titles[]=director%20sales&person_titles[]=director%2C%20sales&person_locations[]=California%2C%20US&person_locations[]=Oregon%2C%20US&person_locations[]=Washington%2C%20US&per_page=5' \
--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:
"people": [
{
"id": "662c927b318ebe00078b1b1d",
"first_name": "Suzanne",
"last_name": "Summers",
"name": "Suzanne Summers",
"linkedin_url": "http://www.linkedin.com/in/suzanne-summers-02676",
"title": "Director of Sales",
"email_status": "verified",
"photo_url": "https://static.licdn.com/aero-v1/sc/h/9c8pery4andzj6ohjkjp54m",
"twitter_url": null,
"github_url": null,
"facebook_url": null,
"extrapolated_email_confidence": null,
"headline": "Director of Sales at Farm",
"email": "[email protected]",
"organization_id": "5592354d716964135f31cf02",
"employment_history": [
{
"_id": "666fcd69b400bf0001e4e9b9",
"created_at": null,
"current": true,
"degree": null,
"description": null,
"emails": null,
"end_date": null,
"grade_level": null,
"kind": null,
"major": null,
"organization_id": "5592354d716964135f31cf02",
"organization_name": "Armstrong Growers",
"raw_address": null,
"start_date": "2022-12-01",
"title": "Director of Sales",
"updated_at": null,
"id": "666fcd69b400bf0001e4e9b9",
"key": "666fcd69b400bf0001e4e9b9"
},
...
],
"state": "California",
"city": "Glendora",
"country": "United States",
"organization": {
"id": "5592354d716964135f31cf02",
"name": "Farm Growers",
"website_url": "http://www.garmgrowers.com",
"blog_url": null,
"angellist_url": null,
"linkedin_url": "http://www.linkedin.com/company/farm-growers",
"twitter_url": null,
"facebook_url": null,
"primary_phone": {
"number": "+1 555-123-1091",
"source": "Owler",
"sanitized_number": "+15551231091"
},
"languages": [],
"alexa_ranking": null,
"phone": "+1 555-123-1091",
"linkedin_uid": "5929027",
"founded_year": 1889,
"publicly_traded_symbol": null,
"publicly_traded_exchange": null,
"logo_url": "https://zenprospect-production.s3.amazonaws.com/uploads/pictures/65c211a030fb27000192ec87/picture",
"crunchbase_url": null,
"primary_domain": "farmgrowers.com",
"sanitized_phone": "+15551231091"
},
"is_likely_to_engage": false,
"departments": [
"master_sales"
],
"subdepartments": [
"sales"
],
"seniority": "director",
"functions": [
"sales"
],
"phone_numbers": [
{
"raw_number": "+1 555-123-1091",
"sanitized_number": "+15551231091",
"type": "work_hq",
"position": 0,
"status": "no_status",
"dnc_status": null,
"dnc_other_info": null,
"dialer_flags": null
}
],
...
The following table details some key elements of the API response:
| Element | Description |
|---|---|
"title" | The value in this object shows the job title for the person. |
"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. |
Updated 23 days ago