Associations v4

While HubSpot provides a set of predefined association types, account admins can now define their own association labels, which provide more context for the relationships between records. Association labels are supported between contacts, companies, deals, and tickets. 

For example, you can create a contact-company association label called Consultant to show that a contact is a consultant for a company, rather than an employee. That label can then be used across HubSpot in tools such as lists and workflows. For example, you can build a list of all contacts associated with companies as Consultants or run a workflow that updates a property on the company that the contact consults for.

In addition, records can have multiple association labels assigned to them. For example a company may have both a Current employer and Board member association with a contact.

With this update, the following is now possible:

• Associating multiple companies with a single contact, deal, or ticket. Previously a record of those types could only be associated with a single company.
• Associating records with multiple association types. Expect an array of association types coming back in all responses.
• Using the DELETE endpoint to remove associations between records.

HubSpot defined association types

To support multiple company associations on contact, deal, and ticket records, two new HubSpot-defined association types have been created: 

• 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 example, set up a workflow to only take action on records that are considered the Primary association. The first company record associated with a contact, deal, or ticket is automatically set to Primary. This API supports changing which company is considered the primary.
• Unlabeled: an association type added when any contact, company, deal, or ticket 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 type, 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 definitions 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

• 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. Will be null for the unlabeled association type.

Associate records with a custom association type

To set association labels between two records, make a PUT request to

/crm/v4/objects/{objectType}/{objectId}/associations/{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.

In the request body, include the category and typeId of 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).
• You can have up to 10,000 total associations between a record and records of an object type (e.g., 10,000 companies can be associated with a single contact). In accounts with Starter, Professional, or Enterprise subscriptions, you can have up to 50,000 associations per each contact, company, ticket, or custom object pair. The increased limit does not apply to Contact to Deal associations, Deal to [Object] associations, or records associated to an engagement.