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.

CRM Associations API Overview

The CRM Associations API helps manage and define relationships between objects in the HubSpot CRM (contacts, companies, deals, quotes, line items, and tickets), allowing you to create a more holistic picture of your customer interactions and improving your ability to market, sell, and serve. While a full list of supported associations can be found below, common examples include: contact to company, company to parent or child company, deal to company or contact, and ticket to contact or company. Associations can also be created between engagements and other objects. 

Use case for this API: Your organization has several deals open with a company. Your sales team can use the CRM Associations API to associate these deals with a contact who has decision-making power. Associations also make it easier to analyze data and trends, like which job titles are most often connected with buying decisions.

Association definitions

Associations are defined based on the type of objects being associated, and the direction of that association. Association definitions are unidirectional, so you'll use a different definition ID depending on which object type you're starting with. For example, if you have a contact (identified by its vid) and you want the associated tickets, you would use definition ID 15. If you have a ticket (identified by its objectId) and you want the associated contacts, you would use definition ID 16. See the table below for the full list of definition IDs.

Association type Definition ID
Contact to company 1
Company to contact (default) 2
   Company to contact (all labels)   280
Deal to contact 3
Contact to deal 4
Deal to company 5
Company to deal 6
Company to engagement 7
Engagement to company 8
Contact to engagement 9
Engagement to contact 10
Deal to engagement 11
Engagement to deal 12
Parent company to child company 13
Child company to parent company 14
Contact to ticket 15
Ticket to contact 16
Ticket to engagement 17
Engagement to ticket 18
Deal to line item 19
Line item to deal 20
Company to ticket 25
Ticket to company 26
Deal to ticket 27
Ticket to deal 28

 

Docs for this section or API