Create a deal

Last updated March 25, 2020

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:

contacts

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.

The dealstage property is required when creating a deal. It's also recommended (though not required) that you always specify the pipeline property, 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 API Key Authorization: Bearer {token} header
or hapikey={key} query parameter.
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.