> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

---
id: 077979ee-e454-47c6-98dd-0743e771db15
---

# Associations overview

> Learn how to create and manage associations between object records via the API.

Associations represent relationships between CRM records. For example, a contact associated with a company, or a deal linked to multiple contacts. The associations APIs are split into two distinct purposes:

[The Associations API](/api-reference/latest/crm/associations/associate-records/guide) is for working with specific records: associating a contact with a deal, retrieving all companies linked to a contact, or removing a relationship between two records.

[The Associations Schema API](/api-reference/latest/crm/associations/associations-schema/guide) is for configuring the structure of associations: creating a custom label (e.g., "Decision maker") for a contact-to-deal association type, updating limits on how many records of one type can be associated with another, or retrieving the list of available association type IDs to use in your API calls.

## Associate records during creation

When creating an object record, you can associate it with existing records in the same request by including an `associations` array in the request body. Each entry specifies the target record and the association type.

The following example request body would create a new contact and associate it with an existing company in a single request.

`POST` `/crm/objects/2026-03/contacts`

```json theme={null}
{
  "properties": {
    "firstname": "Jane",
    "lastname": "Smith",
    "email": "jsmith@example.com"
  },
  "associations": [
    {
      "to": { "id": 9001 },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 279
        }
      ]
    }
  ]
}
```

In this example, the new contact is associated with company ID `9001` using association type `279` (contact to company). For a full list of default association type IDs, see the [association types reference](/api-reference/legacy/crm/associations/associate-records#association-type-id-values).

## Associate existing records

To associate two records that already exist, make a `PUT` request to the Associations API specifying the from-object, to-object, and association type.

`PUT` `/crm/objects/2026-03/contacts/{contactId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}`

### Default associations

Most use cases only require a default association, which represents a standard relationship between two object types with no additional context. To set a default association, use a `HUBSPOT_DEFINED` association type ID from the [association types reference](/api-reference/legacy/crm/associations/associate-records#association-type-id-values).

The following example associates contact `101` with company `9001` using the default contact-to-company association type.

`PUT` `/crm/objects/2026-03/contacts/101/associations/companies/9001/279`

### Labeled associations

Labeled associations allow you to add context to a relationship — for example, marking a contact as a "Decision maker" or "Billing contact" on a company record. Labels are defined using the [Associations Schema API](/api-reference/latest/crm/associations/associations-schema/guide) and have their own association type IDs.

To set a labeled association, include the label's association type ID alongside (or instead of) the default type. The following example sets both the default association and a custom "Decision maker" label in a single request.

`POST` `/crm/objects/2026-03/associations/contacts/companies/batch/create`

```json theme={null}
{
  "inputs": [
    {
      "from": { "id": "101" },
      "to": { "id": "9001" },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 279
        },
        {
          "associationCategory": "USER_DEFINED",
          "associationTypeId": 42
        }
      ]
    }
  ]
}
```

For full details on available endpoints, see the [associate records guide](/api-reference/latest/crm/associations/associate-records/guide).

## Association type IDs

Both APIs rely on association type IDs to identify the kind of relationship between two object types. For a reference of all default HubSpot association type IDs, see the [association types reference](/api-reference/legacy/crm/associations/associate-records#association-type-id-values).