Using the HubSpot Companies API

The HubSpot Companies API allows you to manage your company data in HubSpot. Companies in HubSpot can represent any type of organization.

Contact to Company Association

Companies have a one to many relationship with contacts and deals (multiple contacts and deals can be associated with a single company, but one a single company can be associated with a single contact or deal). Any contacts or deals associated with the company will appear as related items when viewing the company in HubSpot.

Contacts can be associated with companies using two different methods:

  1. The preferred method is to update the contact record and set the associatedcompanyid property of the contact. The value of the property will be the companyId of the company record. This will allow you to associated contacts in bulk using the batch update endpoint.
  2. You can also associate contacts with companies using the endpoint documented here. This will only allow you to associate a single contact at a time.

Individual company records will have the following format. With the exception of being able to update 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