Associations represent the relationships between objects and activities in the HubSpot CRM. You can use the associations endpoints to create, retrieve, update, or delete associations between records, or records and activities.
The association schema endpoints allow you to view the supported types of associations in your account, as well as create your own association types, and assign labels to your record relationships. 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.
HubSpot defined association types
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 type 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.
Create association types
You can create custom association types either in HubSpot or through the association schema API endpoint. You can create up to 10 association types between each object pairing (e.g. contacts and companies).
To create an association type through the API, 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.
You can find more details about this request in the Association schema endpoints tab at the top of this article.
Retrieve association types
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.
Associate records
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 set up default associations 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.
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 body, include the associationCategory
and associationTypeId
to indicate the type of association you want to create.
If you're creating unlabeled associations, you can use the default endpoints outlined in the section above which don't require the associationCategory
or associationTypeId
. If you're creating associations with a label, you can refer to this list of default type IDs, or you'll need to retrieve the custom association types between those objects. 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:
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.
TYPE ID | Association type |
---|---|
449
| Contact to contact (BETA) |
279
| Contact to company |
1
| Contact to company (Primary) |
4
| Contact to deal |
15
| Contact to ticket |
193
| Contact to call |
197
| Contact to email |
199
| Contact to meeting |
201
| Contact to note |
203
| Contact to task |
82
| Contact to communication (SMS, WhatsApp, or LinkedIn message) |
454
| Contact to postal mail |
TYPE ID | Association type |
---|---|
450
| Company to company (BETA) |
14
| Child to parent company (BETA) |
13
| Parent to child company (BETA) |
280
| Company to contact |
2
| Company to contact (Primary) |
342
| Company to deal |
6
| Company to deal (Primary) |
340
| Company to ticket |
25
| Company to ticket (Primary) |
181
| Company to call |
185
| Company to email |
187
| Company to meeting |
189
| Company to note |
191
| Company to task |
88
| Company to communication (SMS, WhatsApp, or LinkedIn message) |
460
| Company to postal mail |
TYPE ID | Association type |
---|---|
451
| Deal to deal (BETA) |
3
| Deal to contact |
341
| Deal to company |
5
| Deal to company (Primary) |
27
| Deal to ticket |
205
| Deal to call |
209
| Deal to email |
211
| Deal to meeting |
213
| Deal to note |
215
| Deal to task |
86
| Deal to communication (SMS, WhatsApp, or LinkedIn message) |
458
| Deal to postal mail |
TYPE ID | Association type |
---|---|
452
| Ticket to ticket (BETA) |
16
| Ticket to contact |
339
| Ticket to company |
26
| Ticket to company (Primary) |
28
| Ticket to deal |
219
| Ticket to call |
223
| Ticket to email |
225
| Ticket to meeting |
227
| Ticket to note |
229
| Ticket to task |
84
| Ticket to communication (SMS, WhatsApp, or LinkedIn message) |
456
| Ticket to postal mail |
TYPE ID | Association type |
---|---|
194
| Call to contact |
182
| Call to company |
206
| Call to deal |
220
| Call to ticket |
TYPE ID | Association type |
---|---|
198
| Email to contact |
186
| Email to company |
210
| Email to deal |
224
| Email to ticket |
TYPE ID | Association type |
---|---|
200
| Meeting to contact |
188
| Meeting to company |
212
| Meeting to deal |
226
| Meeting to ticket |
TYPE ID | Association type |
---|---|
204
| Task to contact |
192
| Task to company |
216
| Task to deal |
230
| Task to ticket |
TYPE ID | Association type |
---|---|
202
| Note to contact |
190
| Note to company |
214
| Note to deal |
228
| Note to ticket |
TYPE ID | Association type |
---|---|
453
| Postal mail to contact |
459
| Postal mail to company |
457
| Postal mail to deal |
455
| Postal mail to ticket |
TYPE ID | Association type |
---|---|
81
| Communication (SMS, WhatsApp, or LinkedIn Message) to contact |
87
| Communication (SMS, WhatsApp, or LinkedIn Message) to company |
85
| Communication (SMS, WhatsApp, or LinkedIn Message) to deal |
83
| Communication (SMS, WhatsApp, or LinkedIn Message) to ticket |
Thank you for your feedback, it means a lot to us.