Contacts

Use these endpoints to search and view saved contacts, and create or update contacts individually or in bulk. You can also retrieve contact stages, move contacts between stages, assign or change contact owners, check whether a contact has a likely duplicate, and merge duplicate contacts.

Key concepts

Contacts and people	Contacts are people saved in your team's Apollo workspace. People are individuals in Apollo not yet saved to your workspace. To find people in Apollo's database, use people API search.
Identifying a contact	Search and create responses return a contact `id` that you can pass to view or update the contact. A contact ID identifies your saved contact; a person ID identifies a person in Apollo's database.
Creating and updating	Create adds a new saved contact; update changes an existing one. Deduplication behaves differently across create endpoints. With `run_dedupe` enabled, creating a contact overwrites a matched contact's submitted fields. Bulk create contacts returns matched contacts without changing them, except for placeholder contacts from email imports. Use an update endpoint to change a known contact by ID.
Stages and owners	Stages track a contact's progress through your sales process. Owners are team members responsible for the contact. Use stage IDs and user IDs to set or change these values.

Choose an endpoint

I want to . . .	Use this
Find contacts saved in my team's Apollo workspace	Search for contacts
Retrieve details for a contact whose ID I have	View a contact
Check whether one contact has a likely duplicate	Find a potential duplicate contact
Save one person as a contact	Create a contact
Save up to one hundred people as contacts in one request	Bulk create contacts
Change one contact's details or stage	Update a contact
Change details or owners for multiple contacts	Bulk update contacts
Move multiple contacts to the same stage	Update contact stage for multiple contacts
Assign multiple contacts to the same owner	Update contact owner for multiple contacts
Merge up to 100 groups of duplicate contacts in one request	Merge duplicate contacts (beta)
Check whether a background merge has finished	View a contact merge job (beta)
Retrieve available contact stages and their IDs	List contact stages

Save enriched people as contacts

Save the people you've enriched as contacts your team can manage in Apollo.

Retrieve person details with people enrichment or bulk people enrichment. If you already have the details in your system, you can skip this step.
Pass the person details you want to save, such as names, email addresses, and company information, as objects in the contacts array of bulk create contacts. Include up to 100 contacts per request and set run_dedupe to true to match against existing contacts.
Retain the contact IDs returned for newly created and existing contacts. Use these IDs when you need to view or update the saved contacts.

Matched contacts are returned in existing_contacts without changes, except for placeholder contacts from email imports. To apply new values to an existing contact, use an update endpoint.

Learn more: Use the bulk create contacts reference to explore contact fields and deduplication behavior.

Update contact stages and owners

Move a group of saved contacts to a new stage and assign them to the team member responsible for the next step.

Call search for contacts to identify the contacts you want to change. Retain each contact's id.
Call list contact stages and retain the ID of the destination stage.
Pass the contact IDs as contact_ids[] and the stage ID as contact_stage_id to update contact stage for multiple contacts.
Call get a list of users and retain the ID of the intended owner.
Pass the same contact IDs as contact_ids[] and the user ID as owner_id to update contact owner for multiple contacts.

If you also need to change contact details or custom fields, use bulk update contacts. Requests with more than 100 contacts are processed asynchronously.

Learn more: Use the update contact stage for multiple contacts and update contact owner for multiple contacts references to dig in to the workflow.

Find and merge duplicate contacts

Clean up your workspace by merging contacts that are copies of the same person.

Call find a potential duplicate contact for each contact you want to check. When it returns a match, compare the two contacts, and retain both IDs if they are the same person.
Group the IDs by the contact you want to keep. Pass up to 100 groups in the contacts array of merge duplicate contacts, with up to 10 duplicates per group. Each contact can appear only once in the request.
If the request had 2 or more groups, retain the deduplication_job_id and call view a contact merge job until status is succeeded or failed.

Merging permanently deletes the duplicate contacts, so review each pair before you merge.

Learn more: Use the merge duplicate contacts reference to explore merge limits and errors.