Create a Deal

POST /deals/v1/deal/

Method Details

HTTP Methods:


Content Type:


Response Format:


Requires Authentication?


Rate Limited?






For a given portal, create a deal. This is particularly useful if you're integrating with a CRM or another application that has a similar notion of a deal.

Note that you can create associations between Deals and Contacts and Companies much the same way you create an association between Companies and Contacts. Associating your Deal with Contacts and Companies is not required (i.e. you can create an orphaned deal). You can also pass any custom property value you want to the deals API, so long as you've created the property first.

The dealstage property is required when creating a deal. 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 dealstages through the Deals 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 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.

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

If the object IDs in the associations data are invalid, the deal will still be created, and you will still get a 200 response with the details of the created deal, but you'll receive the additional associationCreateFailures field in the response, which will include details about those association faliures. See the example associationCreateFailures at the bottom of the example JSON to the right.