Skip to main content

Associations represent the relationships between objects and activities in the HubSpot CRM. Record associations can exist between records of different objects (e.g., Contact to Company), as well as within the same object (e.g., Company to Company).

The v4 Associations API includes Association endpoints and Association schema endpoints:

  • Association endpoints: create, edit, and remove associations between records.
  • Association schema endpoints: view your account's association definitions (also known as types), create and manage custom association labels, and set limits for associations. Association labels are supported between contacts, companies, deals, tickets, and custom objects, and can be used across HubSpot in tools, such as lists and workflows.

Learn more about objects, records, properties, and associations APIs in the Understanding the CRM guide.

To associate records with records with one another, use the Association endpoints.

You can create a default unlabeled association between two records, or set up unlabeled associations for records in bulk. To set up an individual default association between two records, make a PUT request to

/crm/v4/objects/{fromObjectType}/{fromObjectId}/associations/default/{toObjectType}/{toObjectId}

In the request URL, include:

  • fromObjectType: the ID of the object you're associating. To find the ID values, refer to this list of object type IDs, or for contacts, companies, deals, tickets, and notes, you can use the object name (e.g., contact, company).
  • fromObjectId: the ID of the record to associate.
  • toObjectType: the ID of the object you're associating the record to. To find the ID values, refer to this list of object type IDs, or for contacts, companies, deals, tickets, and notes, you can use the object name (e.g., contact, company).
  • toObjectId: the ID of the record to associate to.

For example, to associate a contact record whose ID is 12345 with a company record whose ID is 67891, your request URL would be: /crm/v4/objects/contact/12345/associations/default/company/67891.

To associate records without a label in bulk, make a POST request to crm/v4/associations/{fromObjectType}/{toObjectType}/batch/associate/default. In the request body, include objectId values for the records you want to associate.

You can also associate records with labels for individual record pairs or multiple pairs of records in bulk.

  • To associate two records and set a label to describe the association, make a PUT request to /crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}. In the request URL, include the id values of the two records you're associating.
  • To bulk create labelled associations between records of the same objects, make a POST request to /crm/v4/associations/{fromObjectType}/{toObjectType}/batch/create. In the request body, include the id values of records to associate in addition to the required parameters below.

In the request body, include the following information to indicate the labeled association you want to create:

  • associationCategory: either HUBSPOT_DEFINED (default label) or USER_DEFINED (custom label).
  • associationTypeId: the numerical ID value for the label. If using a default label (e.g., Primary company), refer to this list of default type IDs. If you're using a custom label, you'll need to retrieve the labels between those objects.

For each association, depending on your association limits, you can include multiple labels.

For example, to associate a contact with a deal using a custom label:

1. Make a GET request to /crm/v4/associations/contact/deal/labels.

2. In the response, look at the typeId and category values for the label. The ID will be a number (e.g., 36), and the category will always be USER_DEFINED for custom labels.

3. Make a PUT request to /crm/v4/objects/contact/{objectId}/associations/deal/{toObjectId}with the following request body:

A successful response will include the id values of the two associated records along with the label for the association. For the example above, the response would look like:

You can retrieve a record's associations of a specific object.

  • To retrieve an individual record's associations of a specific object, make a GET request to /crm/v4/objects/{fromObjectType}/{objectId}/associations/{toObjectType}. In the request URL, include the record's object as the fromObjectType and its record ID as the objectId.
  • To retrieve a record's associated records of a specific object, make a POST request to /crm/v4/associations/{fromObjectType}/{toObjectType}/batch/read. In the request body, include up to 1,000 id values of records whose associated records you want to retrieve.

For example, to retrieve all company associations for two contacts, make a POST request to /crm/v4/associations/contacts/companies/batch/read. Your request would look like the following:

For both the basic and batch endpoints, the record ID values will be returned for each associated record, along with information to describe the association between the record, including the label, category, and typeId. For the example batch request above, the response would be:

For existing associations, to update the association labels, you can use the basic and batch create endpoints. If an existing labeled association exists between two records, to replace the existing label, only include the new label in the request. If you want to append labels (i.e. add a new label and keep the existing label), include both labels in your request.

For example, if records are already associated with a label with the typeId of 30, to keep that label while adding another label, your request would look like:

You can delete all associations between records, or delete only associations of specific types (i.e. default or custom labels). When deleting all associations, the records will not be deleted, but they will no longer be associated with one another. If deleting a specific association type, the records will still be associated but the specified labels will be removed, with the exception of deleting the default unlabelled association type which will remove all other associations.

To remove all associations:

  • To remove all associations between two records, make a DELETE request to /crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}.
  • To batch remove all associations between records, make a POST request to /crm/v4/associations/{fromObjectType}/{toObjectType}/batch/archive. In the request body, include the id values of records for which you want to remove all of their associations.

For example, to remove all associations between sets of contacts and companies, your request would look like:

To remove specific association labels, make a POST request to /crm/v4/associations/{fromObjectType}/{toObjectType}/batch/labels/archive. In the request body, include an array with id values of the associated records and the associationTypeId and category values of label(s) to remove.

For example, to remove a custom label from an association, but keep the unlabeled association, your request would look like:

If you then retrieve that contact's company associations, now only the unlabelled association type will be returned for the above associated company:

There are technical limits to the number of associations a record can have. You can use the associations API to retrieve a report of records that are either approaching or have hit the maximum limit for associations.

To retrieve the report, make a POST request to crm/v4/associations/usage/high-usage-report/{userID}. The file includes records using 80% or more of their association limit. For example, if a company can be associated with up to 50,000 contacts, the company will be included in the file if it has 40,000 or more associated contacts. The file will be sent to the email of the user whose ID was included in the request URL. Learn how to retrieve user IDs with the users API.

To manage association definition (a.k.a association type) configurations and labels, use the Association schema endpoints. These endpoints include configuration endpoints and label endpoints. You should use the endpoints for the following goals:

  • Association definitions (labels): create and manage association types, including creating, editing, and deleting custom association labels. For example, create a Billing contact label between contacts and deals or a Manager and Employee paired label between contacts.
  • Association definition configurations: set and manage limits for how many associations can exist per association type. For example, allow up to five associated deals per company or only one associated contact with the Decision maker label per company.

HubSpot provides a set of predefined association types (e.g., unlabeled contact to company), but account admins can define their own association labels to provide additional context for record relationships (e.g., manager and employee). There are two HubSpot-defined association types:

  • 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 records with multiple associated companies, this API supports changing which company is considered the primary.
  • Unlabeled: an association added when any contact, company, deal, ticket, or custom object 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 label, those types will be listed alongside the unlabeled association type.

You can view all of the HubSpot-defined association types in this section.

You can create association labels to further define record associations. For example, you could create a Decision maker label to indicate which contacts at a company are responsible for making purchasing decisions.

Use the definitions endpoints to create custom labeled association types and review or manage existing types.

You can create custom labeled association types in HubSpot or through the association schema API endpoint. You can create up to 10 association labels between each object pairing (e.g. contacts and companies, contacts and contacts).

There are two types of association labels you can use to describe the relationships between records:

  • Single: one label that applies to both records in the relationship. For example, Friend or Colleague.
  • Paired: a pair of labels for when different words are used to describe each side of the associated records' relationship. For example, Parent and Child or Employer and Employee. To create paired labels, you must include the inverseLabel field in your request to name the second label in the pair.

To create a labeled association type, make a POST request to /crm/v4/associations/{fromObjectType}/{toObjectType}/labels and include the following in your request:

  • name: the internal name of the association type. This value cannot include hyphens or begin with a numerical character.
  • label: the name of the association label as shown in HubSpot.
  • inverseLabel (paired labels only): the name of the second label in the pair of labels.

For example, your request could look similar to the following:

In the response, the new association label's category and unique typeId will be returned, which you can use to retrieve, update, or delete the label moving forward. For paired labels, there'll be a value for each direction of the association (e.g., 550 for contact to company and 551 for company to contact). For example, for the paired label request above, the response would look like:

Once created, you can now add the label when associating records.

To view the association types between specific objects, make a GET request to /crm/v4/associations/{fromObjectType}/{toObjectType}/labels.

You'll receive an array, each item containing:

  • category: whether the association type was created by HubSpot (HUBSPOT_DEFINED) or by a user (USER_DEFINED).
  • typeId: the numeric ID for that association type. This is used to set a label when associating records. Refer to this list for all the HubSpot defined typeId values.
  • label: the alphanumeric label. This will be null for the unlabeled association type.

You can also find these values in HubSpot in your association settings.

For example, to view all association types from contacts to companies, make a GET request to /crm/v4/associations/contacts/companies/labels. Your response would look similar to the following:

You can edit the label field for association types, which updates the name as it appears in HubSpot in your settings and on records. You cannot change the internal name or typeId.

To update a label, make a PUT request to /crm/v4/associations/{fromObjectType}/{toObjectType}/labels. In the request body, including the associationTypeId and a new value for label. If editing a paired label, you can also include a new value for inverseLabel.

Using the example in the section above, to update the label Contractor to Contract worker, your request would look like:

You can delete custom association labels if they're no longer in use. If a label is used to describe associated records, you'll need to remove the label from associations before deleting. Default association types, including the Primary company label, cannot be deleted.

To delete an association label, make a DELETE request to /crm/v4/associations/{fromObjectType}/{toObjectType}/labels/{associationTypeId}. You'll no longer be able to use this label when associating records.

Use the definition configuration endpoints to set up limits for the number of associated records between objects, or how often a label can be used to describe associations. There are also technical limits and limits based on your HubSpot subscription.

You can create new or update existing association limits between objects.

  • To create limits, make a POST request to crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/create.
  • To update existing limits, make a POST request to crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/update.

In the request body, include inputs with the following:

ParameterDescription
categoryThe category of the association you're setting a limit for, either HUBSPOT_DEFINED or USER_DEFINED.
typeIdThe numeric ID for the association type you want to set a limit for. Refer to this list of default typeId values or retrieve the value for custom labels.
maxToObjectIdsThe maximum number of associations allowed for the association type.

For example, to set limits that a deal can be associated with a maximum of five contacts with only one contact labelled Point of contact for a deal, your request would look like the following:

  • To read all defined association limits, make a GET request to /crm/v4/associations/definitions/configurations/all. This will return custom association limits defined across all objects.
  • To read association limits between two specific objects, make a GET request to /crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}.

For both requests, the response will return the associations' values for category, typeId, maxToObjectIds, and label. For example, if retrieving limits between deals and contacts, the response would look similar to:

To delete specific association limits, make a POST request to /crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/purge. In the request body, include the category and typeId values of the association types for which you want to remove limits.

For example, to remove the Point of contact limit between deals and contacts, the request would look like:

If successful, you'll receive a 204 response and the included limit will return to the system default (i.e. Many contacts can have the label Point of contact).

The association API endpoints are subject to the following limits based on your account subscription:

  • Daily limits:
    • Professional accounts: 500,000 requests
    • Enterprise accounts: 500,000 requests
    • You can purchase an API limit increase, you can make a maximum of 1,000,000 requests per day. This maximum will not increase for association API requests if you purchase an additional API limit increase.
  • Burst limits:
    • Free and Starter accounts: 100 requests per 10 seconds
    • Professional and Enterprise accounts: 150 requests per 10 seconds
    • If you purchase the API limit increase, you can make a maximum of 200 requests per 10 seconds. This maximum will not increase for association API requests if you purchase an additional API limit increase.

Learn more about API limits in this article.

The following tables include the HubSpot-defined associationTypeId values that specify the type of association. Association types vary depending on the included objects and the direction of the association (e.g., Contact to Company is different from Company to Contact). If you create custom objects or custom association labels, the related association types will have unique typeId values that you'll need to retrieve or locate in your association settings in HubSpot.

TYPE IDAssociation type
450Company to company
14Child to parent company
13Parent to child company
280Company to contact
2Company to contact (Primary)
342Company to deal
6Company to deal (Primary)
340Company to ticket
25Company to ticket (Primary)
181Company to call
185Company to email
187Company to meeting
189Company to note
191Company to task
88Company to communication (SMS, WhatsApp, or LinkedIn message)
460Company to postal mail
180Company to invoice
510Company to order
390Company to payment
298Company to subscription
909Company to appointment
939Company to course
885Company to listing
793Company to service
TYPE IDAssociation type
449Contact to contact
279Contact to company
1Contact to company (Primary)
4Contact to deal
15Contact to ticket
193Contact to call
197Contact to email
199Contact to meeting
201Contact to note
203Contact to task
82Contact to communication (SMS, WhatsApp, or LinkedIn message)
454Contact to postal mail
587Contact to cart
508Contact to order
178Contact to invoice
388Contact to payment
296Contact to subscription
907Contact to appointment
861Contact to course
883Contact to listing
799Contact to service
TYPE IDAssociation type
451Deal to deal
3Deal to contact
341Deal to company
5Deal to company (Primary)
27Deal to ticket
205Deal to call
209Deal to email
211Deal to meeting
213Deal to note
215Deal to task
86Deal to communication (SMS, WhatsApp, or LinkedIn message)
458Deal to postal mail
313Deal to deal split
19Deal to line item
176Deal to invoice
511Deal to order
392Deal to payment
63Deal to quote
300Deal to subscription
945Deal to appointment
863Deal to course
887Deal to listing
795Deal to service
TYPE IDAssociation type
452Ticket to ticket
16Ticket to contact
339Ticket to company
26Ticket to company (Primary)
28Ticket to deal
219Ticket to call
223Ticket to email
225Ticket to meeting
227Ticket to note
229Ticket to task
84Ticket to communication (SMS, WhatsApp, or LinkedIn message)
456Ticket to postal mail
32Ticket to thread
278Ticket to conversation
526Ticket to order
947Ticket to appointment
941Ticket to course
943Ticket to listing
797Ticket to service
TYPE IDAssociation type
578Lead to primary contact
608Lead to contact
610Lead to company
596Lead to call
598Lead to email
600Lead to meeting
854Lead to note
646Lead to task
602Lead to communication (SMS, WhatsApp, or LinkedIn message)
TYPE IDAssociation type
966Appointment to contact
908Appointment to company
944Appointment to deal
946Appointment to ticket
912Appointment to call
916Appointment to email
918Appointment to meeting
920Appointment to note
922Appointment to task
924Appointment to communication (SMS, WhatsApp, or LinkedIn message)
926Appointment to postal mail
TYPE IDAssociation type
860Course to contact
938Course to company
862Course to deal
940Course to ticket
866Course to call
870Course to email
872Course to meeting
874Course to note
876Course to task
878Course to communication (SMS, WhatsApp, or LinkedIn message)
880Course to postal mail
TYPE IDAssociation type
882Listing to contact
884Listing to company
886Listing to deal
942Listing to ticket
890Listing to call
894Listing to email
896Listing to meeting
898Listing to note
900Listing to task
902Listing to communication (SMS, WhatsApp, or LinkedIn message)
904Listing to postal mail
TYPE IDAssociation type
798Service to contact
792Service to company
794Service to deal
796Service to ticket
840Service to call
842Service to email
838Service to meeting
836Service to note
852Service to task
846Service to communication (SMS, WhatsApp, or LinkedIn message)
848Service to postal mail
TYPE IDAssociation type
194Call to contact
182Call to company
206Call to deal
220Call to ticket
913Call to appointment
867Call to course
891Call to listing
841Call to service
TYPE IDAssociation type
198Email to contact
186Email to company
210Email to deal
224Email to ticket
917Email to appointment
871Email to course
895Email to listing
843Email to service
TYPE IDAssociation type
200Meeting to contact
188Meeting to company
212Meeting to deal
226Meeting to ticket
919Meeting to appointment
873Meeting to course
897Meeting to listing
839Meeting to service
TYPE IDAssociation type
202Note to contact
190Note to company
214Note to deal
228Note to ticket
921Note to appointment
875Note to course
899Note to listing
837Note to service
TYPE IDAssociation type
453Postal mail to contact
459Postal mail to company
457Postal mail to deal
455Postal mail to ticket
927Postal mail to appointment
881Postal mail to course
905Postal mail to listing
849Postal mail to service
TYPE IDAssociation type
204Task to contact
192Task to company
216Task to deal
230Task to ticket
923Task to appointment
877Task to course
901Task to listing
853Task to service
TYPE IDAssociation type
81Communication (SMS, WhatsApp, or LinkedIn Message) to contact
87Communication (SMS, WhatsApp, or LinkedIn Message) to company
85Communication (SMS, WhatsApp, or LinkedIn Message) to deal
83Communication (SMS, WhatsApp, or LinkedIn Message) to ticket
925Communication (SMS, WhatsApp, or LinkedIn Message) to appointment
879Communication (SMS, WhatsApp, or LinkedIn Message) to course
903Communication (SMS, WhatsApp, or LinkedIn Message) to listing
847Communication (SMS, WhatsApp, or LinkedIn Message) to service
TYPE IDAssociation type
177Invoice to contact
179Invoice to company
175Invoice to deal
407Invoice to quote
622Invoice to subscription
815Invoice to payment link
517Invoice to order
986Invoice to ticket
409Invoice to line item
411Invoice to discount
413Invoice to fee
415Invoice to tax
541Invoice to commerce payment
691Invoice to payment schedule installment
679Invoice to data sync state
TYPE IDAssociation type
69Quote to contact
71Quote to company
64Quote to deal
67Quote to line item
286Quote to quote template
362Quote to discount
364Quote to fee
366Quote to tax
702Contact signer (for e-signatures)
733Quote to cart
408Quote to invoice
731Quote to order
398Quote to payment
304Quote to subscription
TYPE IDAssociation type
571Line item to abandoned cart
591Line item to cart
396Line item to commerce payment
20Line item to deal
368Line item to discount
410Line item to invoice
514Line item to order
759Line item to payment link
68Line item to quote
302Line item to subscription
565Upcoming line item to subscription
TYPE IDAssociation type
593Order to cart
507Order to contact
509Order to company
512Order to deal
519Order to discount
521Order to discount code
518Order to invoice
513Order to line item
523Order to payment
730Order to quote
516Order to subscription
726Order to task
525Order to ticket
TYPE IDAssociation type
586Cart to contact
588Cart to discount
590Cart to line item
592Cart to order
732Cart to quote
728Cart to task
594Cart to ticket

If you're using the v1 associations API, view the table below for information about IDs to use when associating records.

Association typeID
Contact to company1
Company to contact (default)2
Company to contact (all labels)280
Deal to contact3
Contact to deal4
Deal to company5
Company to deal6
Company to engagement7
Engagement to company8
Contact to engagement9
Engagement to contact10
Deal to engagement11
Engagement to deal12
Parent company to child company13
Child company to parent company14
Contact to ticket15
Ticket to contact16
Ticket to engagement17
Engagement to ticket18
Deal to line item19
Line item to deal20
Company to ticket25
Ticket to company26
Deal to ticket27
Ticket to deal28