Access and test APIs in beta.
This API is currently in beta. For the latest stable version check out the assocations page version 3.
The latest update to CRM associations in HubSpot allows users to go beyond the predefined HubSpot association types. Account admins can now define their own “association labels”, which are descriptors that provide context for the relationships between records. For example, you can create a contact:company association label called “Consultant” to explain that a contact is a consultant for a company, rather than an employee. These labels 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.
- Association labels are supported between contacts, companies, deals, and tickets. Any combination of those object types can have a 1:many association type between them.
- Multiple association labels can be used to describe a single record pair, for example a company may have both a “current employer” and “board member” association with a contact.
To support this change, two new HubSpot-defined association types have been created:
Primary association type
This CRM associations update includes UI support for multiple company associations on contact, deal, and ticket records. As part of this change, there is a new HubSpot-defined association type called “Primary” between specifically those object types. “Primary” can be used in HubSpot functionality like lists and workflows, to only take action on the record which is considered the “Primary” association. The first company record associated with a contact, deal, or ticket is now auto-assigned to the “Primary”. This API provides support for changing which company is considered the “Primary”.
Unlabeled association type
The unlabeled association type is a new HubSpot default that will be added to any association between the contact, company, deal, or ticket object types. This type will always be returned in the response, where the Primary and portal-defined association types are only included as applicable.
How it works
When getting information about associations between objects, you'll receive an array, each item containing:
toObjectIdwith the associated record ID
- An array of association types. Each type contains:
category: current options are
typeId: Numeric ID for that association type
label: String that contains the alphanumeric label. Will be `null` for the unlabeled association type.
- It’s now possible to associate multiple companies with a single contact, deal, or ticket. Previously a record of those types could only be associated with a single company.
- Two records can be associated with multiple association types. Expect an array of association types coming back in all responses.
- Use the DELETE endpoint to remove associations between two records.
What we’re planning for the future
- CRUD powers for creating and managing association labels
- Association label support for custom objects
- Up to 10 association labels between object types (e.g. contacts and companies)
- Up to 10k total associations between a record and records of an object type (e.g. 10k companies can be associated with a single contact).
Thank you for your feedback, it means a lot to us.