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.
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.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "apollo-rest-api",
"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.\n\n## Base URL\n\nAll API requests are made to `https://api.apollo.io/api/v1`.\n\n## Authentication\n\n- **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).\n- **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).\n\n## Rate limits & credits\n\nRate 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).\n\nNew 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/"
},
"version": "1.0"
},
"servers": [
{
"url": "https://api.apollo.io/api/v1"
}
],
"tags": [
{
"name": "Accounts",
"description": "Create, update, and search the companies your team tracks in Apollo."
}
],
"components": {
"securitySchemes": {
"apiKey": {
"type": "apiKey",
"in": "header",
"name": "x-api-key",
"description": "[Recommended] API key, passed in the `x-api-key` request header.\nSee [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.\nSee the [OAuth 2.0 authorization flow](https://docs.apollo.io/docs/use-oauth-20-authorization-flow-to-access-apollo-user-information-partners)."
}
},
"schemas": {
"ErrorDetails": {
"type": "object",
"description": "Machine-readable detail for an error that uses the new format, returned alongside the endpoint's existing error fields. The legacy error fields at the root level (`error`, `error_code`, `message`, etc) are removed on 2027-02-16, after which `error_details` is the only error payload. Some errors already return `error_details` on its own.",
"properties": {
"code": {
"type": "string",
"description": "Stable identifier in the form `DOMAIN.CATEGORY.REASON`. Branch on this value; the human-readable `message` can change.",
"example": "AUTH.AUTHENTICATION.CREDENTIALS_MISSING"
},
"message": {
"type": "string",
"description": "Human-readable explanation of what went wrong.",
"example": "This request carried no credential Apollo could authenticate."
},
"suggestions": {
"type": "array",
"description": "Ordered, actionable next steps. Each entry carries a `label`, and where relevant the `parameter`, `header`, or `url` it refers to.",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"example": "Send your API key in the X-Api-Key header"
},
"url": {
"type": "string",
"example": "https://docs.apollo.io/reference/authentication"
},
"parameter": {
"type": "string",
"example": "webhook_url"
},
"parameters": {
"type": "array",
"description": "Several parameters, any one of which satisfies the requirement.",
"items": {
"type": "string"
},
"example": [
"name",
"domain",
"website_url",
"linkedin_url"
]
},
"header": {
"type": "string",
"example": "X-Api-Key"
},
"example": {
"type": "string",
"description": "A valid sample value for the parameter named above."
},
"retry_after_seconds": {
"type": "integer",
"description": "On a rate-limit refusal, how long to wait before retrying.",
"example": 60
}
}
}
},
"context": {
"type": "object",
"description": "Values from your request that explain the refusal. Each entry is an object rather than a bare value, so read `context..value`. Absent when the error needs no context.",
"additionalProperties": {
"type": "object",
"properties": {
"value": {
"type": "string"
},
"description": {
"type": "string"
}
}
},
"example": {
"window": {
"value": "hourly",
"description": "The rate-limit window your request exceeded"
}
}
}
}
}
}
},
"security": [
{
"apiKey": []
},
{
"bearerAuth": []
}
],
"paths": {
"/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 account 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.
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:\n- `account_last_activity_date`: The most recent activity date recorded first.\n- `account_created_at`: The most recently created first.\n- `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",
"signal_field_name": "account_stage_ids",
"value": "61b8e913e0f4d2012e3af74e",
"display_name": "Lead"
}
],
"partial_results_only": false,
"has_join": false,
"disable_eu_prospecting": false,
"partial_results_limit": 10000,
"pagination": {
"page": 1,
"per_page": 5,
"total_entries": 1,
"total_pages": 1
},
"accounts": [
{
"id": "66e9abf95ac32901b20d1a0d",
"domain": "irishcopywriters.com",
"name": "The Fast Irish Copywriters",
"team_id": "6095a710bd01d100a506d4ac",
"organization_id": null,
"account_stage_id": "61b8e913e0f4d2012e3af74e",
"label_ids": [
"68eec47ece3b0b000de4751f"
],
"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",
"typed_custom_fields": {},
"custom_field_errors": {},
"modality": "account",
"source_display_name": "Created from API",
"crm_record_url": null,
"contact_emailer_campaign_ids": [],
"contact_campaign_status_tally": {},
"num_contacts": 0,
"last_activity_date": null,
"show_intent": false,
"has_intent_signal_account": false,
"intent_signal_account": null
}
],
"num_fetch_result": null
}
}
},
"schema": {
"type": "object",
"properties": {
"breadcrumbs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"example": "Company Name"
},
"signal_field_name": {
"type": "string",
"example": "q_organization_name"
},
"value": {
"type": "string",
"example": "Irish Copywriters"
},
"display_name": {
"type": "string",
"example": "Irish Copywriters"
}
}
}
},
"partial_results_only": {
"type": "boolean",
"example": false,
"default": true
},
"has_join": {
"type": "boolean",
"example": false,
"default": true
},
"disable_eu_prospecting": {
"type": "boolean",
"example": false,
"default": true
},
"partial_results_limit": {
"type": "integer",
"example": 10000,
"default": 0
},
"pagination": {
"type": "object",
"properties": {
"page": {
"type": "integer",
"example": 1,
"default": 0
},
"per_page": {
"type": "integer",
"example": 5,
"default": 0
},
"total_entries": {
"type": "integer",
"example": 1,
"default": 0
},
"total_pages": {
"type": "integer",
"example": 1,
"default": 0
}
}
},
"accounts": {
"type": "array",
"items": {
"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": {},
"contact_emailer_campaign_ids": {
"type": "array"
},
"contact_campaign_status_tally": {
"type": "object",
"properties": {}
},
"num_contacts": {
"type": "integer",
"example": 0,
"default": 0
},
"last_activity_date": {},
"show_intent": {
"type": "boolean",
"example": false,
"default": true
},
"has_intent_signal_account": {
"type": "boolean",
"example": false,
"default": true
},
"intent_signal_account": {}
}
}
},
"num_fetch_result": {}
}
}
}
}
},
"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": {
"Check Apollo pricing plan": {
"value": "{\n \"message\": \"This endpoint is only available to Apollo users on paid plans.\"\n}"
}
},
"schema": {
"type": "object",
"properties": {
"error_details": {
"$ref": "#/components/schemas/ErrorDetails"
},
"message": {
"deprecated": true,
"description": "Legacy error field. Removed on 2027-02-16, after which `error_details` is the only error payload.",
"type": "string",
"example": "This endpoint is only available to Apollo users on paid plans."
}
}
}
}
}
},
"422": {
"description": "422",
"content": {
"application/json": {
"examples": {
"Choose valid sort_by_field option": {
"value": "{\n \"error\": \"Invalid sort criteria\",\n \"skip_alert_dialog\": true\n}"
},
"Check account stage IDs": {
"value": "{\n \"error\": \"Your search parameters are entered incorrectly. Did you try to edit the URL directly?\"\n}"
}
},
"schema": {
"oneOf": [
{
"title": "Choose valid sort_by_field option",
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Invalid sort criteria"
},
"skip_alert_dialog": {
"type": "boolean",
"example": true,
"default": true
}
}
},
{
"title": "Check account stage IDs",
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Your search parameters are entered incorrectly. Did you try to edit the URL directly?"
}
}
}
]
}
}
}
},
"429": {
"description": "429",
"content": {
"application/json": {
"examples": {
"Too many requests": {
"value": "{\n \"message\": \"The maximum number of api calls allowed for api/v1/accounts/search is 600 times per hour. Please upgrade your plan from https://app.apollo.io/#/settings/plans/upgrade.\",\n \"error_details\": {\n \"code\": \"USAGE.RATE_LIMIT.API_RATE_LIMIT_EXCEEDED\",\n \"message\": \"You have made more API requests than your plan allows in this time window.\",\n \"suggestions\": [\n {\n \"label\": \"Wait until the rate limit resets, then retry the API request.\"\n },\n {\n \"label\": \"Check the Apollo Docs to understand API rate limits and how to use response headers to prevent rate-limit errors.\",\n \"url\": \"https://docs.apollo.io/reference/rate-limits\"\n }\n ],\n \"context\": {\n \"window\": {\n \"value\": \"hour\",\n \"description\": \"The rate limit window that was exhausted, such as \\\"minute\\\" or \\\"hour\\\"\"\n }\n }\n }\n}"
}
},
"schema": {
"type": "object",
"properties": {
"error_details": {
"$ref": "#/components/schemas/ErrorDetails"
},
"message": {
"deprecated": true,
"description": "Legacy error field. Removed on 2027-02-16, after which `error_details` is the only error payload.",
"type": "string",
"example": "The maximum number of api calls allowed for api/v1/accounts/search is 600 times per hour. Please upgrade your plan from https://app.apollo.io/#/settings/plans/upgrade."
}
}
}
}
}
}
},
"deprecated": false
}
}
},
"x-readme": {
"headers": [
{
"key": "Cache-Control",
"value": "no-cache"
},
{
"key": "Content-Type",
"value": "application/json"
}
],
"explorer-enabled": true,
"proxy-enabled": true
},
"x-readme-fauxas": true
}
```