Deals (Opportunity-type Objects)

The deal object is not a standalone object - much of the value in using the API is in how deals relate to other HubSpot objects. The way to determine deal associations are with fields will be returned to you when you request a deal: ‘associatedCompanyIds’ contains 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 relevant contacts or company. The properties are also important for creating associations between the deals you are creating and existing objects in HubSpot.

An important difference between the deals object and the companies object 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.

Keeping Your Database Updated

If any users are intending on using the HubSpot CRM as well as your bespoke CRM, you’ll want to ensure that your database contains the latest information. However, if the HubSpot CRM (or any other external system syncing with your instance of HubSpot) is not going to be used to create or modify deal-type objects, you may not need to implement functions to keep this data up to date, as your database will always be authoritative from the HubSpot perspective.

Poll the ‘Get Recently Created Deals’ and the ‘Get Recently Modified Deals‘ endpoints every five minutes for any new or updated deals from HubSpot, and then update your internal database with the new data. We recommend keeping a timestamp of the last update to any given deal property within your internal system, and then comparing that with a timestamp taken whenever an update API call is made to HubSpot to ensure that your internal database always contains the latest data.

In the event that your system contains more recent data than HubSpot, use the ‘Update a Deal‘ endpoint outlined below to update the data.

Creating a New Deal

To create a new deal in HubSpot, use the ‘Create a Deal‘ endpoint. This will return the deal as a JSON object, containing the ‘dealId’, which is the unique identifier of the deal within HubSpot. We recommend you store this value together with the deal within your own database. While you can create an ‘orphan’ deal with no associations to other objects, normal process flow will be to associate relevant companies / contacts at deal creation time. You can do this by including the relevant ‘companyId’ and ‘vid’ with the call.

Updating an Existing Deal

To update a deal, use the ‘Update a Deal‘ endpoint, passing the relevant ‘dealId’ within the destination of the call, and the updated deal property in JSON within the body. This will return the deal in JSON format.
You can also store custom data on the Deals object by creating a custom deal property and then creating / updating the relevant deal objects, populating the created fields with the desired data.

Deleting an Existing Deal

You can delete an engagement by using the ‘Delete a Deal’ endpoint, passing the relevant ‘dealId’ with the call. Successful deletion of the deal will be indicated by the return of HTTP status 200 with the response, which will be a JSON object with two fields; 'deleted', which will return true when the deal has been successfully deleted, as well as the dealId of the deleted deal.

Associating an Existing Deal

You can associate a deal object with multiple contacts and companies. Simply call the ‘Associate a deal with a contact or company’ endpoint, specifying the type of object you’re wanting to associate, as well as the ID of the relevant object together with the call.
For example:


A successful call will return a HTTP 204 response.