The CRM Associations endpoints are used to manage associations between tickets, products, line items, and their related contacts, companies, and deals.
For the previous version, please see the documentation for the v3 Associations API.
Scope requirements
Associations represent the relationships between objects and activities in the HubSpot CRM. Record associations can exist between records of different objects (e.g., Contact to Company), as well as within the same object (e.g., Company to Company).The v4 Associations API includes two sets of endpoints:
Association schema endpoints: view your account’s association definitions (also known as types), create and manage custom association labels, and set limits for associations. 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.
Please note:The v4 Associations API is supported in Version 9.0.0 or later of the NodeJS HubSpot Client.
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 associate records without a label 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.
You can also associate records with labels for individual record pairs or multiple pairs of records in bulk.
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 URL, include the id values of the two records you’re associating.
To bulk create labelled associations between records of the same objects, make a POST request to /crm/v4/associations/{fromObjectType}/{toObjectType}/batch/create. In the request body, include the id values of records to associate in addition to the required parameters below.
In the request body, include the following information to indicate the labeled association you want to create:
associationCategory: either HUBSPOT_DEFINED (default label) or USER_DEFINED (custom label).
associationTypeId: the numerical ID value for the label. If using a default label (e.g., Primary company), refer to this list of default type IDs. If you’re using a custom label, you’ll need to retrieve the labels between those objects.
For each association, depending on your association limits, you can include multiple labels.
Please note:For cross-object and paired label relationships, ensure you use the typeId that refers to the correct direction (e.g., Contact to Company vs. Company to Contact, Employee to Manager vs. Manager to Employee).
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 example request body:
A successful response will include the id values of the two associated records along with the label for the association. For the example above, the response would look like:
You can retrieve a record’s associations of a specific object.
To retrieve an individual record’s associations of a specific object, make a GET request to /crm/v4/objects/{fromObjectType}/{objectId}/associations/{toObjectType}. In the request URL, include the record’s object as the fromObjectType and its record ID as the objectId.
To retrieve a record’s associated records of a specific object, make a POST request to /crm/v4/associations/{fromObjectType}/{toObjectType}/batch/read. In the request body, include up to 1,000 id values of records whose associated records you want to retrieve.
For example, to retrieve all company associations for two contacts, make a POST request to /crm/v4/associations/contacts/companies/batch/read. Your request would look like the following:
For both the basic and batch endpoints, the record ID values will be returned for each associated record, along with information to describe the association between the record, including the label, category, and typeId. For the example batch request above, the response would be:
For existing associations, to update the association labels, you can use the basic and batch create endpoints. If an existing labeled association exists between two records, to replace the existing label, only include the new label in the request. If you want to append labels (i.e. add a new label and keep the existing label), include both labels in your request.For example, if records are already associated with a label with the typeId of 30, to keep that label while adding another label, your request would look like:
You can delete all associations between records, or delete only associations of specific types (i.e. default or custom labels). When deleting all associations, the records will not be deleted, but they will no longer be associated with one another. If deleting a specific association type, the records will still be associated but the specified labels will be removed, with the exception of deleting the default unlabelled association type which will remove all other associations.To remove all associations:
To remove all associations between two records, make a DELETE request to /crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}.
To batch remove all associations between records, make a POST request to /crm/v4/associations/{fromObjectType}/{toObjectType}/batch/archive. In the request body, include the id values of records for which you want to remove all of their associations.
For example, to remove all associations between sets of contacts and companies, your request would look like:
To remove specific association labels, make a POST request to /crm/v4/associations/{fromObjectType}/{toObjectType}/batch/labels/archive. In the request body, include an array with id values of the associated records and the associationTypeId and category values of label(s) to remove.For example, to remove a custom label from an association, but keep the unlabeled association, your request would look like:
There are technical limits to the number of associations a record can have. You can use the associations API to retrieve a report of records that are either approaching or have hit the maximum limit for associations.To retrieve the report, make a POST request to crm/v4/associations/usage/high-usage-report/{userID}. The file includes records using 80% or more of their association limit. For example, if a company can be associated with up to 50,000 contacts, the company will be included in the file if it has 40,000 or more associated contacts. The file will be sent to the email of the user whose ID was included in the request URL. Learn how to retrieve user IDs with the users API.
Understand association definitions, configurations, and labels
To manage association definition (a.k.a association type) configurations and labels, use the Association schema endpoints. These endpoints include configuration endpoints and label endpoints. You should use the endpoints for the following goals:
Association definitions (labels): create and manage association types, including creating, editing, and deleting custom association labels. For example, create a Billing contact label between contacts and deals or a Manager and Employee paired label between contacts.
Association definition configurations: set and manage limits for how many associations can exist per association type. For example, allow up to five associated deals per company or only one associated contact with the Decision maker label per company.
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 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.
You can create association labels to further define record associations. For example, you could create a Decision maker label to indicate which contacts at a company are responsible for making purchasing decisions.Learn more about creating association labels below.
You can create custom labeled association types in HubSpot or through the association schema API endpoint. You can create up to 10 association labels between each object pairing (e.g. contacts and companies, contacts and contacts).There are two types of association labels you can use to describe the relationships between records:
Single: one label that applies to both records in the relationship. For example, Friend or Colleague.
Paired: a pair of labels for when different words are used to describe each side of the associated records’ relationship. For example, Parent and Child or Employer and Employee. To create paired labels, you must include the inverseLabel field in your request to name the second label in the pair.
To create a labeled association type, 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.
In the response, the new association label’s category and unique typeId will be returned, which you can use to retrieve, update, or delete the label moving forward. For paired labels, there’ll be a value for each direction of the association (e.g., 550 for contact to company and 551 for company to contact). For example, for the paired label request above, the response would look like:
To view the association types between specific objects, make a GET request to /crm/v4/associations/{fromObjectType}/{toObjectType}/labels.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).
label: the alphanumeric label. This will be null for the unlabeled association type.
You can also find these values in HubSpot in your association settings.For example, to view all association types from contacts to companies, make a GET request to /crm/v4/associations/contacts/companies/labels. Your response would look similar to the following:
You can edit the label field for association types, which updates the name as it appears in HubSpot in your settings and on records. You cannot change the internal name or typeId.To update a label, make a PUT request to /crm/v4/associations/{fromObjectType}/{toObjectType}/labels. In the request body, including the associationTypeId and a new value for label. If editing a paired label, you can also include a new value for inverseLabel.Using the example in the section above, to update the label Contractor to Contract worker, your request would look like:
You can delete custom association labels if they’re no longer in use. If a label is used to describe associated records, you’ll need to remove the label from associations before deleting. Default association types, including the Primary company label, cannot be deleted.To delete an association label, make a DELETE request to /crm/v4/associations/{fromObjectType}/{toObjectType}/labels/{associationTypeId}. You’ll no longer be able to use this label when associating records.
You can create new or update existing association limits between objects.
To create limits, make a POST request to crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/create.
To update existing limits, make a POST request to crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/update.
In the request body, include inputs with the following:
Parameter
Description
category
The category of the association you’re setting a limit for, either HUBSPOT_DEFINED or USER_DEFINED.
typeId
The numeric ID for the association type you want to set a limit for. Refer to this list of default typeId values or retrieve the value for custom labels.
maxToObjectIds
The maximum number of associations allowed for the association type.
For example, to set limits that a deal can be associated with a maximum of five contacts with only one contact labelled Point of contact for a deal, your request would look like the following:
To read all defined association limits, make a GET request to /crm/v4/associations/definitions/configurations/all. This will return custom association limits defined across all objects.
To read association limits between two specific objects, make a GET request to /crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}.
For both requests, the response will return the associations’ values for category, typeId, maxToObjectIds, and label. For example, if retrieving limits between deals and contacts, the response would look similar to:
To delete specific association limits, make a POST request to /crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/purge. In the request body, include the category and typeId values of the association types for which you want to remove limits.For example, to remove the Point of contact limit between deals and contacts, the request would look like:
If successful, you’ll receive a 204 response and the included limit will return to the system default (i.e. Many contacts can have the label Point of contact).
The association API endpoints are subject to the following limits based on your account subscription:
Daily limits:
Professional accounts: 500,000 requests
Enterprise accounts: 500,000 requests
You can purchase an API limit increase, you can make a maximum of 1,000,000 requests per day. This maximum will not increase for association API requests if you purchase an additional API limit increase.
Burst limits:
Freeand Starter accounts: 100 requests per 10 seconds
Professionaland Enterprise accounts: 150 requests per 10 seconds
If you purchase the API limit increase, you can make a maximum of 200 requests per 10 seconds. This maximum will not increase for association API requests if you purchase an additional API limit increase.
The following limits apply for batch associations API endpoint requests:
Batch read associations: limited to 1,000 inputs per request body.
Batch create associations: limited to 2,000 inputs per 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 or locate in your association settings in HubSpot.
Please note:Default company association types include an unlabeled association type and a primary association type. If a record has more than one associated company, only one can be the primary company. The other associations can either be unlabelled or have custom association labels.
