Associations v4

Associations represent the relationships between objects and activities in the HubSpot CRM. You can use the associations endpoints to create, retrieve, update, or delete associations between records, or records and activities.

The association schema endpoints allow you to view the supported types of associations in your account, as well as create your own association types, and assign labels to your record relationships. Association labels are supported between contacts, companies, deals, tickets, and custom objects, and can be used across HubSpot in tools, such as lists and workflows.

Learn more about objects, records, properties, and associations APIs in the Understanding the CRM guide. 

HubSpot defined association types

HubSpot provides a set of predefined association types (e.g., unlabeled contact to company), but account admins can define their own association labels to provide additional context for record relationships (e.g., manager and employee). There are two HubSpot-defined association types: 

• Primary: the main company that the other record is associated with. Primary associations can be used in HubSpot tools such as lists and workflows. For records with multiple associated companies, this API supports changing which company is considered the primary.
• Unlabeled: an association type added when any contact, company, deal, ticket, or custom object record is associated. This type denotes that an association exists, and will always returned in responses with a label value of null. When a record has a primary association or a custom association label, those types will be listed alongside the unlabeled association type.

Create association types

You can create custom association types either in HubSpot or through the association schema API endpoint.

To create an association type through the API, make a POST request to /crm/v4/associations/{fromObjectType}/{toObjectType}/labels.

You can find more details about this request in the Association Definitions and Batch Endpoints tab at the top of this article.

Retrieve association types

To view the association types between specific objects, make a GET request to

You'll receive an array, each item containing:

• category: whether the association type was created by HubSpot or a user (HUBSPOT_DEFINED and USER_DEFINED).
• typeId: the numeric ID for that association type.
• label: the alphanumeric label. This will be null for the unlabeled association type.

Associate records

You can create a default unlabeled association between two records, or set up unlabeled associations for records in bulk.

To set up an individual default association between two records, make a PUT request to /crm/v4​/objects​/{fromObjectType}​/{fromObjectId}​/associations​/default​/{toObjectType}​/{toObjectId}.

In the request URL, include:

• objectType: the type of the object you're associating (e.g. contact).
• objectId: the ID of the record to associate.
• toObjectType: the type of object you're associating the record to (e.g. company). 
• toObjectId: the ID of the record to associate to.

To set up default associations in bulk, make a POST request to crm/v4/associations/{fromObjectType}/{toObjectType}/batch/associate/default. In the request body, include objectId values for the records you want to associate.

Associate records with an association label

To associate two records and set a label to describe the association, make a PUT request to /crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}.

In the request body, include the category and typeId to indicate the type of association you want to create. For example:

Limits

• You can create up to 10 association labels between object types (e.g. contacts and companies).
• The number of associations a record can have depends on the object and your HubSpot subscription.
• When making a batch read request to the /crm/v4/associations/{fromObjectType}/{toObjectType}/batch/read endpoint:
  
  • The maximum number of IDs that can be input is 11,000.
  • The default number of associations returned in each page of the response is 1,000.