Create a deal

Last updated November 22, 2019

POST /deals/v1/deal/

Method Details

HTTP Methods:


Content Type:


Response Format:


Requires Authentication?


Rate Limited?






Required Scope:


This endpoint allows you to create a deal. It's useful for integrating with a CRM or another application that has a similar notion of a deal.


You can create associations between deals and contacts or companies. The process is the same as when creating associations between companies and contacts. Associating your deal with contacts and companies isn't required, so you can choose to create an orphaned deal.

Property values

You can pass any custom property value to the deals API as long as you've already created the property

The dealstage property is required when creating a deal. While not required, you should always specify the pipeline property, especially for an account with multiple pipelines. If it isn't specified, the default pipeline will be used. You can manage pipelines and dealstages through the CRM Pipelines API.


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 each property. See the example request for details.
Deal stage dealstage
Used in the request body in the properties list
The dealstage is required when creating a deal. See the CRM Pipelines API for details on managing pipelines and stages.

Optional parameters How to use Description
Associated records "associations": {}
Used in the request body
A set of IDs for records a 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 on associating a 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 portals with multiple pipelines. You can manage pipelines and stages through the CRM Pipelines API.

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

If the object IDs in the associations data are invalid, the deal will still be created. You will still get a 200 response with details of the created deal, but it will also include the associationCreateFailures field which will have information about those association failures. See the example associationCreateFailures at the bottom of the example JSON to the right.