The CRM Associations endpoints are used to manage associations between object records.
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 details endpoints: create, edit, and remove associations between records. In this article, you’ll learn more about using the associations details 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. Learn more about using the associations schema endpoints.
Learn more about objects, records, properties, and associations APIs in the Understanding the CRM guide.
The v4 Associations API is supported in Version 9.0.0 or later of the NodeJS HubSpot Client.
You can associate records with each other unlabeled (i.e. contact and company associated with no descriptor) or with labels (e.g., contact and company associated and the contact is the company’s Decision maker).
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. For example:
You can also associate records with labels for individual record pairs or multiple pairs of records in bulk. For each association, depending on your association limits, you can include multiple labels.
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 cross-object and paired label relationships, ensure you use the typeId that refers to the correct direction. For example, if your fromObjectType is contact and your toObjectType is company, the typeId you should use to label that company as primary is 1.
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 type.
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 body 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 body 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. However, if you delete the default unlabeled association type, this will remove all other associations.
To remove all associations between pairs of records:
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 record pairs, 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 body would look like:
To remove record associations with 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 labels to remove.For example, to remove a custom label from an association, but keep the unlabeled association, your request body 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.
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.
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 unlabeled or have custom association labels.
