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
DELETEendpoint 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
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 (
- typeId: the numeric ID for that association type
- label: the alphanumeric label. Will be
nullfor the unlabeled association type.
Associate records with a custom association type
To set association labels between two records, make a
PUT request to
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
typeId of the type of association you want to create. For example:
Thank you for your feedback, it means a lot to us.