Associations v3

There is a new version of the Associations API that adds the ability to create multiple types of associations between two CRM object types.

Associations represent the relationships between objects in the HubSpot CRM. The CRM associations endpoints help manage and define those relationships.

Example use case: Your organization has several deals with one company. Your sales team can use the CRM Associations API to associate these deals with a contact who is the decision maker within the company. You can use these associations to analyze data and trends, such as exploring which job titles are most frequently connected with buying decisions.

This API doesn't support the following associations:

  • Parent-child associations
  • Special contact-to-company associations

Learn more about how you can use these associations with the previous version of the associations API.

Association definitions

Associations are defined by object and direction. Association definitions are unidirectional, which means you'll need to use a different definition depending on the starting object type. 

For example:

  • To see all tickets associated with a contact, you would define the association with the request URL /crm/v3/associations/Contacts/Tickets/batch/read and identify the contact in the request body by its objectId. In this example, Contacts is the fromObjectType, and Tickets is the toObjectType.
  • To associate a contact record to a custom object record, where your custom object is Pets, you would define the association with the request URL /crm/v3/associations/Pets/Contacts/batch/create and identify the contact and pet records you want to associate in the request body by their objectIds. In this example, Pets is the fromObjectType, and Contacts is the toObjectType.

 You can test your own examples in the Endpoints tab. You can associate the following objects or engagements via the Associations API:

  • Contacts
  • Companies
  • Deals
  • Tickets
  • Custom objects: the name you've defined for the custom object (e.g., Pets, Cars, etc.).
  • Calls
  • Quotes
  • Line_items
  • Meetings
  • Products
  • Feedback_submissions

Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.