Workspace CRM accounts — create, update, search, stages and ownership. 8 operation(s) from the published Apollo OpenAPI.
openapi: 3.1.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
tags:
- name: Accounts
description: Create, update, and search the companies your team tracks in Apollo.
security:
- apiKey: []
- bearerAuth: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: '[Recommended] API key, passed in the `x-api-key` request header.
See [Create API Keys](https://docs.apollo.io/docs/create-api-key).'
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: 'OAuth 2.0 access token, used by Apollo partners building integrations.
See the [OAuth 2.0 authorization flow](https://docs.apollo.io/docs/use-oauth-20-authorization-flow-to-access-apollo-user-information-partners).'
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
# --- truncated at 32 KB (104 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apollo-io/refs/heads/main/openapi/apollo-io-accounts-api-openapi.yml