Short answer
Labels are association types with their own typeId. Get them with GET /crm/v4/associations/contact/deal/labels, then send associationCategory (HUBSPOT_DEFINED for default labels, USER_DEFINED for custom) and associationTypeId when you associate. Batch create takes up to 2,000 inputs per request. Including only the new label replaces an existing one, so include both to append. The v3 associations API cannot create or edit labels.
1. Look up the label
GET https://api.hubapi.com/crm/v4/associations/contact/deal/labelsThe response lists each label with its typeId and category. Custom label IDs differ per account, so do not hard-code them across portals.
2. Associate in bulk
POST https://api.hubapi.com/crm/v4/associations/contact/deal/batch/create
{
"inputs": [
{
"from": { "id": "CONTACT_ID" },
"to": { "id": "DEAL_ID" },
"types": [ { "associationCategory": "USER_DEFINED", "associationTypeId": 36 } ]
}
]
}3. Things to watch
- Replace versus append: send all labels you want kept.
- Association limits per record pair still apply.
- Default type IDs are listed in the docs. Object type IDs are in HubSpot object type IDs.
- In the UI, see association labels.