Using the Deals API

The Deals API, along with the Companies API, has been exposed to allow for easy integration with the HubSpot CRM objects. A couple of use cases the API can support:

  • Creating a client in a project management system when a deal is marked as closed won.
  • Syncing Deal data with a legacy CRM.
  • Executing advanced revenue reporting in a 3rd party reporting platform.

Associations between Deals and other objects

The deal in HubSpot is not a standalone object in HubSpot - much of the value in using the API comes in how deals relate to other objects in HubSpot.

The way to determine deal associations are with fields will be returned to you when you request a deal: associatedCompanyIds returns the id of the company associated with the deal, and associatedVids returns the ids of the contacts associated with the deal.You can then perform lookups on either the contacts or the company.

The properties are also important for setting associations between the deals you are creating and existing objects in HubSpot. For more on how to associate objects with a deal on it's creation, see the documentation on creating a deal.

An important difference between the Deals API and the Companies API is that deals possess a one:many relationship with contacts and companies. This is especially important for any integration that involves extrapolating data from Deals and adding them to a contact or company, either in HubSpot or in another system.

The Deals UI

Though deals is primarily useful for the HubSpot CRM, you can reveal some Deals UI in the marketing product, which is particularly useful for segmentation on deal data or for revenue reporting inside of HubSpot Marketing. To do so, log in (or instruct users to log in) to a HubSpot portal. Then go to Contacts > Contacts Settings > Display Options. Under the Display Deal Information section, select Yes.

Docs for this section or API