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.

You can view all of the HubSpot-defined association types in this section.

Create association types

You can create custom association types either in HubSpot or through the association schema API endpoint. You can create up to 10 association types between each object pairing (e.g. contacts and companies).

To create an association type through the API, make a POST request to /crm/v4/associations/{fromObjectType}/{toObjectType}/labels and include the following in your request:

• name: the internal name of the association type. This value cannot include hyphens or begin with a numerical character.
• label: the name of the association label as shown in HubSpot.

You can find more details about this request in the Association schema 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 (HUBSPOT_DEFINED) or by a user (USER_DEFINED).
• typeId: the numeric ID for that association type. This is used to set a label when associating records. Refer to this list for all the HubSpot defined typeId values.
• 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:

• fromObjectType: the ID of the object you're associating. To find the ID values, refer to this list of object type IDs, or for contacts, companies, deals, tickets, and notes, you can use the object name (e.g., contact, company).
• fromObjectId: the ID of the record to associate.
• toObjectType: the ID of the object you're associating the record to. To find the ID values, refer to this list of object type IDs, or for contacts, companies, deals, tickets, and notes, you can use the object name (e.g., contact, company).
• toObjectId: the ID of the record to associate to.

For example, to associate a contact record whose ID is 12345 with a company record whose ID is 67891, your request URL would be: /crm/v4​/objects​/contact​/12345​/associations​/default​/company​/67891.

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. 

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 associationCategory and associationTypeId to indicate the type of association you want to create.

If you're creating unlabeled associations, you can use the default endpoints outlined in the section above which don't require the associationCategory or associationTypeId. If you're creating associations with a label, you can refer to this list of default type IDs, or you'll need to retrieve the custom association types between those objects. For example, to associate a contact with a deal using a custom label:

1. Make a GET request to /crm/v4/associations/contact/deal/labels.

2. In the response, look at the typeId and category values for the label. The ID will be a number (e.g., 36), and the category will always be USER_DEFINED for custom labels.

3. Make a PUT request to /crm/v4/objects/contact/{objectId}/associations/deal/{toObjectId}with the following request body:

The following tables include the HubSpot-defined associationTypeId values that specify the type of association. Association types vary depending on the included objects and the direction of the association (e.g., Contact to Company is different from Company to Contact). If you create custom objects or custom association labels, the related association types will have unique typeId values that you'll need to retrieve.