Deals

Use these endpoints to list and view deals, and create or update sales opportunities in your team's Apollo workspace. You can also retrieve deal stages, change deal owners, and find deals associated with a contact.

Key concepts

Deals	Deals track sales opportunities in your team's Apollo workspace. Deal details can include a name, monetary value, estimated close date, owner, stage, and associated account.
Identifying a deal	List and create responses return a deal `id` that you can pass to view or update the deal. These endpoints use `opportunity_id` for the deal ID and `opportunity_stage_id` for the stage ID.
Stages and owners	Stages track a deal's progress through your sales process. Owners are team members responsible for the deal. Use stage IDs and user IDs to set these values when creating or updating deals.
Associated deals	A contact can be associated with deals. Use the contact's ID to retrieve those deals. Viewing associated deals returns existing associations; it doesn't create or change them.

Choose an endpoint

I want to . . .	Use this
Retrieve deals in my team's Apollo workspace	List all deals
Retrieve details for a deal whose ID I have	View deal
Create a new sales opportunity	Create deal
Change a deal's details, stage, or owner	Update deal
Find deals associated with a specific contact	View associated deals
Retrieve available deal stages and their IDs	List deal stages

Example workflows

Create and assign a sales opportunity
Update an opportunity associated with a contact

Create and assign a sales opportunity

Create a deal with the stage and owner your team needs to manage the opportunity.

Call list deal stages and retain the ID of the stage where the deal should start.
Call get a list of users and retain the ID of the intended owner.
Call create deal with a name, the stage ID as opportunity_stage_id, and the user ID as owner_id. Include other details you want to track, such as amount and closed_date.
Retain the returned deal id to view or update the deal later.

Enter the amount without commas or currency symbols. The currency comes from your workspace settings. Format the estimated close date as YYYY-MM-DD.

Learn more: Use the create deal reference to explore the deal fields available.

Update an opportunity associated with a contact

Find the opportunity connected to a contact, then update it as the sales conversation progresses.

Call search for contacts to find the saved contact and retain their id.
Pass the contact ID to view associated deals. Review the returned deals and retain the id of the deal you want to change.
If you're changing the stage, call list deal stages and retain the ID of the destination stage.
Pass the deal ID as opportunity_id to update deal. Include the new opportunity_stage_id or other changes, such as an updated amount or estimated close date.

If you already have the deal ID, you can skip the contact lookup. View associated deals returns an empty array when the contact has no associated deals or the contact ID isn't recognized.

Learn more: Use the view associated deals and update deal references to dig in to the workflow.