Deals

OverviewEndpoints

In HubSpot, deals represent transactions with contacts or companies. Deals are tracked through your sales process in pipeline stages until they're won or lost. The deals endpoints allow you to manage create and manage deal records, as well as sync deal data between HubSpot and other systems. 

Learn more about objects, records, properties, and associations APIs in the Understanding the CRM guide. For more general information about objects and records in HubSpot, learn how to manage your CRM database.

Create deals

To create new deals, make a POST request to /crm/v3/objects/deals.

In your request, include your deal data in a properties object. You can also add an associations object to associate your new deal with existing records (e.g., contacts, companies), or activities (e.g., meetings, notes).

Properties

Deal details are stored in deal properties. There are default HubSpot deal properties, but you can also create custom properties.

When creating a new deal, you should include the following properties in your request: dealname, dealstage and if you have multiple pipelines, pipeline. If a pipeline isn't specified, the default pipeline will be used. 

To view all available properties, you can retrieve a list of your account's deal properties by making a GET request to /crm/v3/properties/deals. Learn more about the the properties API.

Please note: you must use the internal ID of a deal stage or pipeline when creating a deal via the API. The internal ID will also be returned when you retrieve deals via the API. You can find a deal stage's or pipeline's internal ID in your deal pipeline settings.

For example, to create a new deal, your request may look similar to the following:

///Example request body { "properties": { "amount": "1500.00", "closedate": "2019-12-07T16:50:06.678Z", "dealname": "New deal", "pipeline": "default", "dealstage": "contractsent", "hubspot_owner_id": "910901" } }

Associations

When creating a new deal, you can also associate the deal with existing records or activities. In the associations object, include the following fields:

Use this table to describe parameters / fields
ParameterDescription
toObjectId

The ID of the record or activity that you want to associate the deal with.

associationTypeId

A unique identifier to indicate the association type between the deal and the other object or activity. Default association types are listed here, or you can retrieve the value by making a GET request to /crm/v4/associations/{fromObjectType}/{toObjectType}/labels. Learn more about the associations API.

You can also include the label field to assign a defined association label that describes the association. Learn more about associating records via the associations API.

For example, to associate a new deal with an existing contact and company, your request would look like the following:

///Example request body { "properties": { "amount": "1500.00", "closedate": "2019-12-07T16:50:06.678Z", "dealname": "New deal", "pipeline": "default", "dealstage": "contractsent", "hubspot_owner_id": "910901" }, "associations": [ { "to": { "id": 201 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 5 } ] }, { "to": { "id": 301 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 3 } ] }] }

Retrieve deals

You can retrieve deals individually or in batches.

  • To retrieve an individual deal, make a GET request to /crm/v3/objects/deals/{dealId}.
  • To request a list of all deals, make a GET request to /crm/v3/objects/deals.
  • To retrieve a batch of specific deals by record ID or a custom unique identifier property, make a POST request to crm/v3/objects/deals/batch/read.
For these endpoints, you can include the following query parameters in the request URL:
Use this table to describe parameters / fields
ParameterDescription
properties
A comma separated list of the properties to be returned in the response. If the requested deal doesn't have a value for a property, it will not appear in the response.
associations

A comma separated list of objects to retrieve associated IDs for. Any specified associations that don't exist will not be returned in the response. Learn more about the associations API.

For the batch read endpoint, you can also use the optional idProperty parameter to retrieve deals by a custom unique identifier property. By default, the id values in the request refer to the record ID (hs_object_id), so the idProperty parameter is not required when retrieving by record ID. To use a custom unique value property to retrieve deals, you must include the idProperty parameter.

For example, to retrieve a batch of deals, your request could look like either of the following:

///Example request body with record ID { "properties": [ "dealname", "dealstage", "pipeline" ], "inputs": [ { "id": "7891023" }, { "id": "987654" } ] }
///Example request body with a unique value property { "properties": [ "dealname", "dealstage", "pipeline" ], "idProperty": "uniqueordernumber", "inputs": [ { "id": "0001111" }, { "id": "0001112" } ] }

Update deals

You can update deals individually or in batches. For existing deals, the deal ID is a unique value that you can use to update the deal via API.

To update an individual deal by its deal ID, make a PATCH request to /crm/v3/objects/deals/{dealId}, and include the data you want to update.

Associate existing deals with records or activities

To associate a deal with other CRM records or an activity, make a PUT request to  /crm/v3/objects/deals/{dealId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}. 

To retrieve the associationTypeId value, refer to this list of default values, or make a GET request to /crm/v4/associations/{fromObjectType}/{toObjectType}/labels.

Learn more about associating records with the associations API.

Remove an association

To remove an association between a deal and a record or activity, make a DELETE request to the following URL: /crm/v3/objects/deals/{dealId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}.

Delete deals

You can delete deals individually or in batches, which will add the deal to the recycling bin in HubSpot. You can later restore the deal within HubSpot.

To delete an individual deal by its ID, make a DELETE request to /crm/v3/objects/deals/{dealId}.

Learn more about batch deleting deals on the Endpoints tab at the top of this article.

Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.