Workspace CRM contacts — create, update, search, stages and ownership. 10 operation(s) from the published Apollo OpenAPI.
openapi: 3.1.0
info:
title: Apollo.io Contacts 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: Contacts
description: Create, update, and search the people your team saves 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:
/contacts:
post:
summary: Create a Contact
description: '## Endpoint essentials
**API key access:** `api/v1/contacts/create` or `Master API key`
**OAuth scopes:** `contact_write`
**Credit usage:** `0 credits` — [Learn more about API pricing and credits](https://docs.apollo.io/docs/api-pricing).
<a href="https://knowledge.apollo.io/hc/en-us/articles/5995459280525-View-and-Edit-Contacts" target="_blank">Contacts</a>
are people saved in Apollo.<br><br>Use the Create a Contact endpoint to add a new contact to your
team''s Apollo account.<br><br>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 <code>run_dedupe</code> parameter
to <code>true</code>. <br><br>To update an existing contact, use the <a href="https://docs.apollo.io/reference/update-a-contact">Update
a Contact endpoint</a> 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.'
tags:
- Contacts
operationId: create-a-contact
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
first_name:
type: string
description: 'The first name of the contact you want to create. Example: `Tim`'
last_name:
type: string
description: 'The last name of the contact you want to create. Example: `Zheng`'
organization_name:
type: string
description: 'The name of the contact''s employer (company). Example: `apollo`'
title:
type: string
description: 'The current job title that the contact holds. Example: `senior research
analyst`'
account_id:
type: string
description: 'The Apollo ID for the account. Example: `63f53afe4ceeca00016bdd2f`'
email:
type: string
description: 'The email address of the contact. Example: `example@email.com`'
website_url:
type: string
description: 'The corporate website URL. Example: `https://www.apollo.io/`'
label_names:
type: array
description: Lists to which the contact belongs.
items:
type: string
contact_stage_id:
type: string
description: 'The Apollo ID for the contact stage. Example: `6095a710bd01d100a506d4ae`'
present_raw_address:
type: string
description: 'The personal location for the contact. Example: `Atlanta, United States`'
direct_phone:
type: string
description: 'The primary phone number. Example: `555-555-0133`'
corporate_phone:
type: string
description: 'The work/office phone number. Example: `+44 7700 900852`'
mobile_phone:
type: string
description: 'The mobile phone number. Example: `555-555-0133`'
home_phone:
type: string
description: 'The home phone number. Example: `555-555-0133`'
other_phone:
type: string
description: 'Alternative phone number. Example: `555-555-0133`'
typed_custom_fields:
type: object
description: "Add information to <a href=\"https://knowledge.apollo.io/hc/en-us/articles/4412498825869-Create-Custom-Contact-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'
run_dedupe:
type: boolean
description: 'Set to `true` to match against your existing contacts instead of always
creating a new one. The default value is `false`. <br><br>When a match is found, Apollo
**updates that existing contact in place** with the values you sent and returns it
— the `id` in the response belongs to the pre-existing contact, not a new record.
Fields you send overwrite the stored values, fields you omit are left untouched, and
sending an empty value clears the field. <br><br>Matching is checked in order: `id`,
CRM identifiers, `person_id`, `email` (against the contact''s primary and additional
emails), then name plus company. Because of the last rule, a contact can be matched
and updated even when the email differs. <br><br>When deduplication is enabled, performance
may be slightly impacted due to the additional matching checks. See the endpoint description
for full details.'
default: false
examples:
Create contact without deduplication:
summary: Create a new contact without deduplication (default behavior)
value:
first_name: John
last_name: Smith
email: john.smith@example.com
organization_name: Example Corp
title: Software Engineer
Create contact with deduplication:
summary: Create a new contact with deduplication enabled
value:
first_name: Jane
last_name: Doe
email: jane.doe@example.com
organization_name: Example Corp
title: Product Manager
run_dedupe: true
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
contact:
contact_roles: []
id: 66e34b81740c50074e3d1bd4
first_name: Fyodor
last_name: Dostoevsky
name: Fyodor Dostoevsky
linkedin_url: null
title: Chief Fiction 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: St. Petersburg, Russia
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-12T20:13:53.207Z'
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: '+15555550149'
merged_crm_ids: null
updated_at: '2024-09-12T20:13:53.331Z'
queued_for_crm_push: true
suggested_from_rule_engine_config_id: null
email_unsubscribed: null
label_ids:
- 66e34b81740c50074e3d1bd0
- 66e34b81740c50074e3d1bd1
- 66e34b81740c50074e3d1bd2
- 66e34b81740c50074e3d1bd3
has_pending_email_arcgate_request: false
has_email_arcgate_request: false
existence_level: full
email: fyodo@apollo.io
email_from_customer: true
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: []
contact_emails: []
next_contact_id: null
time_zone: Asia/Krasnoyarsk
city: Saint Petersburg
state: Saint Petersburg
country: Russia
show_intent: false
phone_numbers:
- raw_number: 555-555-0149
sanitized_number: '+15555550149'
type: work_direct
position: 0
status: no_status
dnc_status: null
dnc_other_info: null
dialer_flags: null
account_phone_note: null
free_domain: false
is_likely_to_engage: false
email_domain_catchall: false
typed_custom_fields:
5b75f1c11dc2727d43ae3bb9: test
5c4296857f799409361890ea: test2
labels:
- id: 66e34b81740c50074e3d1bd2
modality: contacts
cached_count: 0
name: typewriter
created_at: '2024-09-12T20:13:53.119Z'
updated_at: '2024-09-12T20:13:53.279Z'
user_id: 60affe7d6e270a00f5db6fe4
- id: 66e34b81740c50074e3d1bd1
modality: contacts
cached_count: 0
name: fiction
created_at: '2024-09-12T20:13:53.107Z'
updated_at: '2024-09-12T20:13:53.258Z'
user_id: 60affe7d6e270a00f5db6fe4
- id: 66e34b81740c50074e3d1bd0
modality: contacts
cached_count: 0
name: writer
created_at: '2024-09-12T20:13:53.093Z'
updated_at: '2024-09-12T20:13:53.308Z'
user_id: 60affe7d6e270a00f5db6fe4
- id: 66e34b81740c50074e3d1bd3
modality: contacts
cached_count: 0
name: microsoft word
created_at: '2024-09-12T20:13:53.132Z'
updated_at: '2024-09-12T20:13:53.313Z'
user_id: 60affe7d6e270a00f5db6fe4
Deduplication-Result:
summary: Contact creation with deduplication enabled - existing contact found
value:
contact:
contact_roles: []
id: 66e34b81740c50074e3d1bd4
first_name: Jane
last_name: Doe
name: Jane Doe
linkedin_url: null
title: Product Manager
contact_stage_id: 6095a710bd01d100a506d4ae
owner_id: 60affe7d6e270a00f5db6fe4
creator_id: 60affe7d6e270a00f5db6fe4
person_id: null
email_needs_tickling: null
organization_name: Example Corp
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-12T20:13:53.207Z'
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-12T20:13:53.331Z'
queued_for_crm_push: false
suggested_from_rule_engine_config_id: null
email_unsubscribed: null
label_ids: []
has_pending_email_arcgate_request: false
has_email_arcgate_request: false
existence_level: full
email: jane.doe@example.com
email_from_customer: true
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: []
contact_emails: []
next_contact_id: null
time_zone: null
city: null
state: null
country: null
show_intent: false
phone_numbers: []
account_phone_note: null
free_domain: false
is_likely_to_engage: false
email_domain_catchall: false
typed_custom_fields: {}
labels: []
dedupe_result:
found_existing: true
match_reason: email_match
existing_contact_id: 66e34b81740c50074e3d1bd4
schema:
type: object
properties:
contact:
type: object
properties:
contact_roles:
type: array
id:
type: string
example: 66e34b81740c50074e3d1bd4
first_name:
type: string
example: Fyodor
last_name:
type: string
example: Dostoevsky
name:
type: string
example: Fyodor Dostoevsky
linkedin_url: {}
title:
type: string
example: Chief Fiction 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:
type: string
example: St. Petersburg, Russia
linkedin_uid: {}
extrapolated_email_confidence:
type: number
nullable: true
salesforce_id: {}
salesforce_lead_id: {}
salesforce_contact_id: {}
salesforce_account_id: {}
crm_owner_id: {}
created_at:
type: string
example: '2024-09-12T20:13:53.207Z'
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:
type: string
example: '+15555550149'
merged_crm_ids: {}
updated_at:
type: string
example: '2024-09-12T20:13:53.331Z'
queued_for_crm_push:
type: boolean
example: true
default: true
suggested_from_rule_engine_config_id: {}
email_unsubscribed: {}
label_ids:
type: array
items:
type: string
example: 66e34b81740c50074e3d1bd0
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: fyodo@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.marcus.hale@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:
# --- truncated at 32 KB (201 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apollo-io/refs/heads/main/openapi/apollo-io-contacts-api-openapi.yml