Associations v4

Access and test APIs in beta. 

Please note: This API is currently under development and is subject to change based on testing and feedback. By using these endpoints you agree to adhere to our Developer TermsDeveloper BetaTerms. You also acknowledge and understand the risk associated with testing an unstable API. 

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.

More information

  • 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: 

  1. Primary
  2. Unlabeled

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:

  • A toObjectId with the associated record ID
  • An array of association types. Each type contains:
    • category: current options are HUBSPOT_DEFINED and PORTAL_SPECIFIC
    • typeId: Numeric ID for that association type
    • label: String that contains the alphanumeric label. Will be `null` for the unlabeled association type.

What's different

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


Was this page helpful? *
This form is for feedback on our developer docs. If you have feedback on the HubSpot product, please share it in our Idea Forum instead.