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, and assign or change contact owners.

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
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
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.