Use HubSpot's CRM Associations API v4 to define a custom association type between two standard objects, create labeled associations in bulk, and query associations with label filters
POST /crm/v4/associations/{fromObjectType}/{toObjectType}/labels with a body containing 'label' (display name) and 'name' (internal API name) to create a custom association label between the two object types
Note the returned 'typeId' (the association type ID) for use in subsequent create and query calls
POST /crm/v4/associations/{fromObjectType}/{toObjectType}/batch/create with a 'inputs' array, each element containing 'from' (id), 'to' (id), and 'types' array with the association type ID and category 'USER_DEFINED'
GET /crm/v4/objects/{fromObjectType}/{objectId}/associations/{toObjectType} to retrieve all associations for a record and filter the response by 'associationTypes[].typeId' matching the custom type ID
DELETE /crm/v4/associations/{fromObjectType}/{toObjectType}/batch/labels to remove specific labeled associations while preserving unlabeled default associations
Known gotchas
Custom association labels are directional — a label created from Contact to Company has a different typeId than a label created from Company to Contact; querying in the wrong direction returns no results even if associations exist
HubSpot limits the number of custom association labels per object pair by plan tier; exceeding the limit returns a 429-style error with a message about label quota rather than a rate limit
When batch-creating associations with a custom label, if the default (unlabeled) association already exists between two records, adding a labeled association does not remove the default one — both coexist and must be managed independently
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