Association Labels in HubSpot: A Guide for Developers

Knowing that a contact is linked to a company doesn’t tell you how, is this person the decision-maker, the billing contact, or someone who filled out a form once and never replied? HubSpot association labels add that missing context directly onto the relationship between two CRM records. This hubspot association labels guide covers what association labels hubspot actually are, how the hubspot association labels api works with real endpoints, how paired labels hubspot handles two-directional relationships, and three details most introductory guides skip entirely: the feature isn’t available on every HubSpot tier, there’s a hard hubspot association label limits cap on how many labels you can create per object pair, and HubSpot’s own current rate-limit numbers are different from what a lot of older guides still repeat.

What Are HubSpot Association Labels?

Association labels are the human-readable names HubSpot attaches to the relationship between two CRM records, not just that a contact and a company are connected, but what kind of connection it is (“Decision Maker,” “Billing Contact,” “Reseller”). Every association has an underlying associationTypeId; the label is what a user actually sees in the HubSpot UI and what the associations API returns. Labels are either HUBSPOT_DEFINED (built-in defaults like “Primary company”) or USER_DEFINED (custom labels your team creates), and the feature requires a Professional or Enterprise subscription, it is not available on Free or Starter tiers.

What Association Labels Actually Are

Every association between two CRM records in HubSpot, a contact and a company, a deal and a contact, has an underlying association type, identified by an associationTypeId, forming the backbone of how hubspot crm associations actually work, as HubSpot’s own associations schema documentation lays out in full. A label is the human-readable name attached to that type, visible in the HubSpot UI and returned through the hubspot associations API. HubSpot distinguishes two categories of hubspot association types: HUBSPOT_DEFINED labels are built-in defaults (like the primary company association, the default relationship type linking a contact to its main company record), and USER_DEFINED labels are custom association labels hubspot teams create, “Decision Maker,” “Billing Contact,” “Contract worker”, to reflect crm object relationships specific to your actual sales or service process.

Some labels are paired labels, meaning the relationship reads differently depending on direction: a contact might be labeled “Employee” pointing to a company, while the company’s inverseLabel pointing back to that contact reads “Employer.” Getting this pairing right matters for how the relationship displays on both sides of the record, and worth knowing upfront: a paired label counts as only one label against your per-object-pair limit, covered below.

What Tier of HubSpot Has Association Labels? A Real Limitation Worth Knowing Upfront

Association labels require a Professional or Enterprise subscription, specifically on Marketing Hub, Sales Hub, Service Hub, Data Hub, Content Hub, or Smart CRM. Free tier and Starter tier accounts are not supported. This is a genuine hubspot api limits restriction that trips up developers building against a lower-tier account during initial development and testing. Confirm your target account’s actual subscription tier before assuming this feature is available, rather than discovering the restriction mid-build.

How Many Association Labels Can You Actually Create?

This is the detail missing from almost every guide on this topic, including, until now, this one: HubSpot caps custom association labels at 50 per object pair (e.g., Contact-to-Deal, Contact-to-Contact). A paired label, the “Employee”/”Employer” example above, counts as a single label toward that cap, not two. If you’re designing a labeling scheme for a large sales org with many role types (Decision Maker, Champion, Economic Buyer, Technical Evaluator, End User, Procurement, Legal Reviewer…), 50 sounds generous until a few teams start adding their own variants independently, worth governing centrally rather than letting labels sprawl.

Retrieving Association Labels

To view existing association types between two object types, make a GET request:

GET /crm/associations/{version}/{fromObjectType}/{toObjectType}/labels

 

For example, to view all association types from contacts to companies:

GET /crm/associations/{version}/contacts/companies/labels

 

This returns an array of the association types currently configured between those two objects, including both HubSpot-defined defaults and any custom labels your team has created. HubSpot’s current approach to hubspot api versioning versions this hubspot rest api by date rather than by a simple v1/v2/v3/v4 number, confirm the current dated version against HubSpot developer documentation before hardcoding one, since the hubspot association schema changes on HubSpot’s release schedule, not yours.

Creating and Updating Custom Association Labels

This hubspot association labels api example covers both directions developers actually need: creating a new custom label and renaming an existing one are two different requests, and conflating them is an easy mistake:

• To create a new custom label, make a POST request to /crm/associations/{version}/{fromObjectType}/{toObjectType}/labels with the label text (and inverseLabel if it’s a paired label).
• To update an existing label’s display name, the underlying associationTypeId stays fixed, only the label text changes, make a PUT request to the same endpoint, including the associationTypeId and the new label value. Renaming “Contractor” to “Contract worker,” for instance, is a matter of passing the existing ID with the updated text, not recreating the association type from scratch. If you’re updating a paired label, include a new value for inverseLabel as well, so both directions of the relationship stay consistent.

Applying Labels to Records: Associate, Read, and Remove

Defining a label and applying it are separate steps, and the record-level endpoints live under a different path family than the label-definition endpoints above. Per HubSpot’s current associate-records documentation:

Task	Method and path	Notes
Associate two records with a label	PUT /crm/objects/{version}/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}	Body carries associationCategory (HUBSPOT_DEFINED or USER_DEFINED) and the label’s associationTypeId
Batch associate with labels	POST /crm/associations/{version}/{fromObjectType}/{toObjectType}/batch/create	Up to 2,000 inputs per request
Associate with the default, unlabeled type	PUT /crm/objects/{version}/{fromObjectType}/{fromObjectId}/associations/default/{toObjectType}/{toObjectId}	Batch version: …/batch/associate/default
Read a record’s associations	GET /crm/objects/{version}/{fromObjectType}/{objectId}/associations/{toObjectType}	Batch read: …/batch/read, up to 1,000 inputs
Remove all associations between two records	DELETE /crm/objects/{version}/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}	Batch: …/batch/archive, 100 unique from inputs

One trap worth flagging: HubSpot’s documentation warns that deleting the default unlabeled association type removes all other associations between those records. Removing a label (next section) is the safe operation; removing the default type is not.

Removing Labels From Associations

You can remove a specific label from an association without deleting the underlying association itself, the relationship between the two records persists, just without that particular categorization. This works through a batch endpoint:

POST /crm/associations/{version}/{fromObjectType}/{toObjectType}/batch/labels/archive

 

The request body includes the record IDs along with the associationTypeId and category of the label to remove. This specific batch endpoint is capped at 100 inputs per request, worth designing your integration around if you’re processing bulk data rather than individual record updates. That’s not HubSpot’s only batch limit, though, and the other two matter just as much for integration design (see the table below).

Deleting Custom Association Labels

To permanently delete a custom label definition:

DELETE /crm/associations/{version}/{fromObjectType}/{toObjectType}/labels/{associationTypeId}

 

One important constraint: a label still in active use on existing associations needs to be removed from those associations first, before the label definition itself can be deleted. Default association types, including the built-in “Primary company” label, cannot be deleted at all, only custom, user-defined labels support this operation. Every operation above, GET, POST, PUT, and this DELETE request, hits the same family of API endpoint paths, which is exactly why getting the batch size limit and daily request limit right for each one (next section) matters more than it looks like it would from a single test call.

Setting Association Limits

Beyond labeling, HubSpot lets you configure how many associations of a given type a record can have, useful for enforcing real business rules directly at the data layer rather than relying on manual discipline. For example, you could configure a deal to allow a maximum of five associated contacts, with only one of those contacts permitted to carry the “Point of contact” label. This is set through the definition configuration endpoints, specifying the category, typeId, and maxToObjectIds for the limit you want enforced.

Monitoring Association Usage at Scale

Here’s how to monitor hubspot association usage before it becomes an outage instead of a planning task: HubSpot enforces real technical limits, separate from the hubspot association limits set per association type, on how many associations a single record can accumulate, a company associated with tens of thousands of contacts, for instance, will eventually hit a hard ceiling. Rather than discovering this when a write operation suddenly fails, the associations API provides a way to proactively check: a POST request to the hubspot high-usage report endpoint generates a report of records using 80% or more of their association limit, emailed to a specified user. For a company with a 50,000-contact association limit, that means the report flags it once it crosses roughly 40,000 associated contacts, early enough to plan a data cleanup or request a limit increase before actually hitting the wall. Checking this report on a schedule, rather than only after something breaks, is the same proactive monitoring discipline that matters for any production integration, not a HubSpot-specific concern.

HubSpot API Rate Limits by Tier (Corrected)

Hubspot api rate limits and hubspot api usage limits get confused with each other constantly, and this specific figure is worth getting exactly right, because an older or AI-generated summary is likely to get it wrong: per HubSpot’s current API usage documentation, daily request limits for privately distributed apps scale by subscription tier, and Professional and Enterprise do not share the same default, Free and Starter accounts get 250,000 requests/day, the hubspot professional tier gets 625,000/day, and the hubspot enterprise tier gets 1,000,000/day. Accounts can purchase up to two rate-limit increases, each adding 1,000,000 requests/day on top of the base subscription, so the real ceiling is your base limit plus up to 2,000,000 more, not a flat 1,000,000 total. For integrations processing large volumes of association updates, designing around batch endpoints (rather than one request per record) is the practical way to stay comfortably under these limits regardless of tier.

Batch Operation Limits at a Glance

The hubspot batch label operations limit is only one of four batch ceilings worth knowing, and a detail no competing guide on this topic currently lists in one place:

Batch operation	Maximum inputs per request
Create associations	2,000
Read associations	1,000
Archive/remove all associations between records	100
Remove a specific label from associations	100

Designing an integration around the smallest of these (100) rather than assuming the 2,000-input create limit applies everywhere is the mistake that surfaces in production, not in testing, testing rarely exercises the archive/label-removal path at real volume.

Common Real-World Use Cases

Hubspot sales qualification labeling: A single company might have a dozen associated contacts, but only one or two actually matter for closing a deal. A decision maker label hubspot sales teams actually use, alongside “Champion” or “Economic Buyer,” against their hubspot company contact association lets a sales team filter and prioritize outreach directly from the CRM data structure, rather than relying on notes or memory.

Support and billing separation: For B2B accounts where the person managing the relationship isn’t the person who receives invoices, a billing contact label hubspot teams apply alongside “Primary Contact” against the same company keeps that distinction structurally clear rather than buried in a free-text field someone has to remember to check.

Multi-stakeholder deal tracking: Complex enterprise deals often involve several contacts playing different roles, technical evaluator, budget approver, end user. Custom association labels on a hubspot deal contact association let a team model that structure directly, rather than approximating it with generic hubspot crm object associations that don’t distinguish role.

Vendor and partner relationships hubspot teams rely on: Companies associated with other companies (a reseller, an integration partner, a referral source) benefit from the same labeling approach, a plain company-to-company association doesn’t communicate why the two are connected, but a labeled one does.

Each of these patterns uses the same underlying mechanism covered above, the specific value is in choosing labels that map to how your actual team already thinks about these relationships, not inventing new terminology nobody adopts.

Building Real HubSpot Integrations

This hubspot developer api guide is meant to be used alongside HubSpot’s own reference docs, not instead of them. Getting association labels, limits, and hubspot batch operations working together correctly in a real integration, not just a single hubspot batch api call in isolation, is genuine development work, the same category of custom application development work that shows up constantly in real CRM and data-integration projects. At any real volume, that usually means routing requests through a proper middleware api integration layer rather than firing calls directly from application code, the batch-size table above is exactly the kind of per-endpoint constraint that layer needs to enforce consistently, not re-discover separately in every service that touches the associations API.

Related Topic Clusters: Where CRM Associations Connect to the Rest of Your Stack

Association labels are rarely the end of a project. Once relationship context lives in the CRM, it tends to feed three other areas, each covered in a separate Triotech guide:

• API integration architecture: Rate limits and batch ceilings are enforced best in one routing layer: Middleware vs. API Gateways: Key Differences and When to Use Each.
• AI agents that read and write CRM records: A “Decision Maker” label is exactly the kind of structured context an agent needs before drafting outreach or updating a deal, and the same tier, rate-limit, and permission constraints apply to every tool call it makes. See the enterprise agentic AI reference architecture and the comparison of Amazon Bedrock AgentCore, Microsoft Foundry Agent Service, and Agent Runtime.
• Grounding AI on CRM data: Labeled associations (who is the billing contact, who approves budget) are private company data that retrieval systems should respect: RAG Architecture for Private Company Data covers permission-aware retrieval, and Bedrock Guardrails vs. Azure AI Content Safety vs. Google Model Armor covers the safety layer around it.
• Integration cost and operations: High-volume sync jobs carry real infrastructure spend: FinOps Cloud Cost Optimization.
• Who builds and secures it: Managed DevOps and Cloud Security Company and the wider AI Engineering Guides series.

Who Builds This

This guide reflects how Triotech Systems actually builds HubSpot integrations for clients, not a rewrite of HubSpot’s own documentation, but the practical constraints (tier gating, the 50-label cap, the real batch limits, the corrected rate limits above) that only show up once you’re actually building against the API rather than reading about it. If you’re building a HubSpot integration and want it done properly, reach out.

Frequently Asked Questions

What are association labels in HubSpot? 

The human-readable names HubSpot attaches to the relationship between two CRM records, not just that a contact and a company are connected, but what kind of connection it is, like “Decision Maker” or “Billing Contact.”

What’s the difference between association type and association label HubSpot developers should know? 

The association type, identified by associationTypeId, is the underlying structural relationship. The label is the human-readable name attached to that type, visible in HubSpot’s interface and API responses, the type is the mechanism, the label is what a user actually sees.

What HubSpot tier includes association labels? 

Professional and Enterprise accounts specifically, Marketing Hub, Sales Hub, Service Hub, Data Hub, Content Hub, or Smart CRM. This isn’t available on Free or Starter tiers, a common point of confusion for developers testing against a lower-tier account.

How many association labels can you create in HubSpot? 

Up to 50 custom labels per object pair (e.g., Contact-to-Deal). A paired label counts as one label toward that limit, not two.

How to create custom association labels in HubSpot? 

Make a POST request to /crm/associations/{version}/{fromObjectType}/{toObjectType}/labels with the label text and, for a paired label, the inverseLabel value.

How to update association labels via API? 

Make a PUT request to the same labels endpoint, including the existing associationTypeId and the new label text, the type ID itself stays fixed, only the display text changes.

How to delete association labels in HubSpot, and can you delete a default label like “Primary company”? 

Default, HubSpot-defined association types cannot be deleted. Only custom, user-defined labels support deletion through the DELETE endpoint above, and even then, the label must first be removed from any active associations using it, that’s how to remove a label from an association in HubSpot without deleting the label definition itself.

What is a paired label in HubSpot associations? 

A label where the relationship reads differently depending on direction, for example, a contact labeled “Employee” toward a company, with the company’s inverse label reading “Employer” back toward that contact.

What’s the maximum batch size for association operations? 

It depends on the operation: 2,000 inputs for batch create, 1,000 for batch read, and 100 for batch archive or batch label removal. Design integrations around the smallest limit that applies to the operation you’re using.

What are HubSpot’s current API rate limits by tier? 

250,000 requests/day for Free and Starter, 625,000/day for Professional, and 1,000,000/day for Enterprise, with up to two purchasable increases of 1,000,000 each on top of the base subscription. These hubspot api rate limits by tier are frequently reported incorrectly as a flat “500,000/day” for both Professional and Enterprise, which is outdated.

How many associations can a HubSpot record have, and how do you monitor it? 

It depends on the object type and your account’s configuration. HubSpot enforces both technical and subscription-based limits, and the associations API provides a high-usage report specifically for identifying records approaching those limits before they’re hit, the practical answer to how to monitor HubSpot association usage at scale.

Where’s a good HubSpot developer guide to CRM associations overall, not just labels? 

This hubspot developer api guide covers labels specifically; for the broader hubspot developer guide to crm associations, associating and disassociating records themselves, not just labeling them, HubSpot’s own associations schema documentation (linked above) is the canonical reference to pair with this guide.