Skip to content
Changelog

Report a bug

Apollo integration: operations for AI agents

Apollo connects to Type.com as an integration. This page lists the 82 operations documented for Claude and Codex in Type.com: 43 read, 35 write, 4 destructive.

About Apollo

Apollo provides CRM and lead generation capabilities, helping businesses discover contacts, manage outreach, and track sales pipelines for consistent customer relationship development

Categories: Sales & CRM

How to connect Apollo to Type.com

Connect
Managed OAuth through Pipedream when enabled for your workspace; API key
Access
Organization connection: one shared account for the workspace.

To add the connection, follow the steps in Space connections.

Documented operations

82 operations. Your connection's permissions determine which operations are available. API references describe the vendor surface; they do not expand your connection's credentials or access.

82 operations listed.

AI Assistant

  • Read

    Poll an Assistant task

    An Apollo AI Assistant (https://knowledge.apollo.io/hc/en-us/articles/39359204112397-AI-Assistant-Overview) task is a conversation in which you give instructions, receive results, and answer follow-up questions. Use the poll an Assistant task endpoint to check the progress of a task you created with the run an Assistant task (https://docs.apollo.io/reference/run-an-assistant-task) endpoint. It returns immediately with the task's `status`, its messages, and a `cursor`. It only reads the task: it never waits for the task to finish, and it never starts or continues a task. Any `instruction` you send to this endpoint is ignored. ## Poll for results Send the `task_id`. Omit `cursor` on your first poll; on later polls, pass the `cursor` from your previous response: ```json { "task_id": "507f1f77bcf86cd799439011", "cursor": 0 } ``` The response returns only the messages with a sequence number strictly greater than `cursor`, plus a new `cursor`. Pass that new `cursor` on your next poll. An empty `messages` array means nothing new has been added yet; it does not mean the task has finished, so check `status`. Omit `cursor` to receive the full conversation. While the task is `running`, the response includes `poll_after_ms` (`10000`, or 10 seconds). Wait that long before you poll again. | Status | What to do | | --- | --- | | running | Wait `poll_after_ms`, then poll again with the new `cursor`. | | awaiting_input | Read `question`, then answer by calling the run an Assistant task (https://docs.apollo.io/reference/run-an-assistant-task) endpoint with the same `task_id` and your answer as `instruction`. The response also includes `error_type: "elicitation_required"`; this is a request for input, not an HTTP error. | | complete | Read the result. To send a follow-up, call the run an Assistant task endpoint with the same `task_id` and a new `instruction`. | | failed | Stop polling and inspect any returned messages. | `question` is the latest Assistant message in the returned batch, so it appears in the poll where that message first arrives. If a later poll returns no new messages, `question` is `null`; omit `cursor` to read the full conversation again. Set a polling deadline in your client and handle a task that remains `running`. This endpoint does not promise a fixed completion time. Poll with the same acting user that created the task. A task created by another user returns `403`. See which user API requests act as (https://docs.apollo.io/reference/authentication#which-user-do-your-requests-act-as).

    POST /agents/poll_task

  • Write

    Run an Assistant task

    An Apollo AI Assistant (https://knowledge.apollo.io/hc/en-us/articles/39359204112397-AI-Assistant-Overview) task is a conversation in which you give instructions, receive results, and answer follow-up questions. It is separate from a CRM task created with the create a task (https://docs.apollo.io/reference/create-a-task) endpoint. Use `POST /api/v1/agents/task` to create, poll, and continue an Assistant task. All three operations return HTTP `200` on success. A successful submission means the instruction was accepted, not that the Assistant has completed it. Use the same acting user for the task's lifetime. See which user API requests act as (https://docs.apollo.io/reference/authentication#which-user-do-your-requests-act-as). The Assistant can perform actions using that user's permissions. Restricting the API key to specific endpoints does not restrict which actions the Assistant can perform. ## Create a task Send an `instruction` without a `task_id`: ```json { "instruction": "Find companies matching my ideal customer profile." } ``` Save the returned `task_id`. The response also includes `status: "running"`, a `next_action` polling hint, and `poll_after_ms`, the number of milliseconds to wait before you poll (`10000`, or 10 seconds). The hint names the `apollo_agent_poll_task` MCP tool; API clients poll with the poll an Assistant task (https://docs.apollo.io/reference/poll-an-assistant-task) endpoint instead, or with this endpoint as described below. ## Poll for results We recommend polling with the poll an Assistant task (https://docs.apollo.io/reference/poll-an-assistant-task) endpoint. You can also poll with this endpoint. Wait `poll_after_ms` (10 seconds) between polls. Send the `task_id` and omit `instruction`: ```json { "task_id": "507f1f77bcf86cd799439011" } ``` The response includes `status`, `messages`, and `latest_seq_num`. While the task is `running`, the response also includes `next_action` and `poll_after_ms`. Messages contain `seq_num`, `role`, and flattened `text`. Hidden messages and non-text content are excluded. | Status | What to do | | --- | --- | | running | Continue polling. | | awaiting_input | Read `question` and the conversation, then submit your answer with the same `task_id`. The response also includes `error_type: "elicitation_required"`; this is a request for input, not an HTTP error. | | complete | Read the result. You can submit another instruction with the same `task_id`. | | failed | Stop polling and inspect any returned messages. | An empty `messages` array does not mean the task has finished; check `status`. Set a polling deadline in your client and handle a task that remains `running`. This endpoint does not promise a fixed completion time or accept a webhook URL. Repeating a create request without a `task_id` creates another task. ## Continue a task When the status is `awaiting_input` or `complete`, send another instruction with the existing ID: ```json { "task_id": "507f1f77bcf86cd799439011", "instruction": "Yes, continue." } ``` The response retains the same `task_id`. If you submit an instruction while the task is `running`, it is ignored: the endpoint returns the current polling result and a `note` explaining that you should wait. It does not queue that instruction for later.

    POST /agents/task

Enrichment

  • Read

    Organization enrichment

    Enrichment (https://knowledge.apollo.io/hc/en-us/articles/33699917233293-Enrichment-Overview) is when you refresh existing records so your prospecting data is up-to-date. Use the organization enrichment endpoint to enrich data for one company. To enrich data for up to ten companies with a single API call, use the bulk organization enrichment endpoint (https://docs.apollo.io/reference/bulk-organization-enrichment) instead. Identify a company using its domain, LinkedIn URL, or website. You can include its name to improve match accuracy, but name alone is not supported. Enriched data potentially includes industry information, revenue, employee counts, funding round details, corporate phone numbers, locations, language counts, retail-location counts, and organization hierarchy data. The owned_by_organization field identifies the immediate parent, owned_by_chain lists parent organization IDs from the immediate parent to the ultimate parent, and ultimate_parent_organization identifies the topmost parent. The suborganizations array includes each direct subsidiary's industries, estimated employee count, and country when available.

    GET /organizations/enrich

  • Read

    Bulk organization enrichment

    Enrichment (https://knowledge.apollo.io/hc/en-us/articles/33699917233293-Enrichment-Overview) is when you refresh existing records so your prospecting data is up-to-date. Use the bulk organization enrichment endpoint to enrich data for up to ten companies with a single API call. To enrich data for a single company, use the organization enrichment endpoint (https://docs.apollo.io/reference/organization-enrichment) instead. You can identify the companies to enrich by providing a list of domains via the domains[] query parameter, or by providing a details array in the request body where each company can be matched by any combination of domain, LinkedIn URL, name, and website. Enriched data potentially includes industry information, revenue, employee counts, funding round details, corporate phone numbers, locations, language counts, retail-location counts, and organization hierarchy data. The owned_by_organization field identifies the immediate parent, owned_by_chain lists parent organization IDs from the immediate parent to the ultimate parent, and ultimate_parent_organization identifies the topmost parent. Each result also includes num_suborganizations and subsidiary_rollups with the total estimated subsidiary employee count and distinct subsidiary countries and industries.

    POST /organizations/bulk_enrich

  • Write

    People enrichment

    Credits are charged only if credit-consuming data is found: 1 credit for demographics or email, plus 8 credits if a mobile phone is returned. If no credit-consuming data is found, the request consumes 0 credits. Demographic credit usage depends on `match_confidence`. Apollo doesn't charge a demographic credit when `match_confidence` is `none`. When `match_confidence` is `low`, Apollo charges a demographic credit only if it returns data you didn't send. Email and mobile phone credit usage isn't determined by `match_confidence`. Learn more about [API pricing and credits](https://docs.apollo.io/docs/api-pricing). If waterfall enrichment is used for phone or email, credit usage depends on the returned data and the vendors included in your [waterfall enrichment configuration](https://knowledge.apollo.io/hc/en-us/articles/34071121664781-Use-Waterfall-Enrichment); some vendors consume credits per lookup even when no data is found. Enrichment (https://knowledge.apollo.io/hc/en-us/articles/33699917233293-Enrichment-Overview) is when you refresh existing records so your prospecting data is up-to-date. Use the people enrichment endpoint to enrich data for one person. To enrich data for up to ten people with a single API call, use the bulk people enrichment endpoint (https://docs.apollo.io/reference/bulk-people-enrichment) instead. Apollo relies on the information you pass via the endpoint's parameters to identify the correct person to enrich. If you provide more information about a person, Apollo is more likely to find a match within its database. If you only provide general information, such as a name without a domain or email address, you might receive a `200` response, but the response indicates that no records have been enriched. Check `match_confidence` in the response to understand how confidently Apollo matched the submitted information: - `high`: Apollo matched the information to a person record. - `medium`: Apollo identified a likely person using additional contact data. - `low`: Apollo couldn't match a complete person record, but returned person data assembled from available contact data. - `none`: Apollo couldn't identify a matching person. By default, this endpoint doesn't return personal emails or phone numbers. Use the `reveal_personal_emails` and `reveal_phone_number` parameters to retrieve emails and phone numbers. When you use `reveal_phone_number`, a valid `webhook_url` is required so Apollo can deliver the completed phone enrichment results. Apollo returns the main enrichment response synchronously, then sends the requested phone numbers to the webhook asynchronously. [See webhook details](#webhook-details). You can also use the `run_waterfall_email` and `run_waterfall_phone` parameters to run waterfall enrichment via this endpoint. [Waterfall enrichment](https://knowledge.apollo.io/hc/en-us/articles/34071089002509-Waterfall-Enrichment-Overview) gives you broader data coverage by checking connected third-party data sources for contact emails and phone numbers. When you call this endpoint and include at least one waterfall parameter, a valid `webhook_url` is required so Apollo can deliver the completed waterfall enrichment results. Apollo returns an immediate synchronous response with demographic and firmographic data, along with a waterfall enrichment request status. Apollo then delivers enriched emails or phone numbers asynchronously to the configured webhook. ### Webhook Details - When using Apollo enrichment for phone number reveal, the webhook response follows: [Native webhook response details](doc:retrieve-mobile-phone-numbers-for-contacts#webhook-response). - When using waterfall enrichment, the webhook response follows: [Waterfall webhook response details](doc:enrich-phone-and-email-using-data-waterfall#asynchronous-webhook-response-1). - You can poll webhook results with the [poll webhook result](ref:poll-webhook-result) endpoint by passing the request_id from the people enrichment response. ### Webhook Requirements - **HTTPS Required:** Your endpoint must be publicly accessible over HTTPS. - **Rate Limiting:** Ensure your webhook endpoint can handle the volume of webhook traffic sent by Apollo. - **Idempotency:** Apollo may retry webhook calls; your endpoint should be idempotent to handle duplicate payloads safely.

    POST /people/match

  • Write

    Bulk people enrichment

    Credits are charged only if credit-consuming data is found: 1 credit for demographics or email, plus 8 credits if a mobile phone is returned. If no credit-consuming data is found, the request consumes 0 credits. Apollo doesn't charge a demographic credit when it can't match a person. With waterfall enrichment, this is indicated by `match_confidence: none`; for standard requests, unmatched people are returned as `null`. When `match_confidence` is `low`, Apollo charges a demographic credit only if it returns data you didn't send. You can enrich up to 10 people per request. Learn more about [API pricing and credits](https://docs.apollo.io/docs/api-pricing). If waterfall enrichment is used for phone or email, credit usage depends on the returned data and the vendors included in your [waterfall enrichment configuration](https://knowledge.apollo.io/hc/en-us/articles/34071121664781-Use-Waterfall-Enrichment); some vendors consume credits per lookup even when no data is found. Enrichment (https://knowledge.apollo.io/hc/en-us/articles/33699917233293-Enrichment-Overview) is when you refresh existing records so your prospecting data is up-to-date. Use the bulk people enrichment endpoint to enrich data for up to ten people with a single API call. To enrich data for a single person, use the people enrichment endpoint (https://docs.apollo.io/reference/people-enrichment) instead. Apollo relies on the information you pass via the endpoint's parameters to identify the correct people to enrich. The details for each person should be passed as an object in the `details[]` array. When you provide more information, Apollo is more likely to find matches within its database. If you only provide general information, such as a name without a domain or email address, you may receive a `200` response, but the response indicates that no records have been enriched. Check `match_confidence` in the response to understand how confidently Apollo matched the submitted information. By default, this endpoint doesn't return personal emails or phone numbers. Use the `reveal_personal_emails` parameter to retrieve personal emails and `reveal_phone_number` to retrieve phone numbers. If you set either of these parameters to `true`, Apollo attempts to provide emails or phone numbers for all matches. When you use `reveal_phone_number`, a valid `webhook_url` is required so Apollo can deliver the completed phone enrichment results. Apollo returns the main enrichment response synchronously, then sends the requested phone numbers to the webhook asynchronously. [See webhook details](#webhook-details). You can also use the `run_waterfall_email` and `run_waterfall_phone` parameters to run waterfall enrichment via this endpoint. [Waterfall enrichment](https://knowledge.apollo.io/hc/en-us/articles/34071089002509-Waterfall-Enrichment-Overview) gives you broader data coverage by checking connected third-party data sources for contact emails and phone numbers. When you call this endpoint and include at least one waterfall parameter, a valid `webhook_url` is required so Apollo can deliver the completed waterfall enrichment results. Apollo returns an immediate synchronous response with demographic and firmographic data, along with a waterfall enrichment request status. Apollo then delivers enriched emails or phone numbers asynchronously to the configured webhook. ### Reading the response The response differs depending on whether you use waterfall enrichment. For a standard request, the response includes `matches` along with: * `total_requested_enrichments` * `unique_enriched_records` * `missing_records` * `credits_consumed` Each person in `matches` also includes `match_confidence`, which indicates how confidently Apollo matched the submitted information to a person. Possible values are `high`, `medium`, `low`, and `none`, with the same meanings as for [people enrichment](ref:people-enrichment). For standard requests, unmatched entries are returned as `null`. When you use waterfall enrichment, an unmatched result can return `match_confidence: none`. If you set `run_waterfall_email` or `run_waterfall_phone` to `true`, the response includes a `waterfall` object instead. Because waterfall enrichment continues asynchronously, `unique_enriched_records`, `missing_records`, and `credits_consumed` aren't included in the initial response. `total_requested_enrichments` is included in both response types. When `run_waterfall_email` is `true`, the entries in `matches` also don't include `email` or `email_status`. Apollo sends the enriched email data later to your webhook. Keep the following response fields in mind: * `unique_enriched_records` counts the number of distinct people whose enrichment consumed credits. It doesn't represent the number of people returned in `matches`, so it can be lower than the number of matches or `0` when `matches` contains results. * `credits_consumed` can contain a decimal value depending on your plan's credit pricing. * `request_id` is a signed 64-bit integer and may be negative. Pass the value unchanged when you use the [poll webhook result](ref:poll-webhook-result) endpoint. * `status` returns `success` for a successful `200` response, even when Apollo doesn't match every requested person. Use `missing_records` and `matches` to review the enrichment results. ### Webhook details * When using native phone enrichment, the webhook response follows: [Native webhook response details](doc:retrieve-mobile-phone-numbers-for-contacts#webhook-response). * When using waterfall enrichment, the webhook response follows: [Waterfall webhook response details](doc:enrich-phone-and-email-using-data-waterfall#asynchronous-webhook-response-1). * You can poll webhook results with the [poll webhook result](ref:poll-webhook-result) endpoint by passing the request_id from the bulk people enrichment response. ### Webhook requirements * **HTTPS Required:** Your endpoint must be publicly accessible over HTTPS. * **Rate Limiting:** Ensure your webhook endpoint can handle the volume of webhook traffic sent by Apollo. * **Idempotency:** Apollo may retry webhook calls. Your endpoint should be idempotent to handle duplicate payloads safely.

    POST /people/bulk_match

Search

  • Read

    Organization job postings

    This endpoint consumes 1 Apollo credit per page, with up to 10,000 results per page. Learn more about [API pricing and credits](https://docs.apollo.io/docs/api-pricing). Organizations (https://knowledge.apollo.io/hc/en-us/articles/4412658766477-Search-for-Companies) are companies you haven't yet saved as accounts on Apollo. Use the organization job postings endpoint to retrieve the current job postings for companies. This can help you identify companies that are growing headcount in areas that are strategically important for you. To protect Apollo's performance for all users, this endpoint has a display limit of 10,000 records.

    GET /organizations/{organization_id}/job_postings

  • Read

    Get complete organization info

    Organizations (https://knowledge.apollo.io/hc/en-us/articles/4412658766477-Search-for-Companies) are companies you haven't yet saved as accounts on Apollo. Use the get complete organization info endpoint to retrieve complete details about an organization in Apollo.

    GET /organizations/{id}

  • Read

    Get complete person info

    Use the get complete person info endpoint to retrieve complete details about a person in the Apollo database, including employment history, location, and the full details of the person's current organization. ### Reading the `email` field This endpoint doesn't reveal verified emails for people you haven't saved as contacts. Instead of the address — and instead of `null` — `email` contains the fixed placeholder `email_not_unlocked@domain.com`, and every unrevealed person returns that same value. Because the placeholder is a non-empty string, it passes checks that assume an email is either usable or absent: * **Truthiness and null checks don't catch it.** `if (person.email)` succeeds, so code may treat an unrevealed person as though you have their address. * **`email` breaks as a dedupe or upsert key.** Identical placeholders collapse unrelated people into one record. `email_status` does **not** distinguish it either: it describes the address Apollo holds internally, so it reads `verified` even when `email` is the placeholder. Use it to judge deliverability once you have a real address, not to decide whether you have one. The field only ever returns one of three values — `verified`, `extrapolated`, or `unavailable`. **Recommended handling:** compare `email` against the literal placeholder string and treat a match as "no email available yet". The response also omits `contact_id` and `revealed_for_current_team` for people who aren't your contacts, which is a useful second signal. To get the real address, call [people enrichment](https://docs.apollo.io/reference/people-enrichment) or [bulk people enrichment](https://docs.apollo.io/reference/bulk-people-enrichment), which never substitute the placeholder. | Person's situation | `email` | `email_status` | | --- | --- | --- | | Verified email, not your contact | `email_not_unlocked@domain.com` | `verified` | | Verified email, already your contact | The contact's real address | `verified` | | No verified email, but Apollo holds an extrapolated address | The extrapolated address | `extrapolated` | | No email available | `null` | `unavailable` |

    GET /people/{id}

Accounts

  • Read

    Search for accounts

    An account (https://knowledge.apollo.io/hc/en-us/articles/5995865049229-View-and-Edit-Accounts) is a company saved in Apollo. Use the search for accounts endpoint to search for an account that has been saved to Apollo. This endpoint only returns accounts in the search results. To search for companies in Apollo, call the organization search endpoint (https://docs.apollo.io/reference/organization-search). To protect Apollo's performance for all users, this endpoint has a display limit of 50,000 records (100 records per page, up to 500 pages). Add more filters to narrow your search results as much as possible.

    POST /accounts/search

  • Read

    List account stages

    Account stages (https://knowledge.apollo.io/hc/en-us/articles/4410623601165-Contact-and-Account-Stages-Overview) help you track progress on sales and marketing pipelines. Use the list accounts stages endpoint to retrieve the IDs for the available account stages in your team's Apollo account. This endpoint doesn't require parameters. Account stage IDs can be used to update individual accounts (https://docs.apollo.io/reference/update-an-account) and update the account stages for multiple accounts (https://docs.apollo.io/reference/bulk-update-accounts) via Apollo API.

    GET /account_stages

  • Read

    View an account

    An account (https://knowledge.apollo.io/hc/en-us/articles/5995865049229-View-and-Edit-Accounts) is a company saved in Apollo. Use the view an account endpoint to retrieve details for an existing account.

    GET /accounts/{id}

  • Write

    Create an account

    An account (https://knowledge.apollo.io/hc/en-us/articles/5995865049229-View-and-Edit-Accounts) is a company saved in Apollo. Use the create an account endpoint to add a new account to your team's Apollo account. Apollo doesn't apply deduplication processes when you create a new account via the API. If your entry has the same name, domain, or other details as an existing account, Apollo creates a new account instead of updating the existing account. To update an existing account, use the update an account endpoint (https://docs.apollo.io/reference/update-an-account) instead.

    POST /accounts

  • Write

    Update an account

    An account (https://knowledge.apollo.io/hc/en-us/articles/5995865049229-View-and-Edit-Accounts) is a company saved in Apollo. Use the update an account endpoint to update existing accounts in your team's Apollo account. To create a new account, use the create an account endpoint (https://docs.apollo.io/reference/create-an-account) instead. To update the account stage for multiple accounts, use the bulk update accounts endpoint (https://docs.apollo.io/reference/bulk-update-accounts).

    PATCH /accounts/{account_id}

  • Write

    Bulk create accounts

    An account (https://knowledge.apollo.io/hc/en-us/articles/5995865049229-View-and-Edit-Accounts) is a company saved in Apollo. Use the bulk create accounts endpoint to create up to one hundred accounts in a single API request. This endpoint supports intelligent deduplication and returns separate arrays for newly created and existing accounts. **Important**: This endpoint creates new accounts but doesn't update existing ones. Existing accounts that match the criteria are returned in the existing_accounts array without modification. To update existing accounts, use the bulk update accounts endpoint (https://docs.apollo.io/reference/bulk-update-accounts).

    POST /accounts/bulk_create

  • Write

    Bulk update accounts

    An account (https://knowledge.apollo.io/hc/en-us/articles/5995865049229-View-and-Edit-Accounts) is a company saved in Apollo. Use the bulk update accounts endpoint to simultaneously update multiple accounts in your team's Apollo account. This endpoint allows you to update common fields across multiple accounts efficiently, such as account stages, owners, names, and custom fields. You can update up to 1,000 accounts per request. Important: Asynchronous processing (async parameter) is only supported when using account_ids to apply the same updates to all accounts. If you use async with account_attributes (individual updates per account), the request fails with a 422 error.

    POST /accounts/bulk_update

  • Write

    Update account owner for multiple accounts

    Account owners (https://knowledge.apollo.io/hc/en-us/articles/5631686093069-Edit-a-Contact-or-Account-Owner) manage saved accounts in Apollo. Use the update account owner for multiple accounts endpoint to assign multiple accounts to a different user in your team's Apollo account. To update more than the account owner, such as domains or phone numbers, use the update an account endpoint (https://docs.apollo.io/reference/update-an-account) instead.

    POST /accounts/update_owners

Contacts

  • Read

    View a contact

    Contacts (https://knowledge.apollo.io/hc/en-us/articles/5995459280525-View-and-Edit-Contacts) are people saved in Apollo. Use the view a contact endpoint to retrieve details for an existing contact in your team's Apollo database.

    GET /contacts/{contact_id}

  • Read

    View associated deals

    Deals (https://knowledge.apollo.io/hc/en-us/articles/4415062467725-Deals-Overview) on Apollo help you track sales opportunities. Use the view associated deals endpoint to retrieve the deals associated with a contact. This endpoint doesn't require a request body. If you include one, Apollo doesn't read its fields. An empty JSON {} is sufficient. Each result returns the same deal details as view deal (https://docs.apollo.io/reference/view-deal) endpoint. If the contact has no associated deals or the contact ID isn't recognized, Apollo returns a 200 response with an empty array rather than a 404 error.

    POST /contacts/{contact_id}/opportunities

  • Read

    Search for contacts

    Contacts (https://knowledge.apollo.io/hc/en-us/articles/5995459280525-View-and-Edit-Contacts) are people saved in Apollo. Use the search for contacts endpoint to search for the contacts that have been added to your team's Apollo account. This endpoint only returns contacts in the search results. To search for people in the Apollo database, call the people API search endpoint (https://docs.apollo.io/reference/people-api-search). To protect Apollo's performance for all users, this endpoint has a display limit of 50,000 records (100 records per page, up to 500 pages). Add more filters to narrow your search results as much as possible.

    POST /contacts/search

  • Read

    List contact stages

    Contact stages (https://knowledge.apollo.io/hc/en-us/articles/4410623601165-Contact-and-Account-Stages-Overview) help you track progress on sales and marketing pipelines. Use the list contact stages endpoint to retrieve the IDs for the available contact stages in your team's Apollo account. Contact stage IDs can be used to update individual contacts (https://docs.apollo.io/reference/update-a-contact) and update the contact stages for multiple contacts (https://docs.apollo.io/reference/update-contact-stage) via Apollo API.

    GET /contact_stages

  • Write

    Create a contact

    Contacts (https://knowledge.apollo.io/hc/en-us/articles/5995459280525-View-and-Edit-Contacts) are people saved in Apollo. Use the create a contact endpoint to add a new contact to your team's Apollo account. By default, Apollo doesn't apply deduplication processes when you create a new contact via API. If your entry has the same name, email address, or other details as an existing contact, Apollo creates a new contact instead of updating the existing contact. To enable deduplication and prevent duplicate contacts, set the run_dedupe parameter to true. To update an existing contact, use the update a contact endpoint (https://docs.apollo.io/reference/update-a-contact) instead. ### What `run_dedupe` actually does Setting `run_dedupe` to `true` does more than suppress a duplicate. On a match, Apollo **updates that existing contact in place** with your request's values and returns it. The response looks like a creation, but the `id` belongs to the pre-existing contact — so treating every `200` as "a new contact was created" doesn't hold once `run_dedupe` is on. **How Apollo picks the match.** It checks these in order and stops at the first hit, so a match isn't necessarily on email: 1. `id`, if you send one. 2. CRM identifiers: `salesforce_lead_id`, `salesforce_contact_id`, `hubspot_vid`, or a previously merged CRM ID. 3. `person_id`. 4. `email` — compared against the contact's primary email **and** any additional emails stored on it. 5. `first_name` plus `last_name` (or a full name) with a matching company, where the company matches on email domain, `organization_id`, or `organization_name`. Because of step 5, a contact can be matched and updated even when the email you send differs from the stored one. **What the update writes.** It's a field-level overwrite of the values you send, not a merge that prefers existing data: * Fields you **send** overwrite the stored values, with no warning and no record of the previous value. * Fields you **omit** are left untouched, so you don't need to resend the whole record. * An **empty value clears the field** rather than being ignored. * The contact's `email` can itself be overwritten when the match came from a CRM ID, `person_id`, or name-plus-company. `email_status` isn't re-verified, so it can keep reading `verified` while describing the previous address. * Protected once set: `person_id`, `salesforce_lead_id`, and `salesforce_contact_id`. LinkedIn-sourced photos won't replace an existing `photo_url`. **Recommended handling.** To add records without changing existing ones, leave `run_dedupe` off (the default) and reconcile duplicates yourself. To upsert, set it to `true` and send the complete set of fields you want the contact to end up with, since omitted fields keep their old values. To edit a known contact, prefer [update a contact](https://docs.apollo.io/reference/update-a-contact) with its `id` — explicit, with no matching involved. [bulk create contacts](https://docs.apollo.io/reference/bulk-create-contacts) differs: matched contacts are returned in `existing_contacts` **without** being modified.

    POST /contacts

  • Write

    Update a contact

    Contacts (https://knowledge.apollo.io/hc/en-us/articles/5995459280525-View-and-Edit-Contacts) are people saved in Apollo. Use the update a contact endpoint to update existing contacts in your team's Apollo account. To create a new contact, use the create a contact endpoint (https://docs.apollo.io/reference/create-a-contact) instead. To update the contact stage for multiple contacts, use the update contact stage for multiple contacts (https://docs.apollo.io/reference/update-contact-stage) endpoint.

    PATCH /contacts/{contact_id}

  • Write

    Update contact stage for multiple contacts

    Contact stages (https://knowledge.apollo.io/hc/en-us/articles/4410623601165-Contact-and-Account-Stages-Overview) help you track progress on sales and marketing pipelines. Use the update contact stage for multiple contacts endpoint to update the contact stage for several contacts in your team's Apollo account. To update more than the contact stage, such as job titles or contact details, use the update a contact endpoint (https://docs.apollo.io/reference/update-a-contact) instead.

    POST /contacts/update_stages

  • Write

    Update contact owner for multiple contacts

    Contact owners (https://knowledge.apollo.io/hc/en-us/articles/5631686093069-Edit-a-Contact-or-Account-Owner) manage specific contacts in Apollo. Use the update contact owner for multiple contacts endpoint to assign multiple contacts to a different user in your team's Apollo account. To update more than the contact's owner, such as job titles or contact details, use the update a contact endpoint (https://docs.apollo.io/reference/update-a-contact) instead.

    POST /contacts/update_owners

  • Write

    Bulk create contacts

    Contacts (https://knowledge.apollo.io/hc/en-us/articles/5995459280525-View-and-Edit-Contacts) are people saved in Apollo. Use the bulk create contacts endpoint to create up to 100 contacts in a single API request. This endpoint supports intelligent deduplication and returns separated arrays for newly created and existing contacts. Important: This endpoint creates new contacts but doesn't update existing ones (except for placeholder contacts from email imports). Existing contacts that match the criteria are returned in the existing_contacts array without modification. To update existing contacts, use the bulk update contacts endpoint (https://docs.apollo.io/reference/bulk-update-contacts).

    POST /contacts/bulk_create

  • Write

    Bulk update contacts

    Contacts (https://knowledge.apollo.io/hc/en-us/articles/5995459280525-View-and-Edit-Contacts) are people saved in Apollo. Use the bulk update contacts endpoint to update multiple contacts in your team's Apollo account simultaneously. Use this endpoint to update contact details, owners, and custom field values. To change stages, use update contact stage for multiple contacts (https://docs.apollo.io/reference/update-contact-stage). You can update up to 1000 contacts per request; requests with more than 1000 contacts are rejected with a 422 error. Requests of 100 or fewer contacts are processed synchronously and return the updated contacts immediately. Requests of 101 to 1000 contacts are processed asynchronously. You can also force asynchronous processing at any batch size by setting the async parameter to true.

    POST /contacts/bulk_update

Sequences

  • Read

    List email schedules

    Sending schedules (https://knowledge.apollo.io/hc/en-us/articles/4409477927309-Configure-a-Sequence-Sending-Schedule) control the days and times that Apollo sends emails for your sequences. You can configure multiple sending schedules for different sequences, for example to match your audience's time zone or when your contacts are most likely to engage. Use the list email schedules endpoint to retrieve every sending schedule that has been created for your team's Apollo account. For each schedule, the response returns its ID, name, time zone, weekly sending windows, and whether it is your team's default schedule. Use a schedule's `id` as the `emailer_schedule_id` when you create a sequence (https://docs.apollo.io/reference/create-sequence) or update a sequence (https://docs.apollo.io/reference/update-sequence) to control when that sequence's emails are sent.

    GET /emailer_schedules

  • Read

    Search for sequences

    Sequences (https://knowledge.apollo.io/hc/en-us/articles/4409237165837-Sequences-Overview) are outreach campaigns that sales teams use to reach out to contacts over a planned period of time. Use the search for sequences endpoint to search for the sequences that have been created for your team's Apollo account.

    POST /emailer_campaigns/search

  • Read

    Check email stats

    Sequences (https://knowledge.apollo.io/hc/en-us/articles/4409237165837-Sequences-Overview) are outreach campaigns that sales teams use to reach out to contacts over a planned period of time. Use the check email stats endpoint to review the complete details for an email sent as part of an Apollo sequence. This includes the contents of the emails, stats related to the email such as opens and clicks, and details about the contact that received the email.

    GET /emailer_messages/{id}/activities

  • Read

    Search for outreach emails

    Sequences (https://knowledge.apollo.io/hc/en-us/articles/4409237165837-Sequences-Overview) are outreach campaigns that sales teams use to reach out to contacts over a planned period of time. Use the search for outreach emails endpoint to find emails that your team has created and sent as part of Apollo sequences. To protect Apollo's performance for all users, this endpoint has a display limit of 50,000 records (100 records per page, up to 500 pages). Add more filters to narrow your search results as much as possible. This limitation does not restrict your access to Apollo's database; you just need to access the data in batches.

    GET /emailer_messages/search

  • Read

    Get contact sequence activity

    Sequences (https://knowledge.apollo.io/hc/en-us/articles/4409237165837-Sequences-Overview) are outreach campaigns that sales teams use to reach out to contacts over a planned period of time. Use the get contact sequence activity endpoint to retrieve one contact's sequence timeline: when they were added to a sequence, when their enrollment was paused, resumed, failed, finished, or removed, and when they replied. This is the same enrollment activity that the contact's timeline shows in Apollo. You must provide a `contact_id`, and that contact must belong to your team. This endpoint returns activity for a single contact — it doesn't return activity for every contact in a sequence. To narrow the timeline to one sequence, also provide a `sequence_id`. Events are returned newest-first, and each response contains at most 50 events. There is no `page` parameter: the endpoint always returns the most recent events, so use `per_page` to request fewer than 50. To find contact IDs, call the search for contacts endpoint (https://docs.apollo.io/reference/search-for-contacts) and identify the `id` value for the contact. To find sequence IDs, call the search for sequences endpoint (https://docs.apollo.io/reference/search-for-sequences) and identify the `id` value for the sequence.

    POST /emailer_campaigns/activity_feed

  • Write

    Add contacts to a sequence

    Sequences (https://knowledge.apollo.io/hc/en-us/articles/4409237165837-Sequences-Overview) are outreach campaigns that sales teams use to reach out to contacts over a planned period of time. Use the add contacts to a sequence endpoint to add contacts to the existing sequences in your team's Apollo account. A contact is a person that your team has explicitly added to your database. Only contacts can be added to sequences. To enrich a person's data, call the people enrichment endpoint (https://docs.apollo.io/reference/people-enrichment). Then, to add the person as a contact in your database, call the create a contact endpoint (https://docs.apollo.io/reference/create-a-contact).

    POST /emailer_campaigns/{sequence_id}/add_contact_ids

  • Write

    Update contact status in a sequence

    Sequences (https://knowledge.apollo.io/hc/en-us/articles/4409237165837-Sequences-Overview) are outreach campaigns that sales teams use to reach out to contacts over a planned period of time. Use the update contact status in a sequence endpoint to either mark contacts as having `finished` a sequence, or to remove them from a sequence entirely.

    POST /emailer_campaigns/remove_or_stop_contact_ids

  • Write

    Create a sequence

    Sequences (https://knowledge.apollo.io/hc/en-us/articles/4409237165837-Sequences-Overview) are outreach campaigns that sales teams use to reach out to contacts over a planned period of time. Use the create a sequence endpoint to create a new sequence in your team's Apollo account, including its steps and email templates. To create a sequence with steps, add the `emailer_steps` array to the request body. Each email step (`auto_email`, `manual_email`) can include one or more `emailer_touches` (email variants); adding more than one touch to a step creates an A/B test, which requires a plan with A/B testing access. To activate the sequence immediately after creation, set `active` to `true`. Email touches only send if their `status` is `approved`, and a touch can only be approved if its template has a non-empty body. ### Who owns a sequence created via API The new sequence is owned by the user your request acts as, returned as `object_owner_id` (and its alias, `user_id`). With an API key that user isn't the teammate who created the key, so expect `object_owner_id` to differ from that teammate's profile — see [Authentication](https://docs.apollo.io/reference/authentication) for how the acting user is resolved and how to confirm it. This endpoint ignores `user_id` in the request body, so you can't choose the owner at creation time. To reassign ownership afterward, call [update a sequence](https://docs.apollo.io/reference/update-sequence) with a `user_id`.

    POST /sequences

  • Write

    Activate a sequence

    Sequences (https://knowledge.apollo.io/hc/en-us/articles/4409237165837-Sequences-Overview) are outreach campaigns that sales teams use to reach out to contacts over a planned period of time. Use the activate a sequence endpoint to start an inactive sequence. Once activated, the sequence begins sending emails to its contacts on the configured schedule. The sequence must have at least one step configured before it can be activated.

    POST /emailer_campaigns/{sequence_id}/approve

  • Write

    Deactivate a sequence

    Sequences (https://knowledge.apollo.io/hc/en-us/articles/4409237165837-Sequences-Overview) are outreach campaigns that sales teams use to reach out to contacts over a planned period of time. Use the deactivate a sequence endpoint to stop an active sequence. Once deactivated, the sequence pauses all contacts and stops sending emails.

    POST /emailer_campaigns/{sequence_id}/abort

  • Destructive

    Update a sequence

    Sequences (https://knowledge.apollo.io/hc/en-us/articles/4409237165837-Sequences-Overview) are outreach campaigns that sales teams use to reach out to contacts over a planned period of time. Use the update a sequence endpoint to update an existing sequence (emailer campaign) in your team's Apollo account. You can update sequence-level settings, such as the name, active state, schedule, and sending limits, as well as the sequence's steps and the email touches within each step. To turn a sequence on or off, set the `active` field. Passing `emailer_steps` will create, update, reorder, or remove steps and their touches based on the IDs you provide. To create a new sequence instead, use the create a sequence endpoint (https://docs.apollo.io/reference/create-sequence). ### Reassigning sequence ownership Unlike [create a sequence](https://docs.apollo.io/reference/create-sequence), this endpoint accepts `user_id` and uses it to change who owns the sequence. Pass the intended owner's Apollo user ID, and the response reflects it in both `user_id` and its alias `object_owner_id`. Use [get a list of users](https://docs.apollo.io/reference/get-a-list-of-users) to look up IDs. This is how you correct ownership on sequences created with an API key, which aren't owned by the teammate who created the key. See [Authentication](https://docs.apollo.io/reference/authentication) for how the acting user is resolved.

    PUT /sequences/{id}

  • Destructive

    Archive a sequence

    Sequences (https://knowledge.apollo.io/hc/en-us/articles/4409237165837-Sequences-Overview) are outreach campaigns that sales teams use to reach out to contacts over a planned period of time. Use the archive a sequence endpoint to archive a sequence. Archiving a sequence marks it as inactive and finishes all contacts currently in the sequence. You must be the owner of the sequence or have full access sharing permissions to archive it.

    POST /emailer_campaigns/{sequence_id}/archive

Deals

  • Read

    List all deals

    Deals (https://knowledge.apollo.io/hc/en-us/articles/4415062467725-Deals-Overview) on Apollo help you track sales opportunities. Use the list all deals endpoint to retrieve every deal that has been created for your team's Apollo account.

    GET /opportunities/search

  • Read

    View deal

    Deals (https://knowledge.apollo.io/hc/en-us/articles/4415062467725-Deals-Overview) on Apollo help you track sales opportunities. Use the view deal endpoint to retrieve complete details about a deal within your team's Apollo account. Deal information can include the ID of the deal owner, the monetary value of the deal, the deal stage, and general details about the account.

    GET /opportunities/{opportunity_id}

  • Read

    List deal stages

    Deals (https://knowledge.apollo.io/hc/en-us/articles/4415062467725-Deals-Overview) on Apollo help you track sales opportunities. Use the list deal stages endpoint to retrieve information about every deal stage that's available in your team's Apollo account. The `id` value for each deal stage can be used to set the stage when creating a deal (https://docs.apollo.io/reference/create-deal) or updating a deal (https://docs.apollo.io/reference/update-deal) via the Apollo API.

    GET /opportunity_stages

  • Write

    Create deal

    Deals (https://knowledge.apollo.io/hc/en-us/articles/4415062467725-Deals-Overview) on Apollo help you track sales opportunities. Use the create deal endpoint to create new deals for an Apollo account. To update existing deals in your Apollo account, use the update deal endpoint (https://docs.apollo.io/reference/update-deal) instead.

    POST /opportunities

  • Write

    Update deal

    Deals (https://knowledge.apollo.io/hc/en-us/articles/4415062467725-Deals-Overview) on Apollo help you track sales opportunities. Use the update deal endpoint to update the details of existing deals within your team's Apollo account. To create new deals in your Apollo account, use the create deal endpoint (https://docs.apollo.io/reference/create-deal) instead.

    PATCH /opportunities/{opportunity_id}

Tasks

  • Read

    Get a task

    Tasks (https://knowledge.apollo.io/hc/en-us/articles/28705458602125-Tasks-Overview) let you track, prioritize, and help you complete actions required for your outbound sales motion. Use the get a task endpoint to retrieve the full details for a single task that belongs to your team's Apollo account. The response includes the task's associated account (https://docs.apollo.io/reference/view-an-account) and contact (https://docs.apollo.io/reference/view-a-contact) when the task has one attached. Depending on the task's `type` and how it was created, the response can also include additional fields, such as `phone_call` for call tasks, `emailer_message` for email tasks, or a LinkedIn message template for LinkedIn-step tasks. To find task IDs, use the search for tasks endpoint (https://docs.apollo.io/reference/search-tasks) and identify the `id` value for the task you want to view. To create a task, use the create a task endpoint (https://docs.apollo.io/reference/create-a-task) instead.

    GET /tasks/{id}

  • Read

    Search for tasks

    Tasks (https://knowledge.apollo.io/hc/en-us/articles/28705458602125-Tasks-Overview) let you track, prioritize, and help you complete actions required for your outbound sales motion. Use the search for tasks endpoint to find tasks that your team has created in Apollo. To protect Apollo's performance for all users, this endpoint has a display limit of 50,000 records (100 records per page, up to 500 pages). Add more filters to narrow your search results as much as possible.

    POST /tasks/search

  • Write

    Create a task

    Tasks (https://knowledge.apollo.io/hc/en-us/articles/28705458602125-Tasks-Overview) let you track, prioritize, and help you complete actions required for your outbound sales motion. Use the create a task endpoint to create a single task in Apollo for you and your team. Tasks help track the upcoming actions you need to take, such as emailing or calling a contact. This endpoint returns the created task object. Apollo does not apply deduplication processes when you create a new task via the API. If your entry has the same task owner, contact, and other details as an existing task, Apollo will create a new task instead of updating the existing task.

    POST /tasks

  • Write

    Bulk create tasks

    **Authentication note:** Shares scope with `tasks/create`. Tasks (https://knowledge.apollo.io/hc/en-us/articles/28705458602125-Tasks-Overview) let you track, prioritize, and help you complete actions required for your outbound sales motion. Use the bulk create tasks endpoint to create multiple tasks in a single API request. A separate task will be created for each contact provided. This endpoint returns a `success` boolean and a `tasks` array containing the created tasks. Apollo doesn't apply deduplication processes when you create a new task via the API. If your entry has the same task owner, contact, and other details as an existing task, Apollo creates a new task instead of updating the existing task. For creating a single task, use the create a task endpoint (https://docs.apollo.io/reference/create-a-task) instead.

    POST /tasks/bulk_create

  • Write

    Update a task

    Tasks (https://knowledge.apollo.io/hc/en-us/articles/28705458602125-Tasks-Overview) let you track, prioritize, and help you complete actions required for your outbound sales motion. Use the update a task endpoint to change the details of an existing task that belongs to your team's Apollo account. To find task IDs, use the search for tasks endpoint (https://docs.apollo.io/reference/search-tasks) and identify the `id` value for the task you want to update. The fields you can update depend on the task's current `status`. For a task with a `scheduled` status, you can update any of the parameters listed below. For a task that's already `completed` or `skipped`, you can only update `note`, `priority`, `priority_cd`, and `contact_id`. To mark a task as done, use the complete a task (https://docs.apollo.io/reference/complete-a-task) or skip a task (https://docs.apollo.io/reference/skip-a-task) endpoints instead of setting `status` here. > ⚠️ Omitting `priority` or `creator_id` resets them > > If the task you're updating has a `scheduled` status, and your request doesn't include a `priority` or `creator_id` parameter, Apollo resets `priority` to `medium` and `creator_id` to the user associated with your API key — even if you didn't intend to change those fields. To avoid this, always include the task's current `priority` and `creator_id` in every update request, even when you're only changing an unrelated field like `note`.

    PATCH /tasks/{id}

  • Write

    Complete a task

    Tasks (https://knowledge.apollo.io/hc/en-us/articles/28705458602125-Tasks-Overview) let you track, prioritize, and help you complete actions required for your outbound sales motion. Use the complete a task endpoint to mark an existing task as `completed`. To find task IDs, use the search for tasks endpoint (https://docs.apollo.io/reference/search-tasks) and identify the `id` value for the task you want to complete. If the task no longer exists (for example, because the sequence it belonged to was paused and the task was removed), Apollo still returns a `200` response, with `deleted: true` on the task, instead of an error. To skip a task instead of completing it, use the skip a task endpoint (https://docs.apollo.io/reference/skip-a-task). Calling this endpoint on a task that's already `completed` or `skipped` returns a `422` response.

    POST /tasks/{id}/complete

  • Write

    Skip a task

    Tasks (https://knowledge.apollo.io/hc/en-us/articles/28705458602125-Tasks-Overview) let you track, prioritize, and help you complete actions required for your outbound sales motion. Use the skip a task endpoint to mark an existing task as `skipped` without completing it. To find task IDs, use the search for tasks endpoint (https://docs.apollo.io/reference/search-tasks) and identify the `id` value for the task you want to skip. If the task no longer exists (for example, because the sequence it belonged to was paused and the task was removed), Apollo still returns a `200` response, with `deleted: true` on the task, instead of an error. Calling this endpoint on a task that's already `completed` or `skipped` returns a `422` response. To mark a task as done instead of skipping it, use the complete a task endpoint (https://docs.apollo.io/reference/complete-a-task).

    POST /tasks/{id}/skip

Emailer Messages

  • Read

    Get email content

    Use the get email content endpoint to retrieve the subject line, body, and recipients of emails that your team has already sent. Provide up to 10 email message IDs in a single request, and choose whether each body is returned as plain text or as the original HTML. This endpoint only returns emails that your team sent and that Apollo has finished sending. Drafted, scheduled, and failed emails are never returned, and neither are replies or other inbound emails. Any ID that doesn't match one of your team's sent emails is left out of the response instead of causing an error. This applies to unknown IDs, malformed IDs, IDs that belong to another team, and IDs for emails that aren't sent outreach emails. Because of this, always match the results back to your request using the `id` field, and treat a missing `id` as "no sent email available" rather than a failure. To find email message IDs, call the search for outreach emails endpoint (https://docs.apollo.io/reference/search-for-outreach-emails) and identify the `id` value for each email.

    POST /emailer_messages/get_content

  • Read

    Check email send status

    Use the check email send status endpoint to check the current delivery status of an email message. This is typically used after calling the send email now endpoint (https://docs.apollo.io/reference/send-email-now), since emails are sent asynchronously and a successful send response only means the email was queued. You must provide the `id` of the email message. The message must belong to your team, otherwise a `404` is returned. The response always includes the message `id`, its current `status`, and a human-readable `message`. The remaining fields depend on the status:If the email was delivered (`completed`), a `completed_at` timestamp is included.If the email failed (`failed`), a `not_sent_reason`, `failure_reason`, and `failed_at` timestamp may be included.If the email is still being processed (like `drafted` or `scheduled`), a `retry_after_seconds` value is included to indicate how long to wait before checking again.

    POST /emailer_messages/email_send_status

  • Write

    Create an email draft

    Use the create an email draft endpoint to create a single, unsent email message (an email draft) for a contact. The draft is created with a `drafted` status — this endpoint doesn't send the email. To send the draft after creating it, call the send email now endpoint (https://docs.apollo.io/reference/send-email-now) with the `id` returned in the response. You must provide a `contact_id` so Apollo knows who the email is for. Alternatively, to draft a reply within an existing email thread, provide `in_response_to_emailer_message_id` instead and Apollo infers the contact and recipients from the parent message. The email is drafted from the user that owns the API key. That user must have permission to email the contact (like by owning the contact or its account), and the contact must not be blocked by any do not contact settings. This endpoint returns the created `emailer_message` object. If the draft is linked to an outreach task, a `task` object is also returned.

    POST /emailer_messages

  • Write

    Send email now

    Use the send email now endpoint to immediately send an existing email message.This works for emails that are currently in a `drafted`, `scheduled`, or `failed` state. Apollo schedules the email to be sent right away and processes it asynchronously. To first create an email draft, use the create an email draft (https://docs.apollo.io/reference/create-an-email-draft) endpoint and pass the returned `id` to this endpoint. The email is sent from the user that owns the API key. That user must have a linked email account on the message, must have permission to send from that email account, and must have permission to email the contact. The contact must also not be blocked by any do not contact settings, and the user must not have exceeded their daily email sending limit. Because sending is processed asynchronously, a successful `200` response means the email has been queued for sending — not that it's been delivered. To check whether the email was delivered, poll the check email send status (https://docs.apollo.io/reference/check-email-send-status) endpoint using the message `id`. This endpoint returns the `emailer_message` object. If the message is linked to an outreach task, a `task` object is also returned.

    POST /emailer_messages/{id}/send_now

Miscellaneous

  • Read

    Get a list of users

    Users (https://knowledge.apollo.io/hc/en-us/articles/4409130537101-Add-Manage-and-Deactivate-Users) are the people who use your Apollo workspace. Use the get a list of users endpoint to retrieve the IDs for all of the users in your Apollo account. These IDs can be used for several other endpoints, including the create a deal (https://docs.apollo.io/reference/create-deal), create an account (https://docs.apollo.io/reference/create-an-account), and create a task (https://docs.apollo.io/reference/create-a-task) endpoints.

    GET /users/search

  • Read

    Get a list of email accounts

    You can link mailboxes to Apollo (https://knowledge.apollo.io/hc/en-us/articles/4409127806093-Link-Your-Mailbox-to-Apollo), and use them for prospect outreach. Use the get a list of email accounts endpoint to retrieve information about the linked email inboxes that your teammates use in your Apollo account. In particular, this endpoint returns IDs for each of your team's linked email accounts, which can be used with the add contacts to a sequence endpoint (https://docs.apollo.io/reference/add-contacts-to-sequence). This endpoint doesn't require any parameters.

    GET /email_accounts

  • Read

    Get a list of all lists

    Use the get a list of all lists endpoint to retrieve information about every list (https://knowledge.apollo.io/hc/en-us/articles/4409728608525-Create-and-Use-a-List) that has been created in your Apollo account. This endpoint can be used to check the available lists before you use the create a contact endpoint (https://docs.apollo.io/reference/create-a-contact). This endpoint doesn't require any parameters.

    GET /labels

  • Read

    Poll webhook result

    Use the poll webhook result endpoint to retrieve webhook results from Apollo. This endpoint enables you to poll for the webhook payload if you didn't receive the original webhook callback. To use this endpoint, you need the request_id from the people enrichment (https://docs.apollo.io/reference/people-enrichment) or bulk people enrichment (https://docs.apollo.io/reference/bulk-people-enrichment) endpoint. Pass this value as request_id in this endpoint. This endpoint returns webhook results for your team from up to thirty days after the webhook was triggered. While an enrichment is still processing, this endpoint returns a 404 with error_code: result_pending and a retry_after_seconds value—wait that many seconds and poll again. Once the result is ready, it returns a 200. Three responses are terminal, so stop polling if you receive any of them: request_id_unknown (404—the request_id is not recognized, usually because it was mistyped or never issued), request_id_expired (410—the result has aged out past the 30-day window, so start a fresh enrichment request), and invalid_request_id (400—the request_id is not a valid signed 64-bit integer). For requests made with poll_only set to true, webhook_status is skipped, because Apollo doesn't send a webhook.

    GET /webhook_result/{request_id}

  • Read

    View credit usage stats

    Use the view credit usage stats endpoint to monitor your team's credit balance across every credit type in the current billing cycle. For each credit type, the response returns the `limit` (your team's allowance for the cycle), `consumed` (credits used so far), and `left_over` (credits remaining). The `current_credit_cycle` object reports the start and end dates of the billing cycle these stats cover. Balances reflect your team's running credit usage and update within seconds of a credit-consuming request. To retrieve credit usage for a single user instead of the whole team, use [get current user profile](https://docs.apollo.io/reference/get-current-user-profile) with the `include_credit_usage` query parameter set to `true`. ### Credit types The `credit_usage_stats` object is keyed by credit type. Each key funds a different Apollo action: | Key | What it funds | | --- | --- | | `lead_credit` | Email address reveals and email enrichment. | | `direct_dial_credit` | Mobile and direct dial phone number reveals. | | `export_credit` | CSV exports of contacts and accounts. | | `conversation_credit` | Conversation intelligence and call recording. | | `ai_credit` | AI-generated email writing. | | `power_up_credit` | AI power-up field enrichment on contact and account records. | | `inbound_website_visitor_credit` | Inbound website visitor identification. | | `contact_website_visitor_credit` | Contact-level website visit tracking. | | `web_search_record_credit` | Web search enrichment records. | | `dialer` | Dialer talk time. Reported in **minutes**, not credits. | A credit type your Apollo plan (https://app.apollo.io/#/settings/plans/upgrade) doesn't include returns a `limit` of `0`. If your team is on a unified credit plan, `lead_credit` is a shared pool: the `left_over` value already accounts for mobile reveals, exports, dialer minutes, and power-up enrichment, so don't add the individual balances together to estimate what's left.

    POST /usage_stats/credit_usage_stats

  • Read

    View API usage stats and rate limits

    Use the view API usage stats endpoint to view your team's usage of Apollo API and your rate limit for API endpoints. Each endpoint has a rate limit per minute, hour, and day. Your Apollo plan (https://docs.apollo.io/docs/api-pricing) does impact the rate limits for API endpoints. By default, the response covers a fixed list of endpoints, not every endpoint you can call. To check other endpoints, use the `endpoints[]` parameter. ### Check specific endpoints Pass each endpoint in the `endpoints[]` parameter as the path shown in the **API key access** row of its page, without a leading slash. For example, the path for view an account (https://docs.apollo.io/reference/view-an-account) is `api/v1/accounts/show`. You can also send the paths as a JSON array in the request body, such as `{"endpoints": ["api/v1/accounts/show"]}`. The response then includes only the endpoints you request. Each endpoint's key in the response is a string in the form `["api/v1/accounts", "show"]`. You can request up to 74 endpoints at a time. Each one must be an endpoint you can add to an API key (https://docs.apollo.io/docs/create-api-key). Otherwise, Apollo returns a `422` response with one of these `error_details.code` values: | Code | Cause | | --- | --- | | `USAGE.VALIDATION.UNKNOWN_ENDPOINT` | A path isn't an endpoint you can add to an API key, or it starts with `/`. `error_details.context.endpoints.value` lists the rejected paths. | | `USAGE.VALIDATION.TOO_MANY_ENDPOINTS` | The request includes more than 74 endpoints. |

    POST /usage_stats/api_usage_stats

  • Read

    Get a list of notes

    Notes (https://knowledge.apollo.io/hc/en-us/articles/28746467476365-Notes-Overview) on Apollo let you keep track of info directly on prospect profiles. The get a list of notes endpoint retrieves notes associated with a specific contact, account, opportunity, calendar event, or conversation in your Apollo account. You must provide at least one relation parameter (account_id, contact_id, contact_ids, opportunity_id, calendar_event_id, conversation_id, or conversation_ids). Use this endpoint to fetch notes with sorting and pagination support.

    GET /notes

  • Write

    Create a list

    A list (https://knowledge.apollo.io/hc/en-us/articles/4409728608525-Create-and-Use-a-List) is a saved group of contacts or accounts in Apollo that you can organize, action, and track together. Use the create a list endpoint to create a new, empty contact or account list in your team's Apollo account. After you create a list, add records to it with the add records to a list endpoint (https://docs.apollo.io/reference/add-records-to-a-list). List names must be unique for each modality within your team. If you try to create a list with a name that already exists for the same modality, Apollo returns a `422` response.

    POST /labels

  • Write

    Update a list

    A list (https://knowledge.apollo.io/hc/en-us/articles/4409728608525-Create-and-Use-a-List) is a saved group of contacts or accounts in Apollo that you can organize, action, and track together. Use the update a list endpoint to rename an existing list or to toggle its Book of Business status. You can't change a list's modality after it's created. To find list IDs, call the get a list of all lists endpoint (https://docs.apollo.io/reference/get-a-list-of-all-lists) and identify the `id` value for the list you want to update.

    PATCH /labels/{id}

  • Write

    Add records to a list

    A list (https://knowledge.apollo.io/hc/en-us/articles/4409728608525-Create-and-Use-a-List) is a saved group of contacts or accounts in Apollo that you can organize, action, and track together. Use the add records to a list endpoint to add existing contacts or accounts to one or more lists, referencing the lists by name. If a list name you provide doesn't exist yet for the given modality, Apollo creates it automatically. Provide the record IDs in `entity_ids` and the target list names in `label_names`. To find record IDs, use the search for contacts (https://docs.apollo.io/reference/search-for-contacts) or search for accounts (https://docs.apollo.io/reference/search-for-accounts) endpoints. If you provide no valid `entity_ids` or no `label_names`, the endpoint makes no changes and returns a `200` response with a confirmation message.

    POST /labels/add_entity_ids_to_label_names

  • Destructive

    Remove records from a list

    A list (https://knowledge.apollo.io/hc/en-us/articles/4409728608525-Create-and-Use-a-List) is a saved group of contacts or accounts in Apollo that you can organize, action, and track together. Use the remove records from a list endpoint to remove contacts or accounts from one or more lists, referencing the lists by name. Removing records from a list doesn't delete the records themselves, it only removes them from the specified lists. Provide the record IDs in `entity_ids` and the list names in `label_names`. To find record IDs, use the search for contacts (https://docs.apollo.io/reference/search-for-contacts) or search for accounts (https://docs.apollo.io/reference/search-for-accounts) endpoints. If you provide no valid `entity_ids` or no `label_names`, the endpoint makes no changes and returns a `200` response with a confirmation message.

    POST /labels/remove_entity_ids_from_label_names

Users

  • Read

    Get current user profile

    **Authentication note:** Default scope — granted automatically on every OAuth token. Users (https://knowledge.apollo.io/hc/en-us/articles/4409130537101-Add-Manage-and-Deactivate-Users) are the people who use your Apollo workspace. Use the get current user profile endpoint to retrieve the authenticated profile of the person who owns the API key being used. By default, the endpoint returns the user's identity fields. Set the `include_credit_usage` query parameter to `true` to also return the user's and team's credit usage and remaining credit balances. If you call this endpoint without valid access credentials, you receive a `401` response.

    GET /users/api_profile

Fields

  • Read

    Get a list of fields

    Use the get a list of fields endpoint to retrieve information about all of the fields that exist in your Apollo account.

    GET /fields

  • Read

    Get a list of all custom fields (deprecated)

    This endpoint is deprecated. To achieve the same result, use the fields endpoint (https://docs.apollo.io/reference/get-a-list-of-fields) (use `source: custom` to get custom fields only). Use the get a list of custom fields endpoint to retrieve information about all of the custom fields that have been created in your Apollo account. This endpoint doesn't require any parameters.

    GET /typed_custom_fields

  • Write

    Create a custom field

    The create a custom field endpoint lets you add custom fields to your Apollo account, helping your team capture unique details with custom contact (https://knowledge.apollo.io/hc/en-us/articles/4412498825869-Create-Custom-Contact-Fields), custom account (https://knowledge.apollo.io/hc/en-us/articles/4412498754445-Create-Custom-Account-Fields), or custom deal fields (https://knowledge.apollo.io/hc/en-us/articles/4415062486669-Create-a-Deal). Use these fields to enhance your sequences and deliver more personalized, relevant outreach.

    POST /fields

  • Write

    Update a custom field

    Use the update a custom field endpoint to change fields that already exist in your Apollo Workspace, such as renaming a field, changing the maximum length of a text field, or updating the values available in a picklist. Pass the field under the `fields` array, where each object identifies the field by its unique `id`. To find field IDs, call the get a list of fields (https://docs.apollo.io/reference/get-a-list-of-fields) endpoint with `source: custom`. Update 1 field per request. Only custom fields can be updated. System fields, and the child fields of a JSON field, cannot be updated. Apollo only changes the parameters you include in your request, so you can omit any parameter that you want to leave as-is. Updates overwrite the field's current configuration. The values you send replace the field's existing configuration for every record of that modality, and the change cannot be cleanly undone. Removing or renaming picklist options in particular can drop or rewrite data already stored on your records. Picklist fields: every update to a `picklist` or `multipicklist` field must include the complete set of options you want to keep in `meta.picklist_values`, even when you are only renaming the field.

    PATCH /fields

Calls

  • Read

    Search for calls

    Use the search for calls endpoint to find calls that your team has made or received using the dialer (https://knowledge.apollo.io/hc/en-us/articles/4409140527757-Dialer-Overview) on Apollo.

    GET /phone_calls/search

  • Write

    Create call records

    Use the create call records endpoint to log calls in Apollo that were made using outside systems such as Orum or Nooks. This endpoint can only be used create call records, not to dial prospects.

    POST /phone_calls

  • Destructive

    Update call records

    Use the update call records endpoint to update your team's call records in Apollo.

    PUT /phone_calls/{id}

Analytics

  • Read

    Query analytics report

    Use the query analytics report endpoint to programmatically query Apollo analytics (https://knowledge.apollo.io/hc/en-us/articles/33574373762317-Analytics-Overview) and retrieve aggregated sales activity data for your team. This endpoint accepts a flexible payload specifying which metrics to measure, how to group and filter results, and which date range to apply — returning the same data that powers Apollo's built-in Analytics dashboards. Three query modes are supported: flat totals (no group_by), grouped by one dimension such as user or sequence, and pivot cross-tab (one group_by dimension as rows + one pivot_group_by dimension as columns). Each array supports a maximum of one entry. Authentication: Requires an Apollo API key with access to the api/v1/reports/sync_report API. When creating or editing an API key in Apollo Settings, open the APIs tab and select api/v1/reports/sync_report from the list. Check out Create an API Key (https://docs.apollo.io/docs/create-api-key) for detailed instructions. Tip: The easiest way to discover valid metric and group_by combinations is to build a report interactively at Apollo Analytics → Start from scratch (https://app.apollo.io/#/analytics/reports/new), then replicate that configuration in your API request.

    POST /reports/sync_report

Conversations

  • Read

    Search conversations

    Conversations (https://knowledge.apollo.io/hc/en-us/articles/45998035787533-Use-Conversations) are prospect video meetings stored in Apollo. Use the search conversations endpoint to find a list of conversations. Several filters are available to help narrow your search, including by type, account, contact, date range, and more. Each result includes a summary of the conversation. This endpoint doesn't include transcripts or recording URLs. Use the conversation ID retrieved from your search to request full details using get conversations info (https://docs.apollo.io/docs/get-conversations-info).

    POST /conversations/search

  • Read

    Get conversations info

    This endpoint consumes 1 Apollo credit per conversation if the conversation has AI insights. Conversations without AI insights consume 0 credits. Learn more about [API pricing and credits](https://docs.apollo.io/docs/api-pricing). Conversations (https://knowledge.apollo.io/hc/en-us/articles/45998035787533-Use-Conversations) are prospect video meetings stored in Apollo. Use the get conversation info endpoint to retrieve the full details of a single conversation by its ID. To get a conversation's ID, refer to search conversations (https://docs.apollo.io/docs/search-conversations).

    GET /conversations/{id}

  • Read

    Export conversations

    This endpoint consumes 1 Apollo credit per conversation if the conversation has AI insights. Conversations without AI insights consume 0 credits. Learn more about [API pricing and credits](https://docs.apollo.io/docs/api-pricing). Conversations (https://knowledge.apollo.io/hc/en-us/articles/45998035787533-Use-Conversations) are prospect video meetings stored in Apollo. Use the export conversations endpoint to export conversations within a time range. Exports are processed asynchronously and delivered as a gzipped JSON file. A notification email is sent to the specified team member when the export is ready. To get the download URL once the export is ready, refer to get export (https://docs.apollo.io/docs/get-conversations-export).

    POST /conversations/export

  • Read

    Get conversations export

    Conversations (https://knowledge.apollo.io/hc/en-us/articles/45998035787533-Use-Conversations) are prospect video meetings stored in Apollo. Use the get conversations export endpoint to retrieve a download URL for your exported conversations. This endpoint is used as a follow-up to the export conversations (https://docs.apollo.io/docs/export-conversations) endpoint.

    GET /conversations/export/{id}

Get started

  1. Open Space settings → Connections and search for Apollo.
  2. Connect your account and add the connection to the Space.
  3. Ask for what you need in any thread in that Space.

See How connections work for access and permissions, or browse all integrations.