Associations v3
There is a new version of the Associations API that adds the ability to create multiple types of associations between two object types.
Associations represent the relationships between objects and activities in the HubSpot CRM. You can use the associations endpoints to create, retrieve, or remove associations in bulk. You can associate the following objects or engagements via the Associations API:
Contacts
Companies
Deals
Tickets
Calls
Quotes
Line_items
Meetings
Products
Feedback_submissions
Custom objects
(the name of your object)
Learn more about objects, records, properties, and associations APIs in the Understanding the CRM guide. For more general information about objects and records in HubSpot, learn how to manage your CRM database.
Associations are defined by object and direction. Association types are unidirectional, which means you'll need to use a different definition depending on the starting object type. For example:
- To see all tickets associated with a contact, you would define the association with the request URL
/crm/v3/associations/Contacts/Tickets/batch/read
and identify the contact in the request body by itsobjectId
. In this example, Contacts is the fromObjectType, and Tickets is the toObjectType. - To associate a contact record to a custom object record, where your custom object is Pets, you would define the association with the request URL
/crm/v3/associations/Pets/Contacts/batch/create
and identify the contact and pet records you want to associate in the request body by theirobjectIds
. In this example, Pets is the fromObjectType, and Contacts is the toObjectType.
To view all the defined association types between objects, make a GET
request to /crm/v3/associations/{fromObjectType}/{toObjectType}/types
.
To associate records in HubSpot, make a POST
request to /crm/v3/associations/{fromObjectType}/{toObjectType}/batch/create
. In your request, include the id
values for the records you want to associate, as well as the type
of association the records belong to.
For example, to associate contacts to companies, your request URL would be /crm/v3/associations/Contacts/Companies/batch/create
, and your request would look similar to the following:
To retrieve associated records, make a POST
request to /crm/v3/associations/{fromObjectType}/{toObjectType}/batch/read
. In your request you can include the id
of a specific record for the fromObjectType
. In your response, you'll receive the id
values of all toObjectType
associated records.
For example, to retrieve all deals associated with a company, your request URL would look like /crm/v3/associations/Companies/Deals/batch/read
. Your response would include the id
values for all associated deals.
To remove associations between records, make a POST
request to /crm/v3/associations/{fromObjectType}/{toObjectType}/batch/archive
.
Thank you for your feedback, it means a lot to us.