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.

Companies API Overview

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

In HubSpot, company records store information about a business or organization. The Companies API allows you to manage this data and sync it between HubSpot and other systems.

Use case for this API: Your organization is using HubSpot and another ERP system. When a company is delinquent on payments, you want to make sure their company record is updated HubSpot. To automatically sync this data, you integrate the two systems using the Companies API. These updates can then be used to pause marketing communications or notify a sales owner in HubSpot.

Companies, along with contacts, deals, tickets, line items, products, and quotes, are objects in the HubSpot CRM. For a more detailed look at all HubSpot record types, you can use our Guide to Records.

Company properties

Details for company records are primarily stored in company properties. In addition to several default properties, HubSpot users can store any necessary custom data by creating custom company properties. Use the Company Properties API to view and manage properties.

Associations between companies and other objects

Companies have a one-to-many relationship with contacts, tickets, and deals (multiple contacts, tickets, and deals can be associated with a single company, but only one company can be associated with a single contact, ticket, or deal). Any contacts or deals associated with the company will appear as related items when viewing the company in HubSpot. Company records can be associated with contacts using the CRM Associations API.  For visual representation of how objects relate to one another in HubSpot, see this ERD.

Response details

Responses for individual company records will have the following format, and with the exception of updating the properties of a company, this data will be read-only. See the Contacts Overview for the values used for the property source field. 

{
  "portalId": 62515,
  // Integer; The Hub ID that the company belongs to.
  "companyId": 184896670,
  // Integer; The unique ID of the company 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.
  "properties": {
  // A set of objects representing the values for the set company properties.
  // Only populated properties will be included; properties that have never been set for the record will not be included.
    "country": {
    // String; The internal name of the property.
      "value": "United States",
      // String; The current value of the property.
      "timestamp": 1457708103906,
      // Integer; A Unix timestamp (in milliseconds) of the time the property was last set.
      "source": "BIDEN",
      // String; The method by which the value was set. See the contacts overview page (linked above) for more details
      "sourceId": "country",
      // String or null; Additional details for the source.
      // This may not be set for all source types.
      "versions": [
      // A list of previous versions of the property.
      // The first item in the list will be the current version
        {
          "name": "country",
          // String; The internal name of the property
          "value": "United States",
          // String; The value of the property for this version
          "timestamp": 1457708103906,
          // Integer; A Unix timestamp (in milliseconds) of the time when this version was set
          "source": "BIDEN",
          // String; The method by which this version was set. See the contacts overview page (linked above) for more details
          "sourceId": "country",
          // 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 record, this will be a list of vids for the changed contact.
          ]
        }
      ]
    },
    "city": {
      "value": "Cambridge",
      "timestamp": 1457708103906,
      "source": "BIDEN",
      "sourceId": "city",
      "versions": [
        {
          "name": "city",
          "value": "Cambridge",
          "timestamp": 1457708103906,
          "sourceId": "city",
          "source": "BIDEN",
          "sourceVid": [
            
          ]
        }
      ]
    }
  },
  "additionalDomains": []
  // This is a deprecated field and is not currently used.
}

Docs for this section or API