Define a custom association label via POST to /crm/v4/associations/{fromObjectType}/{toObjectType}/labels with a label string and an optional inverseLabel for the reverse direction
Note the returned typeId values for both directions of the label — you will need these when creating association records
Create an association with a specific label by POST to /crm/v4/objects/{fromObjectType}/{fromObjectId}/associations/{toObjectType}/{toObjectId} with a JSON body containing an associationTypes array where each entry specifies associationCategory (HUBSPOT_DEFINED or USER_DEFINED) and associationTypeId
Retrieve all associations with their labels for a given object via GET /crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}; the response includes label metadata alongside each association
To batch-create labeled associations, POST to /crm/v4/associations/{fromObjectType}/{toObjectType}/batch/create with an inputs array where each entry specifies from.id, to.id, and the associationTypes array
Remove a specific label from an association without deleting the association entirely by using the label-specific DELETE endpoint rather than the full association DELETE
Known gotchas
Association labels are directional — a label defined from Contact to Company does not automatically exist in the Company to Contact direction unless inverseLabel is specified during label creation
HubSpot enforces a maximum number of custom association labels per portal (check current documentation for the exact limit); exceeding this limit causes label creation to fail with a 400 error that references the limit rather than a validation issue
Creating an association with a USER_DEFINED label also creates an unlabeled association of the default HUBSPOT_DEFINED type in the background; deleting only the labeled association leaves the default association intact — delete both if a clean removal is required
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp