A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Apollo API is how an app or AI agent works with a sales account: searching Apollo's database of people and companies, enriching a contact with verified details, saving and updating the team's own contacts and accounts, and adding people to outreach sequences. Access is granted through an account-level API key sent in a header, and that key is either a master key that reaches every endpoint or a scoped key limited to the endpoints chosen for it. Some endpoints draw down account credits, and several are reachable only with a master key.
How an app or AI agent connects to Apollo determines what it can reach. There are two routes, a direct API key for server calls and an official MCP server for AI assistants, each governed by the credential behind it.
The REST API answers at https://api.apollo.io under the /api/v1 path. Each call carries the API key in an X-Api-Key header, and there is a single live version with no dated version to pin.
Apollo's official remote MCP server lets an AI assistant search, enrich, and act on contacts through the Model Context Protocol. It answers at https://mcp.apollo.io/mcp over streamable HTTP, signs in through a browser-based OAuth flow, and reflects the signed-in user's Apollo permissions, plan, and available credits.
A master API key has access to every Apollo API endpoint, including the ones that only a master key can call, such as sequences, tasks, deals, users, and usage stats. Anyone holding it can take action across the whole Apollo account.
A scoped API key is restricted to the specific endpoints chosen when it is created. The scope is at the endpoint level only, so there are no finer per-data-type permissions, and endpoints that require a master key return 403 to a scoped key.
The official MCP server uses a browser-based OAuth 2.0 flow instead of an API key. The signed-in user authorizes access to their workspace, and the assistant can then act only within that user's own Apollo permissions, plan, and credits.
The Apollo API is split into areas an agent can act on, such as the people and organization databases, the contacts and accounts a team has saved, sequences, tasks, and deals. Some endpoints read public prospect data, while others change records the team owns, and several consume account credits.
Search Apollo's database of people, and enrich one person or a batch with matched contact and company data.
Search Apollo's database of companies and enrich a company with firmographic data.
Create, update, and search the contacts a team has saved into its own Apollo account.
Create, update, and search the accounts, the companies a team has saved into its own Apollo account.
Search the team's outreach sequences and add saved contacts into a sequence.
Create and search the tasks a team tracks against its contacts and accounts.
Create, update, and list the deals a team tracks against its accounts.
List the teammates in a team's Apollo account.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
People & enrichmentSearch Apollo's database of people, and enrich one person or a batch with matched contact and company data.3 | ||||||
| POST | /api/v1/mixed_people/api_search | Search Apollo's database to find net new people, using filters like job title, seniority, location, and company attributes. | read | — | Current | |
Optimized for API use and does not consume credits. Returns up to 50,000 records (100 per page, up to 500 pages). Apollo keys are not scoped per data type, so a key either has access to this endpoint or it does not. Acts onperson Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/people/match | Enrich one person, matching the details provided against Apollo's database to fill in contact and company data. | read | — | Current | |
Consumes credits. Personal emails and phone numbers are returned only when reveal_personal_emails and reveal_phone_number are set, and those, plus waterfall enrichment, draw extra credits. Acts onperson Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/people/bulk_match | Enrich up to 10 people in a single call. | read | — | Current | |
Consumes credits per person enriched, plus extra for revealed emails or phone numbers and for waterfall enrichment. Acts onperson Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OrganizationsSearch Apollo's database of companies and enrich a company with firmographic data.2 | ||||||
| POST | /api/v1/mixed_companies/search | Search Apollo's database to find companies, using filters like domain, employee count, location, revenue, and technologies. | read | — | Current | |
Consumes credits as part of the account's pricing plan. Acts onorganization Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/organizations/enrich | Enrich one company, returning firmographics such as industry, revenue, employee count, and funding. | read | — | Current | |
Consumes credits. At least one of domain, LinkedIn URL, name, or website must be supplied. Acts onorganization Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ContactsCreate, update, and search the contacts a team has saved into its own Apollo account.3 | ||||||
| POST | /api/v1/contacts | Add a new contact to the team's own Apollo account. | write | — | Current | |
Set run_dedupe to true to avoid creating a duplicate contact. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v1/contacts/{contact_id} | Update an existing contact in the team's Apollo account. | write | — | Current | |
The contact_id path parameter is the Apollo ID of the contact to change. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/contacts/search | Search the contacts the team has saved into its own Apollo account. | read | — | Current | |
Searches only the team's own saved contacts, not the wider Apollo database. Returns up to 50,000 records (100 per page, up to 500 pages). Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AccountsCreate, update, and search the accounts, the companies a team has saved into its own Apollo account.3 | ||||||
| POST | /api/v1/accounts | Add a new company as an account in the team's own Apollo database. | write | — | Current | |
An account is a company the team has explicitly added to its own database. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v1/accounts/{account_id} | Update an existing account in the team's Apollo database. | write | — | Current | |
The account_id path parameter is the Apollo ID of the account to change. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/accounts/search | Search the accounts the team has saved into its own Apollo account. | read | — | Current | |
Searches only the team's own saved accounts, not the wider Apollo database. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SequencesSearch the team's outreach sequences and add saved contacts into a sequence.2 | ||||||
| POST | /api/v1/emailer_campaigns/search | Search the outreach sequences created for the team's Apollo account. | read | — | Current | |
Sequences are called emailer_campaigns in the API. Requires a master API key; a scoped key returns 403. Acts onsequence Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/emailer_campaigns/{sequence_id}/add_contact_ids | Add one or more saved contacts to a sequence, which can begin automated outreach. | write | — | Current | |
Adds contacts by their Apollo IDs to the sequence named in the path. Requires a master API key; a scoped key returns 403. Acts onsequence Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TasksCreate and search the tasks a team tracks against its contacts and accounts.2 | ||||||
| POST | /api/v1/tasks | Create a task in Apollo to track an upcoming action, such as emailing or calling a contact. | write | — | Current | |
Requires a master API key; a scoped key returns 403. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/tasks/search | Search the tasks created for the team's Apollo account. | read | — | Current | |
Requires a master API key; a scoped key returns 403. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DealsCreate, update, and list the deals a team tracks against its accounts.3 | ||||||
| POST | /api/v1/opportunities | Create a deal, tracking account activity such as monetary value, deal owner, and stage. | write | — | Current | |
Deals are called opportunities in the API. Requires a master API key; a scoped key returns 403. Acts ondeal Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v1/opportunities/{opportunity_id} | Update an existing deal, such as its value, owner, or stage. | write | — | Current | |
The opportunity_id path parameter is the Apollo ID of the deal to change. Requires a master API key; a scoped key returns 403. Acts ondeal Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/opportunities/search | List every deal created for the team's Apollo account. | read | — | Current | |
Requires a master API key; a scoped key returns 403. Acts ondeal Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersList the teammates in a team's Apollo account.2 | ||||||
| GET | /api/v1/users/search | List the teammates in the team's Apollo account, returning their names and IDs. | read | — | Current | |
Used to find the user IDs needed as deal owners or task owners. Requires a master API key; a scoped key returns 403. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/usage_stats/api_usage_stats | Retrieve the current API usage and rate limits for the account. | read | — | Current | |
Reports the per-minute, per-hour, and per-day limits and how much has been used, per endpoint. Requires a master API key; a scoped key returns 403. Acts onusage stats Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Apollo does not document a general event-subscription webhook system on its public API. The one webhook it does support is asynchronous delivery of enrichment results: a webhook_url passed on an enrichment call receives the matched emails and phone numbers once Apollo has verified them, which is mandatory when revealing phone numbers.
| Event | What it signals | Triggered by |
|---|
Apollo limits how fast an app or AI agent can call, with a separate per-minute, per-hour, and per-day ceiling on each endpoint that depends on the account's pricing plan. Enrichment and database endpoints also draw down account credits.
Apollo sets rate limits per endpoint, with a separate per-minute, per-hour, and per-day ceiling on each, using a fixed-window strategy where the full allowance can be spent at any point inside the window before it resets. The exact numbers depend on the account's pricing plan, so a higher plan raises the limits. Going over any window returns 429. The current limits and how much has been used are reported in the headers of a successful response and through the api_usage_stats endpoint, which needs a master API key. Apollo does not publish a single fixed table of numbers, because they vary by plan and endpoint, so an integration should read its own limits from the usage stats endpoint rather than assume a value.
Search endpoints use page-based pagination through the page and per_page parameters, where per_page tops out at 100. The people, contacts, and account search endpoints return at most 50,000 records per query, which is 100 records per page across up to 500 pages.
Requests and responses are JSON. Bulk people enrichment takes up to 10 people in a single call. There is no single documented payload size limit across the API.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | The API key is missing or invalid. | Send a valid key in the X-Api-Key header. |
| 403 | Forbidden | The request is authenticated but not permitted. Most often the key is a scoped key calling an endpoint that requires a master key, or the account's plan does not include the feature. | Use a master API key for master-only endpoints, or confirm the plan includes the feature. |
| 404 | Not Found | The path or the referenced record does not exist. | Check the endpoint path and the ID in the request. |
| 422 | Unprocessable Entity | The request was well-formed but a parameter is missing or invalid, so Apollo could not process it. | Correct the named parameters and resend. |
| 429 | Too Many Requests | A per-minute, per-hour, or per-day rate limit for the endpoint was exceeded. | Slow down and retry after the window resets, and check the usage stats endpoint for the current limits. |
Apollo serves a single, continuously updated version of its API, reached under the v1 path. There is no dated version to pin, and changes ship through the release notes.
Apollo serves one continuously updated version of its API under the v1 path. There is no dated version to pin and no version header to send, so an integration always calls the current API. Changes ship through the release notes rather than as a new version string.
Because there is one live version, an integration always calls the current API and watches the release notes for changes.
Apollo API release notes ↗Bollard AI sits between a team's AI agents and Apollo. Grant each agent exactly the access it needs, read or write, action by action, and every call is checked and logged.