Apollo.io Prospect Search & Enrichment
Build a prospect list from Apollo's B2B database: search people by job title, seniority and location, or companies by headcount and industry, check who a company is hiring for, and enrich a person or domain with verified details. Save the good fits as contacts, set their stage and add them to an Apollo list.
Connect this API to an AI agent Browse all specs
What you can do with Apollo.io Prospect Search & Enrichment via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| POST | /mixed_people/api_search |
searchPeople | Search Apollo's database for people by title, seniority, location or company |
| POST | /mixed_companies/search |
searchOrganizations | Search for companies by name, location, headcount or industry keywords (1 credit per page) |
| GET | /organizations/{organization_id}/job_postings |
listOrganizationJobPostings | List a company's current job postings (1 credit per page) |
| POST | /people/match |
enrichPerson | Enrich one person with title, company and contact details (uses credits) |
| GET | /organizations/enrich |
enrichOrganization | Enrich a company by its domain (uses credits) |
| POST | /contacts/search |
searchContacts | Search the contacts your team has saved |
| GET | /contacts/{contact_id} |
getContact | View a saved contact |
| PATCH | /contacts/{contact_id} |
updateContact | Update a contact's details |
| GET | /contact_stages |
listContactStages | List contact stages and their ids |
| GET | /labels |
listLists | List your Apollo lists |
| POST | /contacts |
createContact | Save a person as a contact |
| POST | /contacts/update_stages |
updateContactStages | Move one or more contacts to a contact stage |
| POST | /labels/add_entity_ids_to_label_names |
addRecordsToList | Add contacts or accounts to a list |
Authentication
apiKey
API key — sent as the x-api-key header
An Apollo.io API key, sent in the x-api-key header.
How to get a credential
- Sign in to Apollo and open Settings > Integrations > API Keys.
- Click Create new key, enter a name (e.g. VX Agents) and a description.
- Select the endpoints the key may call (see the table below), or turn on Set as master key for all endpoints.
- Click Create API key and copy the key.
Permissions used
Apollo keys are scoped by endpoint. A scoped key returns 403 on endpoints it was not given.
| Endpoint to enable | Operations |
|---|---|
| People API Search (0 credits) | searchPeople |
| Organization Search, Organization Job Postings (1 credit per page) | searchOrganizations, listOrganizationJobPostings |
| People Enrichment, Organization Enrichment (credits per record) | enrichPerson, enrichOrganization |
| Contacts (search, view, create, update, stages) | searchContacts, getContact, createContact, updateContact, listContactStages, updateContactStages |
| Lists | listLists, addRecordsToList |
Common errors
| Status | Meaning | Fix |
|---|---|---|
| 401 | Key missing or invalid | Copy the key again or create a new one. |
| 403 | The key is not allowed to call this endpoint, or the plan does not include API access | Edit the key's endpoints, use a master key, or check the Apollo plan. |
| 422 / 400 | Invalid parameter, e.g. an unknown stage id | Look ids up with listContactStages or listLists. |
| 429 | Rate limit for this endpoint (per minute, hour or day; see the Usage tab) | Wait and retry later. |
Store the key as an API key credential in VX Agents; never paste it into chat.
Usage guide
Setup
- Credential: an Apollo API key (Settings > Integrations > API Keys), stored as an API key credential; it is sent in
x-api-key. Give the key the endpoints listed in its auth notes, or make it a master key. - Credits:
searchPeopleand all contact/list calls are free;searchOrganizationsandlistOrganizationJobPostingscost 1 credit per page;enrichPersoncosts 1-9 credits per person andenrichOrganization1 per company. Tell the user the cost and get a yes before calling a paid endpoint.
Build a prospect list
searchPeoplewith filters as query parameters, e.g.person_titles[]=head of marketing,person_seniorities[]=director,person_locations[]=Germany,organization_num_employees_ranges[]=51,200,q_organization_domains_list[]=example.com. It returns people and their company but no emails or phone numbers. Page withpageandper_page(max 100).searchOrganizations(q_organization_name,organization_locations[],q_organization_keyword_tags[], headcount ranges) to find companies;listOrganizationJobPostingswith an organizationidto see who they are hiring.enrichPersonwith an Apollo personid,email,linkedin_url, or name plusdomain, to get the work email.reveal_phone_numberneeds awebhook_urland costs more.enrichOrganizationwithdomain.- Save a good fit with
createContact(first_name,last_name,email,organization_name,title; setrun_dedupe: trueto avoid duplicates). Confirm with the user first. listContactStages, thenupdateContactStageswithcontact_ids[]andcontact_stage_id.addRecordsToListwithentity_ids,label_namesandmodality: "contacts"(an unknown list name creates the list).
Work saved contacts
searchContactswithq_keywords(name, title, company or email),contact_stage_idsorcontact_label_ids(fromlistLists).getContact, thenupdateContactfor changed details. Confirm before changing contact data.
Good to know
- Person ids (from search) and contact ids (saved records) are different things.
- People search shows at most 50,000 records (500 pages of 100): add filters to narrow it.
- Rate limits are per endpoint (minute, hour, day); see the Usage tab in Apollo. 403 usually means the key lacks that endpoint.
- Sequences, deals and bulk enrichment are not part of this spec.
Source: Apollo.io API reference (https://docs.apollo.io/reference/people-api-search), checked 2026-10-22.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Apollo.io Prospect Search & Enrichment” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.