Using the Deals API

The Deals API, along with the Companies API, has been exposed to allow for easy integration with the HubSpot CRM objects. A couple of use cases the API can support:

  • Creating a client in a project management system when a deal is marked as closed won.
  • Syncing Deal data with a legacy CRM.
  • Executing advanced revenue reporting in a 3rd party reporting platform.

Associations between Deals and other objects

The deal in HubSpot is not a standalone object in HubSpot - much of the value in using the API comes in how deals relate to other objects in HubSpot.

The way to determine deal associations are with fields will be returned to you when you request a deal: associatedCompanyIds returns the id of the company associated with the deal, and associatedVids returns the ids of the contacts associated with the deal.You can then perform lookups on either the contacts or the company.

The properties are also important for setting associations between the deals you are creating and existing objects in HubSpot. For more on how to associate objects with a deal on it's creation, see the documentation on creating a deal.

An important difference between the Deals API and the Companies API is that deals possess a one:many relationship with contacts and companies. This is especially important for any integration that involves extrapolating data from Deals and adding them to a contact or company, either in HubSpot or in another system.

The Deals UI

Though deals is primarily useful for the HubSpot CRM, you can reveal some Deals UI in the marketing product, which is particularly useful for segmentation on deal data or for revenue reporting inside of HubSpot Marketing. To do so, log in (or instruct users to log in) to a HubSpot portal. Then go to Contacts > Contacts Settings > Display Options. Under the Display Deal Information section, select Yes.

Individual deal records will have the following format.  With the exception of being able to update the properties of a deal. this data will be read-only. See the contacts overview for the values used for 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": []
        }
      ]
    }
  },
  "imports": [
  // For deals that have been imported, this will contain a list of import objects
  // For deals, this will have at most a single entry, since deal imports will not deduplicate records.
    {
      "importKey": "15eae328-4462-4644-ac03-c23421af51a1",
      // String; an internal reference to a specific import
      "importDate": 1489010292230
      // Integer; a Unix timestamp (in milliseconds) of when the import occurred.
    }
  ]
}

Docs for this section or API