Associations v3

OverviewEndpoints

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.

Please note: this API doesn't support parent-child associations or special contact-to-company associations. Learn more about how you can use these associations with the previous version of the associations API.

Association definitions

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 its objectId. 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 their objectIds. 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.

Create associations

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:

///Example request body { "inputs": [ { "from": { "id": "53628" }, "to": { "id": "12726" }, "type": "contact_to_company" } ] }

Retrieve associations

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.

Remove associations

To remove associations between records, make a POST request to /crm/v3/associations/{fromObjectType}/{toObjectType}/batch/archive.

Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.