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.

Deals API Overview

There's a new version of the Deals API. We've redesigned our deals API and it is out now in developer preview. Check out the new API

In HubSpot, a deal represents an ongoing transaction that a sales team is pursuing with a contact or company. It’s tracked through pipeline stages until won or lost. Deals, along with companies, contacts, tickets, line items, products, and quotes, are an object in the HubSpot CRM. The Deals API allows you to manage this data and sync it between HubSpot and other systems.

What's a use case for this API? Your retail business uses both HubSpot and another CRM. Your business development team uses HubSpot to qualify leads when a contact enrolled in your loyalty program makes a transaction. They pass these qualified leads to the field sales team by syncing HubSpot to their CRM using the Deals API. 

Other use cases include creating a client in a project management system when a deal is marked closed won or executing advanced revenue reporting in a third-party platform.

Deal properties

Deals have several default properties. They also support custom properties, which store data tailored for your integration. Custom properties can be managed through the CRM Object Properties API

The dealstage property is required when creating a deal. While not required, you should also always specify the pipeline property, especially for accounts with multiple pipelines. If it isn't specified, the default pipeline will be used. Learn more about creating deals here.

Associations between deals and other objects

Deals can be associated with contacts, companies, engagements, line items, and tickets. It's important to note that they have a one:many relationship with contacts and companies. 

Response details

When you request a deal, the returned fields will display its associations. For example, associatedCompanyIds returns the associated company id, and associatedVids returns the associated contact ids. You can then perform lookups on either the contacts or the company.

In general, deal data will be returned in the format shown below. With the exception of updating deal properties, this data will be read-only. See the Contacts API Overview for the values found in the property source field.

{
  "portalId": 62515,
  // Integer; The Portal ID (Hub ID) that the record belongs to.
  "dealId": 92606338,
  // Integer; The internal ID of the deal record
  "isDeleted": false,
  // Boolean; Whether or not the record is deleted. In practice this will always be false as deleted records will not appear in the API.
  "associations": {
  // A set of lists indicating which records the deal is associated with.
    "associatedVids": [
    // A list of integers, each one will be the vid of a contact record. 
      3065624
    ],
    "associatedCompanyIds": [
    // A list of integers, each one represents the companyId of a company record.
    // Deals can only be associated with a single company, so there will only be up to one item in the list.
      184896670
    ],
    "associatedDealIds": []
    // Deals can't be associated with other deals, so this will be an empty list.
  },
  "properties": {
  // A set of objects representing the the data for the properties set for the deal.
  // Only populated properties will be included for the record; properties that have never been set for the record will not be included.
    "dealname": {
    // String; The internal name of the property
      "value": "Example Deal",
      // String; The current value of the property.
      "timestamp": 1488839786098,
      // Integer; a Unix timestamp (in milliseconds) of the time the current value was set
      "source": "CRM_UI",
      // String; The method by which the value was set. See the contacts overview page (linked above) for more details
      "sourceId": "user@hubspot.com",
      // String or null; Additional details about the source.
      // May not be set for all source types
      "versions": [
      // A list of previous versions of the property value
      // Each entry represents a change to the value of the property
      // Entries are sorted in reverse chronological order, with the current version as the first entry. 
        {
          "name": "dealname",
          // String; The internal name of the property
          "value": "Example Deal",
          // String; the value of the property
          "timestamp": 1488839786098,
          // Integer; a Unix timestamp (in milliseconds) of the time that this value was set
          "source": "CRM_UI",
          // String; The method by which this version was set. See the contacts overview page (linked above) for more details
          "sourceId": "user@hubspot.com",
          // String or null; Additional details for the source of the change.
          // This may not be set for all source types
          "sourceVid": []
          // If the value was changed as the result of a change to a related contact, this will contain a list of vids for those related contacts.
        }
      ]
    },
    "amount": {
      "value": "50",
      "timestamp": 1488839786098,
      "source": "CRM_UI",
      "sourceId": "user@hubspot.com",
      "versions": [
        {
          "name": "amount",
          "value": "50",
          "timestamp": 1488839786098,
          "sourceId": "user@hubspot.com",
          "source": "CRM_UI",
          "sourceVid": []
        }
      ]
    }
  }
}

Docs for this section or API