Skip to main content

Associations represent the relationships between objects and activities in the HubSpot CRM. You can use the v3 associations endpoints to create, retrieve, or remove associations in bulk.

Learn more about objects, records, properties, and associations APIs in the Understanding the CRM guide. For more general information about objects and records in HubSpot, learn how to manage your CRM database.

Associations are defined by object and direction. Association types are unidirectional, which means you'll need to use a different definition depending on the starting object type. Each endpoint requires a {fromObjectType} and {toObjectType} that tell the direction of the association.

For example:

  • To view all the defined association types from contacts to companies, you'd make a request to /crm/v3/associations/contacts/companies/types.
  • To see all tickets associated with a contact, you'd make a request to /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.

Association types can include unlabeled associations (e.g., contact-to-company), default labeled associations (e.g., contact-to-primary company), and custom labeled associations (e.g., Decision maker contact-to-company).

To view all the defined association types between objects, including default associations and custom association labels, make a GET request to /crm/v3/associations/{fromObjectType}/{toObjectType}/types.

Each type will have a returned numerical id value and name that can be used to reference the association type in other requests. For default associations, the numerical ID will be the same for all accounts, but for custom association labels, the ID will be unique to your account.

For example, your response would look similar to the following:

To associate records, make a POST request to /crm/v3/associations/{fromObjectType}/{toObjectType}/batch/create. In your request, include the id values for the records you want to associate, as well as the type of the association.

For example, to associate contacts to companies, your request URL would be /crm/v3/associations/Contacts/Companies/batch/create, and your request would look similar to the following:

To retrieve associated records, make a POST request to /crm/v3/associations/{fromObjectType}/{toObjectType}/batch/read. In your request, include the id values of the records whose associations you want to view. This will be for the {fromObjectType}.

For example, to retrieve deals associated with companies, your request URL would be /crm/v3/associations/Companies/Deals/batch/read and the request body would look like the following, with id values for the companies whose deal associations you want to view:

In your response, you'll receive the id values of all associated records. For the above example, your response would include the id values for all associated deals and the association type. The response would look similar to the following:

To remove associations between records, make a POST request to /crm/v3/associations/{fromObjectType}/{toObjectType}/batch/archive. In the request body, include the id values for the from record and the to record, as well as their association type.

For example, to remove the association between a company and a deal, your request would look like: