Associations v4

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). 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 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.

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.
  

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, contacts and contacts).

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.
• inverseLabel (paired labels only): the name of the second label in the pair of labels.

For example, your request could look similar to the following:

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).
• 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.

You can also find these values in HubSpot in your association settings.

Associate records without a label

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:

You can set up limits for the number of associated records between objects, or how often a label can be used to describe associations. There are also technical limits and limits based on your HubSpot subscription.

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.

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}.

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).

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 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.

If you're using the v1 associations API, view the table below for information about IDs to use when associating records.

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:
  • Free and Starter accounts: 100 requests per 10 seconds
  • Professional and 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.

Learn more about API limits in this article.