canonical: https://jentic.com/apis/hubspot.com/hubspot-crm-associations-schema

# HubSpot CRM Associations Schema

The HubSpot CRM Associations Schema v4 API defines and reads the catalog of association types and labels available between CRM object pairs. It supports listing all configured association definitions, reading those for a specific object type pair, and creating, updating, or removing labels and configurations in batch. Use this API to set up the relationship vocabulary that the Associations API then operates on.

## For AI agents

Define association labels and configurations between CRM object types in HubSpot, including batch create, update, and purge operations. Useful for agents bootstrapping a custom CRM relationship model.

## Scope

Does not create or remove individual record links, mutate CRM records, or manage CRM properties - use for HubSpot association schema and label definitions only.

## Capabilities

- List all configured association definitions across the portal
- Read the association configuration for a specific from/to object pair
- Create, update, and remove association labels for an object pair
- Batch-create new association configurations between two object types
- Batch-update existing association configurations
- Purge association configurations no longer in use
- Read and manage labels under /crm/v4/associations/{fromObjectType}/{toObjectType}/labels

## Use cases

### Bootstrapping a Custom Object Relationship Model

When defining a new HubSpot custom object, declare the association types and labels it can hold to other CRM objects before any records are linked. POST /crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/create lets the agent register multiple definitions at once during portal setup.

Example prompt: POST /crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/create with the new association definitions for the custom object.

### Renaming Association Labels

Rename a label such as `Primary` to `Primary Contact` across the portal. PUT /crm/v4/associations/{fromObjectType}/{toObjectType}/labels updates the label definition itself rather than touching individual records.

Example prompt: PUT /crm/v4/associations/{fromObjectType}/{toObjectType}/labels with the labelTypeId and the new label name.

### Decommissioning Legacy Associations

When sunsetting a custom object, remove its association definitions to stop new records from being linked. POST /crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/purge clears the configuration in batch as part of a cleanup workflow.

Example prompt: POST /crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/purge with the legacy object types.

### Agent-Driven Schema Provisioning

Use Jentic to give a setup agent the ability to declare association types as part of a multi-step CRM bootstrap. The agent searches by intent for the right schema operation, loads the input shape, and executes - without writing HubSpot SDK code or exposing the OAuth token.

Example prompt: Use Jentic search 'create a HubSpot association label', load the POST /crm/v4/associations/{fromObjectType}/{toObjectType}/labels schema, and execute with the new label payload.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /crm/v4/associations/definitions/configurations/all | Read all association definitions |
| GET | /crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType} | Read association definitions for a pair |
| POST | /crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/create | Batch create configurations |
| POST | /crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/update | Batch update configurations |
| POST | /crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/purge | Batch purge configurations |
| GET | /crm/v4/associations/{fromObjectType}/{toObjectType}/labels | Read association labels |
| POST | /crm/v4/associations/{fromObjectType}/{toObjectType}/labels | Create an association label |

## Key resources

- **Association configurations** — Definitions of allowed association types under /crm/v4/associations/definitions/configurations.
- **Association labels** — Labels per object pair under /crm/v4/associations/{fromObjectType}/{toObjectType}/labels.

## Why Jentic

- **Setup:** Wiring HubSpot CRM Associations Schema by hand means registering an OAuth app or minting a private app token, targeting api.hubapi.com, and coding the definition configuration and label calls yourself. Through Jentic you install once, import CRM Associations Schema from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Associations Schema puts the object-type pair in the URL path (/crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}), so a rule can pin your agent to reading or creating definitions for one type pair. You choose the operations it may call, so purging a definition is not included unless you add it.
- **Credential handling:** Your HubSpot OAuth token or private app token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a HubSpot association label' or 'list association definitions', and Jentic returns the matching Associations Schema operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **HubSpot CRM Associations** — Create and remove the actual links between records using the schema defined here.
- **HubSpot CRM Custom Objects** — Define the custom object types that the association schema then describes.
- **HubSpot CRM Generic Objects** — Read or mutate the underlying CRM records that participate in associations.

## FAQ

### What authentication does the HubSpot Associations Schema API use?

OAuth 2.0 authorization code flow or a private app token in either the `private-app` or `private-app-legacy` header. Through Jentic, the credential lives encrypted in the vault and the agent only ever receives a scoped execution token.

### Can I create new association labels between two object types?

Yes. POST /crm/v4/associations/{fromObjectType}/{toObjectType}/labels creates a new label between the named object types, and the matching PUT and DELETE endpoints update or remove an existing label.

### What are the rate limits for the Associations Schema API?

Standard HubSpot API limits apply - roughly 100 requests per 10 seconds per OAuth app and daily caps on paid tiers. Schema operations are typically low-frequency, so this rarely becomes a bottleneck.

### How do I list every association definition through Jentic?

Search Jentic for `list HubSpot association definitions`, load the GET /crm/v4/associations/definitions/configurations/all schema, and execute. Install with `pip install jentic` and authenticate using `JENTIC_AGENT_API_KEY`.

### Does this API mutate individual association records?

No. This API defines the shape of allowed associations and labels. To create or remove a specific link between two records, use the CRM Associations API instead.

### Can I limit what my agent is allowed to do with the HubSpot Associations Schema API?

Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use. Since this API puts the object-type pair in the URL path (/crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}), you can pin the agent to reading or creating definitions for a single type pair. You also choose the exact operations it may call, so a batch purge of association configurations stays off limits unless you explicitly grant it.