Contacts are people saved in Apollo.

Use the Create a Contact endpoint to add a new contact to your team's Apollo account.

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 run_dedupe parameter to true.

To update an existing contact, use the Update a Contact endpoint 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 with its id — explicit, with no matching involved.

Bulk Create Contacts differs: matched contacts are returned in existing_contacts without being modified.