# Search for Contacts Use the Search for Contacts endpoint to search for the contacts that have been added to your team's Apollo account.

In Apollo terminology, a contact is a person that your team has explicitly added to your database. A contact will have their data enriched in some way, such as accessing an email address or a phone number.

This endpoint only returns contacts in the search results. To search for people in the Apollo database, call the People API 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. This limitation does not restrict your access to Apollo's database; you just need to access the data in batches. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "apollo-rest-api", "version": "1.0" }, "servers": [ { "url": "https://api.apollo.io/api/v1" } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "[Recommended] OAuth Access token" } } }, "security": [ { "bearerAuth": [] }, { "apiKey": [] } ], "paths": { "/contacts/search": { "post": { "summary": "Search for Contacts", "description": "Use the Search for Contacts endpoint to search for the contacts that have been added to your team's Apollo account.

In Apollo terminology, a contact is a person that your team has explicitly added to your database. A contact will have their data enriched in some way, such as accessing an email address or a phone number.

This endpoint only returns contacts in the search results. To search for people in the Apollo database, call the People API 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. This limitation does not restrict your access to Apollo's database; you just need to access the data in batches.", "operationId": "search-for-contacts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q_keywords": { "type": "string", "description": "Add keywords to narrow the search of the contacts in your team's Apollo account. Keywords can include combinations of names, job titles, employers (company names), and email addresses. Examples: `tim zheng`; `senior research analyst`; `microsoft`" }, "contact_stage_ids": { "type": "array", "items": { "type": "string" }, "description": "The Apollo IDs for the contact stages that you want to include in your search results. If you add multiple contact stages, Apollo will include all contacts that match any of the stages, along with the other parameters, in the search results. Call the [List Contact Stages endpoint](https://docs.apollo.io/reference/list-contact-stages) to retrieve a list of all the contact stage IDs available in your Apollo account. Example: `6095a710bd01d100a506d4ae`" }, "contact_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 contacts connected to any of the labels, along with the other parameters, in the search results. Example: `['6095a710bd01d100a506d4ae']`" }, "sort_by_field": { "type": "string", "description": "Sort the matching contacts by 1 of the following options: \n- `contact_last_activity_date`: The most recent activity date recorded first.\n- `contact_email_last_opened_at`: The most recent email opened date first.\n- `contact_email_last_clicked_at`: The most recent email clicked first.\n- `contact_created_at`: The most recently created first.\n- `contact_updated_at`: The most recently updated first." }, "sort_ascending": { "type": "boolean", "default": false, "description": "Set to `true` to sort the matching contacts in ascending order. This parameter must be used with `sort_by_field`. Otherwise, the sorting logic is not applied. Example: `true`" }, "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 search the different pages of data. Example: `10`" }, "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`" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "contacts": [ { "contact_roles": [], "id": "66e3726977d36c03f2c30afc", "first_name": "Walt", "last_name": "Whitman", "name": "Walt Whitman", "linkedin_url": null, "title": "Associate Writer", "contact_stage_id": "6095a710bd01d100a506d4ae", "owner_id": "60affe7d6e270a00f5db6fe4", "creator_id": "60affe7d6e270a00f5db6fe4", "person_id": null, "email_needs_tickling": null, "organization_name": "Apollo.io", "source": "api", "original_source": "api", "organization_id": "5e66b6381e05b4008c8331b8", "headline": null, "photo_url": null, "present_raw_address": null, "linkedin_uid": null, "extrapolated_email_confidence": null, "salesforce_id": null, "salesforce_lead_id": null, "salesforce_contact_id": null, "salesforce_account_id": null, "crm_owner_id": null, "created_at": "2024-09-12T22:59:53.423Z", "emailer_campaign_ids": [], "direct_dial_status": null, "direct_dial_enrichment_failed_at": null, "email_status": "verified", "email_source": null, "account_id": "63f53afe4ceeca00016bdd2f", "last_activity_date": null, "hubspot_vid": null, "hubspot_company_id": null, "crm_id": null, "sanitized_phone": null, "merged_crm_ids": null, "updated_at": "2024-09-12T23:00:41.194Z", "queued_for_crm_push": false, "suggested_from_rule_engine_config_id": null, "email_unsubscribed": null, "label_ids": [ "68eec47ece3b0b000de4751f" ], "has_pending_email_arcgate_request": false, "has_email_arcgate_request": false, "existence_level": "full", "email": "wwhitman@apollo.io", "email_from_customer": true, "typed_custom_fields": {}, "custom_field_errors": {}, "crm_record_url": null, "email_status_unavailable_reason": null, "email_true_status": "User Managed", "updated_email_true_status": true, "contact_rule_config_statuses": [], "source_display_name": "Created from API", "twitter_url": null, "contact_campaign_statuses": [], "account": { "id": "63f53afe4ceeca00016bdd2f", "name": "Apollo.io", "website_url": "http://www.apollo.io", "blog_url": null, "angellist_url": null, "linkedin_url": "http://www.linkedin.com/company/apolloio", "twitter_url": "https://twitter.com/meetapollo/", "facebook_url": "https://www.facebook.com/MeetApollo", "primary_phone": {}, "languages": [], "alexa_ranking": 3514, "phone": "+1(202) 374-1312", "linkedin_uid": "18511550", "founded_year": 2015, "publicly_traded_symbol": null, "publicly_traded_exchange": null, "logo_url": "https://zenprospect-production.s3.amazonaws.com/uploads/pictures/66d13c8d98ec9600013525b8/picture", "crunchbase_url": null, "primary_domain": "apollo.io", "domain": "apollo.io", "team_id": "6095a710bd01d100a506d4ac", "organization_id": "5e66b6381e05b4008c8331b8", "account_stage_id": null, "source": "csv_import", "original_source": "salesforce", "creator_id": null, "owner_id": "66302798d03b9601c7934ec2", "created_at": "2023-02-21T21:43:26.351Z", "phone_status": "no_status", "hubspot_id": "7", "salesforce_id": null, "crm_owner_id": "21973720", "parent_account_id": null, "sanitized_phone": "+12023741312", "account_playbook_statuses": [], "account_rule_config_statuses": [ { "_id": "664f9eef1fded70001e4983e", "created_at": null, "rule_action_config_id": "65735e0ea63d2700faba5c6e", "rule_config_id": "65735e0ea63d2700faba5c6f", "status_cd": "completed", "updated_at": null, "id": "664f9eef1fded70001e4983e", "key": "664f9eef1fded70001e4983e" } ], "existence_level": "full", "label_ids": [ "6504905b21ba8e00a334eb0f" ], "typed_custom_fields": {}, "custom_field_errors": {}, "modality": "account", "source_display_name": "Uploaded from CSV", "crm_record_url": "https://sumware.pipedrive.com/organization/7" }, "contact_emails": [], "organization": { "id": "5e66b6381e05b4008c8331b8", "name": "Apollo.io", "website_url": "http://www.apollo.io", "blog_url": null, "angellist_url": null, "linkedin_url": "http://www.linkedin.com/company/apolloio", "twitter_url": "https://twitter.com/meetapollo/", "facebook_url": "https://www.facebook.com/MeetApollo", "primary_phone": {}, "languages": [], "alexa_ranking": 3514, "phone": null, "linkedin_uid": "18511550", "founded_year": 2015, "publicly_traded_symbol": null, "publicly_traded_exchange": null, "logo_url": "https://zenprospect-production.s3.amazonaws.com/uploads/pictures/66d13c8d98ec9600013525b8/picture", "crunchbase_url": null, "primary_domain": "apollo.io" }, "intent_strength": null, "show_intent": false, "phone_numbers": [], "account_phone_note": null, "free_domain": false, "is_likely_to_engage": false, "email_domain_catchall": false, "contact_job_change_event": null } ], "breadcrumbs": [ { "label": "Contains Keywords", "signal_field_name": "q_keywords", "value": "Apollo.io", "display_name": "Apollo.io" }, { "label": "Contact Stage", "signal_field_name": "contact_stage_ids", "value": "6095a710bd01d100a506d4ae", "display_name": "New" }, { "label": "Contact Stage", "signal_field_name": "contact_stage_ids", "value": "66e34b81740c50074e3d1bd4", "display_name": "[Deleted Stage]" } ], "partial_results_only": false, "has_join": false, "disable_eu_prospecting": false, "partial_results_limit": 10000, "pagination": { "page": 1, "per_page": 2, "total_entries": 178, "total_pages": 89 }, "num_fetch_result": null } } }, "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "contact_roles": { "type": "array" }, "id": { "type": "string", "example": "66e3726977d36c03f2c30afc" }, "first_name": { "type": "string", "example": "Walt" }, "last_name": { "type": "string", "example": "Whitman" }, "name": { "type": "string", "example": "Walt Whitman" }, "linkedin_url": {}, "title": { "type": "string", "example": "Associate Writer" }, "contact_stage_id": { "type": "string", "example": "6095a710bd01d100a506d4ae" }, "owner_id": { "type": "string", "example": "60affe7d6e270a00f5db6fe4" }, "creator_id": { "type": "string", "example": "60affe7d6e270a00f5db6fe4" }, "person_id": {}, "email_needs_tickling": {}, "organization_name": { "type": "string", "example": "Apollo.io" }, "source": { "type": "string", "example": "api" }, "original_source": { "type": "string", "example": "api" }, "organization_id": { "type": "string", "example": "5e66b6381e05b4008c8331b8" }, "headline": {}, "photo_url": {}, "present_raw_address": {}, "linkedin_uid": {}, "extrapolated_email_confidence": {}, "salesforce_id": {}, "salesforce_lead_id": {}, "salesforce_contact_id": {}, "salesforce_account_id": {}, "crm_owner_id": {}, "created_at": { "type": "string", "example": "2024-09-12T22:59:53.423Z" }, "emailer_campaign_ids": { "type": "array" }, "direct_dial_status": {}, "direct_dial_enrichment_failed_at": {}, "email_status": { "type": "string", "example": "verified" }, "email_source": {}, "account_id": { "type": "string", "example": "63f53afe4ceeca00016bdd2f" }, "last_activity_date": {}, "hubspot_vid": {}, "hubspot_company_id": {}, "crm_id": {}, "sanitized_phone": {}, "merged_crm_ids": {}, "updated_at": { "type": "string", "example": "2024-09-12T23:00:41.194Z" }, "queued_for_crm_push": { "type": "boolean", "example": false, "default": true }, "suggested_from_rule_engine_config_id": {}, "email_unsubscribed": {}, "label_ids": { "type": "array" }, "has_pending_email_arcgate_request": { "type": "boolean", "example": false, "default": true }, "has_email_arcgate_request": { "type": "boolean", "example": false, "default": true }, "existence_level": { "type": "string", "example": "full" }, "email": { "type": "string", "example": "wwhitman@apollo.io" }, "email_from_customer": { "type": "boolean", "example": true, "default": true }, "typed_custom_fields": { "type": "object", "properties": {} }, "custom_field_errors": { "type": "object", "properties": {} }, "crm_record_url": {}, "email_status_unavailable_reason": {}, "email_true_status": { "type": "string", "example": "User Managed" }, "updated_email_true_status": { "type": "boolean", "example": true, "default": true }, "contact_rule_config_statuses": { "type": "array" }, "source_display_name": { "type": "string", "example": "Created from API" }, "twitter_url": {}, "contact_campaign_statuses": { "type": "array", "description": "Array of campaign statuses for the contact, showing their participation in various email sequences", "items": { "type": "object", "description": "Contact campaign status object representing the contact's current state in a specific email sequence", "properties": { "id": { "type": "string", "description": "Unique identifier for this contact campaign status record", "example": "68782af181c7f0002159df25" }, "emailer_campaign_id": { "type": "string", "description": "ID of the email sequence (emailer campaign) this status belongs to", "example": "66e9e215ece19801b219997f" }, "send_email_from_user_id": { "type": "string", "description": "ID of the user who is sending emails for this contact in the sequence", "example": "66302798d03b9601c7934ebf" }, "inactive_reason": { "type": "string", "nullable": true, "description": "Reason why the contact is inactive in this sequence, if applicable", "example": "Sequence inactive" }, "status": { "type": "string", "description": "Current status of the contact in this email sequence", "enum": [ "active", "failed", "paused", "finished" ], "example": "paused" }, "added_at": { "type": "string", "format": "date-time", "description": "Timestamp when the contact was added to this sequence", "example": "2025-07-16T22:42:57.372+00:00" }, "added_by_user_id": { "type": "string", "description": "ID of the user who added this contact to the sequence", "example": "60affe7d6e270a00f5db6fe4" }, "finished_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the contact finished/completed the sequence", "example": null }, "paused_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the contact was paused in the sequence", "example": null }, "auto_unpause_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Scheduled timestamp for automatically unpausing the contact", "example": null }, "send_email_from_email_address": { "type": "string", "nullable": true, "description": "Specific email address used to send emails to this contact", "example": "test.brandan.blevins@apollomail.io" }, "send_email_from_email_account_id": { "type": "string", "description": "ID of the email account used to send emails to this contact", "example": "6633baaece5fbd01c791d7ca" }, "manually_set_unpause": { "type": "boolean", "nullable": true, "description": "Whether the unpause was manually set by a user", "example": null }, "failure_reason": { "type": "string", "nullable": true, "description": "Specific reason for failure if status is 'failed'", "enum": [ "hard_bounced", "spam_blocked", "bounced", "past_date_failure" ], "example": null }, "current_step_id": { "type": "string", "nullable": true, "description": "ID of the current step in the sequence that the contact is on", "example": null }, "in_response_to_emailer_message_id": { "type": "string", "nullable": true, "description": "ID of the emailer message this campaign status is in response to", "example": null }, "cc_emails": { "type": "array", "nullable": true, "description": "Email addresses to CC when sending emails to this contact", "items": { "type": "string" }, "example": null }, "bcc_emails": { "type": "array", "nullable": true, "description": "Email addresses to BCC when sending emails to this contact", "items": { "type": "string" }, "example": null }, "to_emails": { "type": "array", "nullable": true, "description": "Additional email addresses to include in TO field when sending emails", "items": { "type": "string" }, "example": null }, "current_step_position": { "type": "integer", "nullable": true, "description": "Position number of the current step in the sequence (1-based indexing)", "example": null } }, "required": [ "id", "emailer_campaign_id", "send_email_from_user_id", "status", "added_at", "added_by_user_id", "send_email_from_email_account_id" ] } }, "account": { "type": "object", "properties": { "id": { "type": "string", "example": "63f53afe4ceeca00016bdd2f" }, "name": { "type": "string", "example": "Apollo.io" }, "website_url": { "type": "string", "example": "http://www.apollo.io" }, "blog_url": {}, "angellist_url": {}, "linkedin_url": { "type": "string", "example": "http://www.linkedin.com/company/apolloio" }, "twitter_url": { "type": "string", "example": "https://twitter.com/meetapollo/" }, "facebook_url": { "type": "string", "example": "https://www.facebook.com/MeetApollo" }, "primary_phone": { "type": "object", "properties": {} }, "languages": { "type": "array" }, "alexa_ranking": { "type": "integer", "example": 3514, "default": 0 }, "phone": { "type": "string", "example": "+1(202) 374-1312" }, "linkedin_uid": { "type": "string", "example": "18511550" }, "founded_year": { "type": "integer", "example": 2015, "default": 0 }, "publicly_traded_symbol": {}, "publicly_traded_exchange": {}, "logo_url": { "type": "string", "example": "https://zenprospect-production.s3.amazonaws.com/uploads/pictures/66d13c8d98ec9600013525b8/picture" }, "crunchbase_url": {}, "primary_domain": { "type": "string", "example": "apollo.io" }, "domain": { "type": "string", "example": "apollo.io" }, "team_id": { "type": "string", "example": "6095a710bd01d100a506d4ac" }, "organization_id": { "type": "string", "example": "5e66b6381e05b4008c8331b8" }, "account_stage_id": {}, "source": { "type": "string", "example": "csv_import" }, "original_source": { "type": "string", "example": "salesforce" }, "creator_id": {}, "owner_id": { "type": "string", "example": "66302798d03b9601c7934ec2" }, "created_at": { "type": "string", "example": "2023-02-21T21:43:26.351Z" }, "phone_status": { "type": "string", "example": "no_status" }, "hubspot_id": { "type": "string", "example": "7" }, "salesforce_id": {}, "crm_owner_id": { "type": "string", "example": "21973720" }, "parent_account_id": {}, "sanitized_phone": { "type": "string", "example": "+12023741312" }, "account_playbook_statuses": { "type": "array" }, "account_rule_config_statuses": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "example": "664f9eef1fded70001e4983e" }, "created_at": {}, "rule_action_config_id": { "type": "string", "example": "65735e0ea63d2700faba5c6e" }, "rule_config_id": { "type": "string", "example": "65735e0ea63d2700faba5c6f" }, "status_cd": { "type": "string", "example": "completed" }, "updated_at": {}, "id": { "type": "string", "example": "664f9eef1fded70001e4983e" }, "key": { "type": "string", "example": "664f9eef1fded70001e4983e" } } } }, "existence_level": { "type": "string", "example": "full" }, "label_ids": { "type": "array", "items": { "type": "string", "example": "6504905b21ba8e00a334eb0f" } }, "typed_custom_fields": { "type": "object", "properties": {} }, "custom_field_errors": { "type": "object", "properties": {} }, "modality": { "type": "string", "example": "account" }, "source_display_name": { "type": "string", "example": "Uploaded from CSV" }, "crm_record_url": { "type": "string", "example": "https://sumware.pipedrive.com/organization/7" } } }, "contact_emails": { "type": "array" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "example": "5e66b6381e05b4008c8331b8" }, "name": { "type": "string", "example": "Apollo.io" }, "website_url": { "type": "string", "example": "http://www.apollo.io" }, "blog_url": {}, "angellist_url": {}, "linkedin_url": { "type": "string", "example": "http://www.linkedin.com/company/apolloio" }, "twitter_url": { "type": "string", "example": "https://twitter.com/meetapollo/" }, "facebook_url": { "type": "string", "example": "https://www.facebook.com/MeetApollo" }, "primary_phone": { "type": "object", "properties": {} }, "languages": { "type": "array" }, "alexa_ranking": { "type": "integer", "example": 3514, "default": 0 }, "phone": {}, "linkedin_uid": { "type": "string", "example": "18511550" }, "founded_year": { "type": "integer", "example": 2015, "default": 0 }, "publicly_traded_symbol": {}, "publicly_traded_exchange": {}, "logo_url": { "type": "string", "example": "https://zenprospect-production.s3.amazonaws.com/uploads/pictures/66d13c8d98ec9600013525b8/picture" }, "crunchbase_url": {}, "primary_domain": { "type": "string", "example": "apollo.io" } } }, "intent_strength": {}, "show_intent": { "type": "boolean", "example": false, "default": true }, "phone_numbers": { "type": "array" }, "account_phone_note": {}, "free_domain": { "type": "boolean", "example": false, "default": true }, "is_likely_to_engage": { "type": "boolean", "example": false, "default": true }, "email_domain_catchall": { "type": "boolean", "example": false, "default": true }, "contact_job_change_event": {} } } }, "breadcrumbs": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "example": "Contains Keywords" }, "signal_field_name": { "type": "string", "example": "q_keywords" }, "value": { "type": "string", "example": "Apollo.io" }, "display_name": { "type": "string", "example": "Apollo.io" } } } }, "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": 2, "default": 0 }, "total_entries": { "type": "integer", "example": 178, "default": 0 }, "total_pages": { "type": "integer", "example": 89, "default": 0 } } }, "num_fetch_result": {} } } } } }, "401": { "description": "401", "content": { "text/plain": { "examples": { "Check API key": { "value": "Invalid access credentials." } } } } }, "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": { "message": { "type": "string", "example": "This endpoint is only available to Apollo users on paid plans." } } } } } }, "429": { "description": "429", "content": { "application/json": { "examples": { "Too many requests": { "value": "{\n \"message\": \"The maximum number of api calls allowed for api/v1/contacts/search 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/contacts/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 } ```