There's a new version of the HubSpot API

Check out the new API
View Beta Docs

We're also working on a new documentation website, you're invited to check it out and give us your feedback.

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.

About

Jobs

Learn Inbound

Support

Locations

HubSpot, Inc.
25 First Street, 2nd Floor
Cambridge, MA 02141
European Headquarters
Ground Floor, Two Dockland Central
Guild Street, Dublin 1
Asia/Pacific Office
20 Hunter St, Level 7
Sydney NSW 2000
View our other locations
Example URL to POST to: https://api.hubapi.com/deals/v1/deal Example request JSON: { "associations": { "associatedCompanyIds": [ 8954037 ], "associatedVids": [ 27136 ] }, "properties": [ { "value": "Tim's Newer Deal", "name": "dealname" }, { "value": "appointmentscheduled", "name": "dealstage" }, { "value": "default", "name": "pipeline" }, { "value": "24", "name": "hubspot_owner_id" }, { "value": 1409443200000, "name": "closedate" }, { "value": "60000", "name": "amount" }, { "value": "newbusiness", "name": "dealtype" } ] } Returns a 200 on success with the data for the newly created deal in the response: { "portalId": 62515, "dealId": 151088, "isDeleted": false, "associations": { "associatedVids": [ 27136 ], "associatedCompanyIds": [ 8954037 ], "associatedDealIds": [ ] }, "properties": { "amount": { "value": "60000", "timestamp": 1410381338943, "source": "API", "sourceId": null, "versions": [ { "name": "amount", "value": "60000", "timestamp": 1410381338943, "source": "API", "sourceVid": [ ] } ] }, "dealstage": { "value": "appointmentscheduled", "timestamp": 1410381338943, "source": "API", "sourceId": null, "versions": [ { "name": "dealstage", "value": "appointmentscheduled", "timestamp": 1410381338943, "source": "API", "sourceVid": [ ] } ] }, "pipeline": { "value": "default", "timestamp": 1410381338943, "source": "API", "sourceId": null, "versions": [ { "name": "pipeline", "value": "default", "timestamp": 1410381338943, "source": "API", "sourceVid": [ ] } ] }, "closedate": { "value": "1409443200000", "timestamp": 1410381338943, "source": "API", "sourceId": null, "versions": [ { "name": "closedate", "value": "1409443200000", "timestamp": 1410381338943, "source": "API", "sourceVid": [ ] } ] }, "createdate": { "value": "1410381339020", "timestamp": 1410381339020, "source": null, "sourceId": null, "versions": [ { "name": "createdate", "value": "1410381339020", "timestamp": 1410381339020, "sourceVid": [ ] } ] }, "hubspot_owner_id": { "value": "24", "timestamp": 1410381338943, "source": "API", "sourceId": null, "versions": [ { "name": "hubspot_owner_id", "value": "24", "timestamp": 1410381338943, "source": "API", "sourceVid": [ ] } ] }, "hs_createdate": { "value": "1410381339020", "timestamp": 1410381339020, "source": null, "sourceId": null, "versions": [ { "name": "hs_createdate", "value": "1410381339020", "timestamp": 1410381339020, "sourceVid": [ ] } ] }, "dealtype": { "value": "newbusiness", "timestamp": 1410381338943, "source": "API", "sourceId": null, "versions": [ { "name": "dealtype", "value": "newbusiness", "timestamp": 1410381338943, "source": "API", "sourceVid": [ ] } ] }, "dealname": { "value": "A new Deal", "timestamp": 1410381338943, "source": "API", "sourceId": null, "versions": [ { "name": "dealname", "value": "A new Deal", "timestamp": 1410381338943, "source": "API", "sourceVid": [ ] } ] } } } If there are any issues with the association, you will still create a deal, and still get a 200 response, but the response will include an additional 'associationCreateFailures` field with details about the associations. "associationCreateFailures": [ { "association": { "fromObjectId": 1, "associationType": "COMPANY_TO_DEAL", "toObjectId": 5464192, "timestamp": 1508187481409 }, "failReason": "INVALID_OBJECT_IDS", "message": "COMPANY=1 is not valid" } ],
import requests import json url= 'https://api.hubapi.com/deals/v1/deal?hapikey=demo' headers={} headers["Content-Type"]="application/json" data = json.dumps({ "associations": { "associatedCompanyIds": [ 8954037 ], "associatedVids": [ 27136 ] }, "properties": [ { "value": "Tim's Newer Deal", "name": "dealname" }, { "value": "appointmentscheduled", "name": "dealstage" }, { "value": "default", "name": "pipeline" }, { "value": "24", "name": "hubspot_owner_id" }, { "value": 1409443200000, "name": "closedate" }, { "value": "60000", "name": "amount" }, { "value": "newbusiness", "name": "dealtype" } ] }) r=requests.post(url, headers = headers, data = data) print(r.status_code)
var request = require("request"); var options = { method: 'POST', url: 'https://api.hubapi.com/deals/v1/deal', qs: { hapikey: 'demo' }, headers: { 'Content-Type': 'application/json' }, body: { associations: { associatedCompanyIds: [ 8954037 ], associatedVids: [ 27136 ] }, properties: [ { value: 'Tim\'s Newer Deal', name: 'dealname' }, { value: 'appointmentscheduled', name: 'dealstage' }, { value: 'default', name: 'pipeline' }, { value: '24', name: 'hubspot_owner_id' }, { value: 1409443200000, name: 'closedate' }, { value: '60000', name: 'amount' }, { value: 'newbusiness', name: 'dealtype' } ] }, json: true }; request(options, function (error, response, body) { if (error) throw new Error(error); console.log(body); });