Workspace CRM accounts — create, update, search, stages and ownership. 8 operation(s) from the published Apollo OpenAPI.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/apollo-io-accounts-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Apollo.io Accounts API
version: '1.0'
summary: Programmatic access to Apollo's sales intelligence and engagement platform — data enrichment, prospect and company search, and go-to-market workflow management.
description: 'The Apollo API provides programmatic access to [Apollo](https://www.apollo.io/), the all-in-one sales intelligence and engagement platform. Use it to enrich people and company data (individually or in bulk), search Apollo''s database of over 240 million contacts and 30 million companies, and manage accounts, contacts, deals, sequences, tasks, calls, and conversations in your go-to-market workflows.
## Base URL
All API requests are made to `https://api.apollo.io/api/v1`.
## Authentication
- **Apollo users** authenticate with an API key passed in the `x-api-key` request header. See [Create API Keys](https://docs.apollo.io/docs/create-api-key).
- **Apollo partners** building integrations on behalf of mutual users authenticate with the [OAuth 2.0 authorization flow](https://docs.apollo.io/docs/use-oauth-20-authorization-flow-to-access-apollo-user-information-partners).
## Rate limits & credits
Rate limits and credit consumption depend on your [Apollo pricing plan](https://docs.apollo.io/docs/api-pricing). Check your current limits and usage with the [View API Usage Stats and Rate Limits](https://docs.apollo.io/reference/view-api-usage-stats) endpoint. For more details, see [Rate Limits](https://docs.apollo.io/reference/rate-limits) and the [API FAQs](https://docs.apollo.io/docs/apollo-api-faqs).
New to the API? Start with the [Apollo API overview](https://docs.apollo.io/reference/apollo-api).'
termsOfService: https://www.apollo.io/terms/api
contact:
name: Apollo API Support
url: https://docs.apollo.io/
servers:
- url: https://api.apollo.io/api/v1
security:
- apiKey: []
- bearerAuth: []
tags:
- name: Accounts
description: Create, update, and search the companies your team tracks in Apollo.
paths:
/accounts:
post:
summary: Create an Account
description: '## Endpoint essentials
**API key access:** `api/v1/accounts/create` or `Master API key`
**OAuth scopes:** `account_write`
**Credit usage:** `0 credits` — [Learn more about API pricing and credits](https://docs.apollo.io/docs/api-pricing).
An <a href="https://knowledge.apollo.io/hc/en-us/articles/5995865049229-View-and-Edit-Accounts" target="_blank">account</a> is a company saved in Apollo.<br><br>Use the Create an Account endpoint to add a new account to your team''s Apollo account.<br><br>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 <a href="https://docs.apollo.io/reference/update-an-account">Update an Account endpoint</a> instead.'
tags:
- Accounts
operationId: create-an-account
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: 'Name the account that you are creating. This should be a human-readable name. <br><br>Example: `The Irish Copywriters`'
domain:
type: string
description: 'The domain name for the account. <br><br>Do not include `www.` or similar. <br><br>Example: `apollo.io` or `microsoft.com`'
owner_id:
type: string
description: 'The ID for the account owner within your team''s Apollo account. <br><br>Use the <a href="https://docs.apollo.io/reference/get-a-list-of-users" target="_blank">Get a List of Users endpoint</a> to retrieve IDs for all of the users within your Apollo account. <br><br>Example: `66302798d03b9601c7934ebf`'
account_stage_id:
type: string
description: 'The Apollo ID for the account stage to which you want to assign the account. Call the <a href="https://docs.apollo.io/reference/list-account-stages" target="_blank">List Account Stages endpoint</a> to retrieve a list of all the account stage IDs available in your Apollo account. <br><br>If you do not specify the account stage, Apollo automatically assigns the account to a stage as determined by your team''s Apollo account. To change the order of account stages, launch the Apollo product and go to <b>Settings</b> > <b>Objects</b> > <a href="https://app.apollo.io/#/settings/accounts/stages" target="_blank"><b>Accounts</b></a>. Then, access the <b>Triggers</b> tab and change the stage for when an account is created.<br><br>Example: `6095a710bd01d100a506d4b9`'
phone:
type: string
description: 'The primary phone number for the account. <br><br>This can be the phone number for the corporate headquarters, a branch location, or a direct dial to the primary point of contact for the account. <br><br>Apollo sanitizes phone numbers, so you can enter them in any format. The sanitized number can be viewed in the endpoint response. <br><br>Examples: `555-555-0133`; `+44 7700 900852`'
raw_address:
type: string
description: 'The corporate location for the account. This can include a city, US state, and country. <br><br>Apollo matches the location you provide to the most applicable pre-defined location. <br><br>Examples: `Belfield, Dublin 4, Ireland`; `Dallas, United States`'
typed_custom_fields:
type: object
description: "Add information to <a href=\"https://knowledge.apollo.io/hc/en-us/articles/4412498754445-Create-Custom-Account-Fields\" target=\"_blank\">custom fields</a> in Apollo. <br><br><b>Your custom fields are unique to your team's Apollo account. This means that the examples in this documentation may not work for your testing purposes.</b> <br><br>To utilize this parameter successfully, call the <a href=\"https://docs.apollo.io/reference/get-a-list-of-all-custom-fields\">Get a List of All Custom Fields</a> endpoint and identify the `id` value for the custom field, as well as the appropriate data type. For example, if a custom field accepts picklist entries, you need to pass the accompanying `id` value for the picklist entry that you want to use as the input value. <br><br><b>Example</b>: When the <a href=\"https://docs.apollo.io/reference/get-a-list-of-all-custom-fields\">Get a List of All Custom Fields</a> endpoint returns an `id` of field: \n * `\"60c39ed82bd02f01154c470a\"` (datetime) \n \n\n then the value passed should be: \n\n `{\"60c39ed82bd02f01154c470a\": \"2025-08-07\"}`"
additionalProperties:
type: string
example:
60c39ed82bd02f01154c470a: '2025-08-07'
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
account:
id: 66e9abf95ac32901b20d1a0d
domain: irishcopywriters.ie
name: The Irish Copywriters
team_id: 6095a710bd01d100a506d4ac
organization_id: null
account_stage_id: 6095a710bd01d100a506d4b9
source: api
original_source: api
creator_id: null
owner_id: 66302798d03b9601c7934ebf
created_at: '2024-09-17T16:19:05.663Z'
phone: 555-555-0108
phone_status: no_status
hubspot_id: null
salesforce_id: null
crm_owner_id: null
parent_account_id: null
linkedin_url: null
sanitized_phone: '+15555550108'
account_playbook_statuses: []
account_rule_config_statuses: []
existence_level: full
label_ids: []
typed_custom_fields:
60c39ed82bd02f01154c470a: '2025-08-07'
custom_field_errors: {}
modality: account
source_display_name: Created from API
crm_record_url: null
show_intent: false
has_intent_signal_account: false
intent_signal_account: null
schema:
type: object
properties:
account:
type: object
properties:
id:
type: string
example: 66e9abf95ac32901b20d1a0d
domain:
type: string
example: irishcopywriters.ie
name:
type: string
example: The Irish Copywriters
team_id:
type: string
example: 6095a710bd01d100a506d4ac
organization_id: {}
account_stage_id:
type: string
example: 6095a710bd01d100a506d4b9
source:
type: string
example: api
original_source:
type: string
example: api
creator_id: {}
owner_id:
type: string
example: 66302798d03b9601c7934ebf
created_at:
type: string
example: '2024-09-17T16:19:05.663Z'
phone:
type: string
example: 555-555-0108
phone_status:
type: string
example: no_status
hubspot_id: {}
salesforce_id: {}
crm_owner_id: {}
parent_account_id: {}
linkedin_url: {}
sanitized_phone:
type: string
example: '+15555550108'
account_playbook_statuses:
type: array
account_rule_config_statuses:
type: array
existence_level:
type: string
example: full
label_ids:
type: array
typed_custom_fields:
type: object
properties: {}
custom_field_errors:
type: object
properties: {}
modality:
type: string
example: account
source_display_name:
type: string
example: Created from API
crm_record_url: {}
show_intent:
type: boolean
example: false
default: true
has_intent_signal_account:
type: boolean
example: false
default: true
intent_signal_account: {}
'401':
description: '401'
content:
text/plain:
examples:
Check API key:
value: Invalid API key. See https://docs.apollo.io/reference/authentication for how to authenticate.
'403':
description: '403'
content:
application/json:
examples:
Need master API key:
value: "{\n \"error\": \"This API key is not authorized to access api/v1/accounts/create. Request an API key from your administrator that includes this endpoint in its configured scope.\",\n \"error_code\": \"API_INACCESSIBLE\"\n}"
schema:
type: object
properties:
error:
type: string
example: This API key is not authorized to access api/v1/accounts/create. Request an API key from your administrator that includes this endpoint in its configured scope.
error_code:
type: string
example: API_INACCESSIBLE
'422':
description: '422'
content:
application/json:
examples:
Add name or domain:
value: "{\n \"error\": \"Please specify at least a name or domain.\"\n}"
schema:
type: object
properties:
error:
type: string
example: Please specify at least a name or domain.
'429':
description: '429'
content:
application/json:
examples:
Too many requests:
value: "{\n \"message\": \"The maximum number of api calls allowed for api/v1/accounts is 600 times per hour. Please upgrade your plan from https://app.apollo.io/#/settings/plans/upgrade.\"\n}"
schema:
type: object
properties:
message:
type: string
example: The maximum number of api calls allowed for api/v1/accounts is 600 times per hour. Please upgrade your plan from https://app.apollo.io/#/settings/plans/upgrade.
deprecated: false
/accounts/{account_id}:
patch:
summary: Update an Account
description: "## Endpoint essentials\n\n**API key access:** `api/v1/accounts/update` or `Master API key`\n\n**OAuth scopes:** `account_update`\n\n**Credit usage:** `0 credits` — [Learn more about API pricing and credits](https://docs.apollo.io/docs/api-pricing).\n\n An <a href=\"https://knowledge.apollo.io/hc/en-us/articles/5995865049229-View-and-Edit-Accounts\" target=\"_blank\">account</a> is a company saved in Apollo.<br><br>Use the Update an Account endpoint to update existing accounts in your team's Apollo account.<br><br>To create a new account, use the <a href=\"https://docs.apollo.io/reference/create-an-account\">Create an Account endpoint</a> instead. To update the account stage for multiple accounts, use the <a href=\"https://docs.apollo.io/reference/bulk-update-accounts\">Bulk Update Accounts endpoint</a>."
tags:
- Accounts
operationId: update-an-account
parameters:
- name: account_id
in: path
description: 'The Apollo ID for the account that you want to update. <br><br>To find account IDs, call the <a href="https://docs.apollo.io/reference/search-for-accounts" target="_blank">Search for Accounts endpoint</a> and identify the `id` value for the contact. <br><br>Example: `66e9abf95ac32901b20d1a0d`'
schema:
type: string
required: true
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: 'Update the account''s name. This should be a human-readable name. <br><br>Example: `The Fast Irish Copywriters`'
domain:
type: string
description: 'Update the domain name for the account. Do not include `www.` or similar. <br><br>Example: `apollo.io` or `microsoft.com`'
owner_id:
type: string
description: 'The ID for the account owner within your team''s Apollo account. Enter a different ID to update the owner of the account. <br><br>Use the <a href="https://docs.apollo.io/reference/get-a-list-of-users" target="_blank">Get a List of Users endpoint</a> to retrieve IDs for all of the users within your Apollo account. <br><br>Example: `66302798d03b9601c7934ebf`'
account_stage_id:
type: string
description: 'The Apollo ID for the account stage to which you want to assign the account. Enter a different ID to update the account stage. <br><br>Call the <a href="https://docs.apollo.io/reference/list-account-stages" target="_blank">List Account Stages endpoint</a> to retrieve a list of all the account stage IDs available in your Apollo account. <br><br>If you do not specify the account stage, Apollo automatically assigns the account to a stage as determined by your team''s Apollo account. To change the order of account stages, launch the Apollo product and go to <b>Settings</b> > <b>Objects</b> > <a href="https://app.apollo.io/#/settings/accounts/stages" target="_blank"><b>Accounts</b></a>. Then, access the <b>Triggers</b> tab and change the stage for when an account is created. <br><br>Example: `61b8e913e0f4d2012e3af74e`'
raw_address:
type: string
description: 'Update the corporate location for the account. This can include a city, US state, and country. <br><br>Apollo matches the location you provide to the most applicable pre-defined location. <br><br>Examples: `Belfield, Dublin 4, Ireland`; `Dallas, United States`'
phone:
type: string
description: 'Update the primary phone number for the account. <br><br>This can be the phone number for the corporate headquarters, a branch location, or a direct dial to the primary point of contact for the account. <br><br>Apollo sanitizes phone numbers, so you can enter them in any format. The sanitized number can be viewed in the endpoint response. <br><br>Examples: `555-555-0133`; `+44 7700 900852`'
typed_custom_fields:
type: object
description: "Add information to <a href=\"https://knowledge.apollo.io/hc/en-us/articles/4412498754445-Create-Custom-Account-Fields\" target=\"_blank\">custom fields</a> in Apollo. <br><br><b>Your custom fields are unique to your team's Apollo account. This means that the examples in this documentation may not work for your testing purposes.</b> <br><br>To utilize this parameter successfully, call the <a href=\"https://docs.apollo.io/reference/get-a-list-of-all-custom-fields\">Get a List of All Custom Fields</a> endpoint and identify the `id` value for the custom field, as well as the appropriate data type. For example, if a custom field accepts picklist entries, you need to pass the accompanying `id` value for the picklist entry that you want to use as the input value. <br><br><b>Example</b>: When the <a href=\"https://docs.apollo.io/reference/get-a-list-of-all-custom-fields\">Get a List of All Custom Fields</a> endpoint returns an `id` of field: \n * `\"60c39ed82bd02f01154c470a\"` (datetime) \n \n\n then the value passed should be: \n\n `{\"60c39ed82bd02f01154c470a\": \"2025-08-07\"}`"
additionalProperties:
type: string
example:
60c39ed82bd02f01154c470a: '2025-08-07'
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
account:
id: 66e9abf95ac32901b20d1a0d
domain: irishcopywriters.com
name: The Fast Irish Copywriters
team_id: 6095a710bd01d100a506d4ac
organization_id: null
account_stage_id: 61b8e913e0f4d2012e3af74e
source: api
original_source: api
creator_id: null
owner_id: 66302798d03b9601c7934ebf
created_at: '2024-09-17T16:19:05.663Z'
phone: 555-555-0172
phone_status: no_status
hubspot_id: null
salesforce_id: null
crm_owner_id: null
parent_account_id: null
linkedin_url: null
sanitized_phone: '+15555550172'
account_playbook_statuses: []
account_rule_config_statuses: []
existence_level: full
label_ids: []
custom_field_errors: {}
modality: account
source_display_name: Created from API
crm_record_url: null
show_intent: false
has_intent_signal_account: false
intent_signal_account: null
typed_custom_fields:
60c39ed82bd02f01154c470a: '2025-08-07'
labels: []
schema:
type: object
properties:
account:
type: object
properties:
id:
type: string
example: 66e9abf95ac32901b20d1a0d
domain:
type: string
example: irishcopywriters.com
name:
type: string
example: The Fast Irish Copywriters
team_id:
type: string
example: 6095a710bd01d100a506d4ac
organization_id: {}
account_stage_id:
type: string
example: 61b8e913e0f4d2012e3af74e
source:
type: string
example: api
original_source:
type: string
example: api
creator_id: {}
owner_id:
type: string
example: 66302798d03b9601c7934ebf
created_at:
type: string
example: '2024-09-17T16:19:05.663Z'
phone:
type: string
example: 555-555-0172
phone_status:
type: string
example: no_status
hubspot_id: {}
salesforce_id: {}
crm_owner_id: {}
parent_account_id: {}
linkedin_url: {}
sanitized_phone:
type: string
example: '+15555550172'
account_playbook_statuses:
type: array
account_rule_config_statuses:
type: array
existence_level:
type: string
example: full
label_ids:
type: array
typed_custom_fields:
type: object
properties: {}
custom_field_errors:
type: object
properties: {}
modality:
type: string
example: account
source_display_name:
type: string
example: Created from API
crm_record_url: {}
show_intent:
type: boolean
example: false
default: true
has_intent_signal_account:
type: boolean
example: false
default: true
intent_signal_account: {}
labels:
type: array
'401':
description: '401'
content:
text/plain:
examples:
Check API key:
value: Invalid API key. See https://docs.apollo.io/reference/authentication for how to authenticate.
'403':
description: '403'
content:
application/json:
examples:
Need master API key:
value: "{\n \"error\": \"This API key is not authorized to access api/v1/accounts/update. Request an API key from your administrator that includes this endpoint in its configured scope.\",\n \"error_code\": \"API_INACCESSIBLE\"\n}"
schema:
type: object
properties:
error:
type: string
example: This API key is not authorized to access api/v1/accounts/update. Request an API key from your administrator that includes this endpoint in its configured scope.
error_code:
type: string
example: API_INACCESSIBLE
'422':
description: '422'
content:
application/json:
examples:
Check account ID:
value: "{\n \"error\": \"Parameters misconfigured. account_id is not a valid ID\"\n}"
Check owner ID:
value: "{\n \"error\": \"Parameters misconfigured. 23423423 is not a valid ID\"\n}"
Check account stage ID:
value: "{\n \"error\": \"Parameters misconfigured. 78977 is not a valid ID\"\n}"
schema:
oneOf:
- title: Check account ID
type: object
properties:
error:
type: string
example: Parameters misconfigured. account_id is not a valid ID
- title: Check owner ID
type: object
properties:
error:
type: string
example: Parameters misconfigured. 23423423 is not a valid ID
- title: Check account stage ID
type: object
properties:
error:
type: string
example: Parameters misconfigured. 78977 is not a valid ID
'429':
description: '429'
content:
application/json:
examples:
Too many requests:
value: "{\n \"message\": \"The maximum number of api calls allowed for api/v1/accounts/{account_id} is 600 times per hour. Please upgrade your plan from https://app.apollo.io/#/settings/plans/upgrade.\"\n}"
schema:
type: object
properties:
message:
type: string
example: The maximum number of api calls allowed for api/v1/accounts/{account_id} is 600 times per hour. Please upgrade your plan from https://app.apollo.io/#/settings/plans/upgrade.
deprecated: false
/accounts/search:
post:
summary: Search for Accounts
description: "## Endpoint essentials\n\n**API key access:** `api/v1/accounts/search` or `Master API key`\n\n**OAuth scopes:** `accounts_search`\n\n**Credit usage:** `0 credits` — [Learn more about API pricing and credits](https://docs.apollo.io/docs/api-pricing).\n\n An <a href=\"https://knowledge.apollo.io/hc/en-us/articles/5995865049229-View-and-Edit-Accounts\" target=\"_blank\">account</a> is a company saved in Apollo.<br><br>Use the Search for Accounts endpoint to search for an account that has been saved to Apollo.<br><br>This endpoint only returns accounts in the search results. To search for companies in Apollo, call the <a href=\"https://docs.apollo.io/reference/organization-search\">Organization Search endpoint</a>.<br><br>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."
tags:
- Accounts
operationId: search-for-accounts
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
q_organization_name:
type: string
description: 'Add keywords to narrow the search of the accounts in your team''s Apollo account. Keywords should directly match at least part of an account''s name. For example, searching the keyword `marketing` might return the result `NY Marketing Unlimited`, but not `NY Market Analysts`. This parameter only searches account names, not other account fields. Examples: `apollo`; `microsoft`; `marketing`'
account_stage_ids:
type: array
items:
type: string
description: 'The Apollo IDs for the account stages that you want to include in your search results. If you add multiple account stages, Apollo will include all accounts that match any of the stages, along with the other parameters, in the search results. Call the [List Account Stages endpoint](https://docs.apollo.io/reference/list-account-stages) to retrieve a list of all the account stage IDs available in your Apollo account. Example: `61b8e913e0f4d2012e3af74e`'
account_label_ids:
type: array
items:
type: string
description: 'The Apollo IDs for the labels that you want to include in your search results. If you add multiple labels, Apollo will include all accounts connected to any of the labels, along with the other parameters, in the search results. Example: `[''6095a710bd01d100a506d4ae'']`'
sort_by_field:
type: string
enum:
- account_last_activity_date
- account_created_at
- account_updated_at
description: 'Sort the matching accounts by 1 of the following options:
- `account_last_activity_date`: The most recent activity date recorded first.
- `account_created_at`: The most recently created first.
- `account_updated_at`: The most recently updated first.'
sort_ascending:
type: boolean
default: false
description: 'Set to `true` to sort the matching accounts in ascending order. This parameter must be used with `sort_by_field`. Otherwise, the sorting logic is not applied. Example: `true`'
page:
type: integer
format: int32
description: 'The page number of the Apollo data that you want to retrieve. Use this parameter in combination with the `per_page` parameter to make search results navigable and improve the performance of the endpoint. Example: `4`'
per_page:
type: integer
format: int32
description: 'The number of search results that should be returned for each page. Limiting the number of results per page improves the endpoint''s performance. Use the `page` parameter to navigate through the different pages of data. Example: `10`'
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
breadcrumbs:
- label: Company Name
signal_field_name: q_organization_name
value: Irish Copywriters
display_name: Irish Copywriters
- label: Account Stage
# --- truncated at 32 KB (99 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apollo-io/refs/heads/main/openapi/apollo-io-accounts-api-openapi.yml