Associations

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

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

All associations between objects are one-to-many for a given direction, meaning a record of one object can be associated with many records of another object. For example, if you have a custom object for Pets, a single pet can be associated with multiple owners, or a single contact be associated with multiple pets. Records of the same object can't be associated with each other (e.g., a contact can't be associated with another contact).

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
  • Engagements

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 page helpful? *
This form is for feedback on our developer docs. If you have feedback on the HubSpot product, please share it in our Idea Forum instead.