There's a new version of the HubSpot API

As of November 30, 2022, HubSpot API keys are no longer a supported authentication method for accessing HubSpot APIs. Instead, you should use a private app access token or OAuth to authenticate API calls. Learn more about this change and how to migrate an API key integration to use a private app instead.

Create a deal

Last updated May 12, 2023

POST /deals/v1/deal/

Method Details

HTTP Methods:

POST

Content Type:

application/json

Response Format:

json

Requires Authentication?

Yes

Rate Limited?

Yes

Headers

User-Agent

Products:

CRM

Required Scope:

crm.objects.deals.write

The create a deal endpoint is used to create and track deals in HubSpot. It also allows you to connect HubSpot with an external CRM or other sales management software.

What's a use case for this endpoint? Your company uses HubSpot along with an external CRM and website hosting platform. Your sales team uses the create a deal endpoint to make sure that certain sales activity in the CRM will automatically create a deal in HubSpot. Additionally, when a contact submits a sales qualification form on your website, this endpoint creates a deal in HubSpot.

Associations

You can (but are not required to) create associations between deals and other CRM objects the same way you would create an association between companies and contacts

Properties

You can pass any custom property value to the Deals API as long as you create the property first.

While the dealstage property and pipeline property are not required, it is recommended to specify both, especially on accounts with multiple pipelines. If left unspecified, the default pipeline is assumed. You can manage pipelines and dealstages through the CRM Pipelines API.

Response details

This endpoint returns a 200 response when a new deal is successfully created. Otherwise, you'll get a 4xx error with failure details in the response body.

If the object IDs in the associations data are invalid, the deal will still be created and you will get a 200 response with appropriate details. However, you'll also receive the additional associationCreateFailures field in the response, which will include details about those association failures. (See the example associationCreateFailures to the right.)

Required Parameters How to use Description
OAuth access token or private app access token Authorization: Bearer {token} header Used to authenticate the request. Please see this page for more details about authentication.
Deal properties "properties": []
Used in the request body
A list of property names, and the value you want to set for the property. See the example request for details.

Optional Parameters How to use Description
Associated records "associations": {}
Used in the request body
A set of IDs for records that the new deal should be associated with. Deals can be associated with a single company (by companyId) and any number of contacts (by vid). See the example request for details an example of associating the record with a company and a single contact.
Pipeline pipeline
Used in the properties list
If the pipeline property is not specified, the default pipeline is assumed. However, it is recommended to always specify the pipeline, especially on accounts with multiple pipelines. You can manage pipelines and stages through the CRM Pipelines API.
Deal stage dealstage
Used in the properties list
The dealstage is not required when creating a deal. However, it is strongly recommended that a dealstage be specified. See the CRM Pipelines API for details on managing pipelines and stages.