A deal stores data about an ongoing transaction. The deals endpoints allow you to manage this data and sync it between HubSpot and other systems.
POST
request to /crm/v3/objects/deals
.
In the request body, 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).
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.
associations
object. For example, to associate a new deal with an existing contact and company, your request would look like the following:
associations
object, you should include the following:
Parameter | Description |
---|---|
to | The record or activity you want to associate with the deal, specified by its unique id value. |
types | The type of the association between the deal and the record/activity. Include the associationCategory and associationTypeId . Default association type IDs are listed here, or you can retrieve the value for custom association types (i.e. labels) via the associations API. |
GET
request to /crm/v3/objects/deals/{dealId}
.GET
request to /crm/v3/objects/deals
.Parameter | Description |
---|---|
properties | A comma separated list of the properties to be returned in the response. If a requested property isn’t defined, it won’t be included in the response. If a requested property is defined but a deal doesn’t have a value, it will be returned as null . |
propertiesWithHistory | A comma separated list of the current and historical properties to be returned in the response. If a requested property isn’t defined, it won’t be included in the response. If a requested property is defined but a deal doesn’t have a value, it will be returned as null . |
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. |
POST
request to crm/v3/objects/deals/batch/read
.
idProperty
parameter in the request body to specify the property name. Then, in the inputs
array, include the values of the unique identifier property rather than the deal ID.propertiesWithHistory
parameter in the request body, as shown below.
PATCH
request to /crm/v3/objects/deals/{dealId}
, and include the data you want to update.POST
request to /crm/v3/objects/deals/batch/update
. In the request body, include an array with the identifiers for the deals and the properties you want to update.PUT
request to /crm/v3/objects/deals/{dealId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}
.
associationTypeId
value, refer to this list of default values, or make a GET
request to /crm/v4/associations/{fromObjectType}/{toObjectType}/labels
.DELETE
request to the following URL: /crm/v3/objects/deals/{dealId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}
.
hs_pinned_engagement_id
parameter in the request. For the value of the parameter, specify the ID of the activity to pin, which can be retrieved via the engagements APIs. You can pin one activity per record, and the activity must already be associated with the deal prior to pinning.
To set or update a deal’s pinned activity, your request could look like:
DELETE
request to /crm/v3/objects/deals/{dealId}
. No request body is needed for this request.POST
request to /crm/v3/objects/deals/batch/archive
. In the request body, include the deal ID values as the id
inputs, as shown in the example request body below.