Auto-associations API (BETA)

Scope requirements

When a user logs a call, sends an email, books a meeting, or creates a note or task, HubSpot can automatically associate that activity with related CRM records. For example, you can automatically associate a call logged on a contact record with the contact’s primary associated company. Use the activity auto-associations API to read and update the rules that control this behavior. Learn more about setting up automatic associations for records and activities in HubSpot.

Understand auto-association settings

Subject and target objects

When viewing and updating activity auto-association settings, the subjectObject and targetObject refer to the direction of the automatic association.

subjectObject: the object where the activity originated (i.e. was created or logged).
targetObject: the object with which the activity associates.

For example, when a call is logged on a contact record, your settings are configured to automatically associate the call to the contact’s associated primary company. In this example, contacts (0-1) is the subjectObject and companies (0-2) is the targetObject.

Association customization values

The associationCustomization field controls how activities are automatically associated with a target object. The following values are available depending on the combination of objects and activity type. Use the retrieve settings endpoint to check the valid options values for a given combination.

Value	Description
`NO_LOGGING`	Do not auto-associate activities of this type with the target object.
`PRIMARY_COMPANY`	Auto-associate with the primary company only. Only available when the target object is companies (`0-2`).
`ONE_MOST_RECENTLY_ASSOCIATED`	Auto-associate with the most recently associated record of this type.
`FIVE_MOST_RECENTLY_ASSOCIATED`	Auto-associate with the five most recently associated records of this type.
`X_MOST_RECENTLY_ASSOCIATED`	Auto-associate with all associated records of this type.

Retrieve auto-association settings

Retrieve current settings for an object

To retrieve the current auto-association settings for a specific object, make a GET request to /crm/auto-associations/2027-03-beta/{subjectObjectTypeId}. For example, to retrieve auto-association settings for activities logged on contacts, make a GET request to /crm/auto-associations/2027-03-beta/0-1. Your response will look similar to the following:

{
  "results": [
    {
      "selectedBehavior": {
        "subjectObjectTypeId": "0-1",
        "engagementType": "CALL",
        "targetObjectTypeId": "0-1",
        "associationCustomization": "X_MOST_RECENTLY_ASSOCIATED",
        "id": "0-1_CALL_0-1"
      },
      "options": [
        "NO_LOGGING",
        "X_MOST_RECENTLY_ASSOCIATED",
        "ONE_MOST_RECENTLY_ASSOCIATED",
        "FIVE_MOST_RECENTLY_ASSOCIATED"
      ],
      "isValidAssociationType": true,
      "id": "0-1_CALL_0-1"
    },
    {
      "selectedBehavior": {
        "subjectObjectTypeId": "0-1",
        "engagementType": "CALL",
        "targetObjectTypeId": "0-2",
        "associationCustomization": "NO_LOGGING",
        "id": "0-1_CALL_0-2"
      },
      "options": [
        "NO_LOGGING",
        "PRIMARY_COMPANY",
        "X_MOST_RECENTLY_ASSOCIATED",
        "ONE_MOST_RECENTLY_ASSOCIATED",
        "FIVE_MOST_RECENTLY_ASSOCIATED"
      ],
      "isValidAssociationType": true,
      "id": "0-1_CALL_0-2"
    },
    {
      "selectedBehavior": {
        "subjectObjectTypeId": "0-1",
        "engagementType": "CALL",
        "targetObjectTypeId": "0-125",
        "associationCustomization": "NO_LOGGING",
        "id": "0-1_CALL_0-125"
      },
      "options": [
        "NO_LOGGING",
        "X_MOST_RECENTLY_ASSOCIATED",
        "ONE_MOST_RECENTLY_ASSOCIATED",
        "FIVE_MOST_RECENTLY_ASSOCIATED"
      ],
      "isValidAssociationType": false,
      "id": "0-1_CALL_0-125"
    }
  ]
}

The response contains a results array. Each item in the array represents one auto-association setting and includes the following fields:

Field	Description
`id`	Composite ID for this setting in the format `{subjectObjectTypeId}_{engagementType}_{targetObjectTypeId}` (e.g., `0-1_CALL_0-2`).
`selectedBehavior`	The current behavior for this combination of subject object, activity type, and target object. Contains `subjectObjectTypeId`, `engagementType`, `targetObjectTypeId`, `associationCustomization` (the selected option), and `id`.
`options`	The available `associationCustomization` values for this combination. Learn more about association customization values.
`isValidAssociationType`	Whether the subject-to-target association type is valid for auto-association. If `false`, the setting cannot be used.

Retrieve default settings for an object

To view the system defaults for an object, make a GET request to /crm/auto-associations/2027-03-beta/{subjectObjectTypeId}/defaults. For example, to retrieve the default activity auto-association settings for contacts, make a GET request to /crm/auto-associations/2027-03-beta/0-1/defaults. Your response will look similar to the following:

{
  "results": [
    {
      "subjectObjectTypeId": "0-1",
      "engagementType": "CALL",
      "targetObjectTypeId": "0-1",
      "associationCustomization": "NO_LOGGING",
      "id": "0-1_CALL_0-1"
    },
    {
      "subjectObjectTypeId": "0-1",
      "engagementType": "CALL",
      "targetObjectTypeId": "0-123",
      "associationCustomization": "NO_LOGGING",
      "id": "0-1_CALL_0-123"
    }
  ]
}

The response contains a results array. Each entry includes subjectObjectTypeId, engagementType, targetObjectTypeId, associationCustomization, and id for the default behavior.

Update auto-association settings

To update activity auto-association settings for one or more combinations of subject object, activity type, and target object, make a POST request to /crm/auto-associations/2027-03-beta/batch/upsert. In your request body, include an associationCustomizationsToUpsert array. Each item in the array represents one setting to upsert:

Field	Type	Description
`subjectObjectTypeId`	String	The subject object type ID (e.g., `0-1` for contacts).
`engagementType`	String	The activity type. Values: `CALL`, `EMAIL`, `MEETING`, `NOTE`, `TASK`.
`targetObjectTypeId`	String	The target object type ID (e.g., `0-2` for companies, `0-3` for deals, `0-5` for tickets).
`associationCustomization`	String	The auto-association behavior to apply. Learn more about association customization values.

For example, to update the auto-association behavior for calls and emails logged on contacts, make a POST request to /crm/auto-associations/2027-03-beta/batch/upsert with the following request body:

{
  "associationCustomizationsToUpsert": [
    {
      "subjectObjectTypeId": "0-1",
      "engagementType": "CALL",
      "targetObjectTypeId": "0-2",
      "associationCustomization": "PRIMARY_COMPANY"
    },
    {
      "subjectObjectTypeId": "0-1",
      "engagementType": "EMAIL",
      "targetObjectTypeId": "0-3",
      "associationCustomization": "FIVE_MOST_RECENTLY_ASSOCIATED"
    }
  ]
}

A successful response returns the updated settings in a results array which will look similar to the following:

{
  "completedAt": "2026-08-14T21:09:32.335Z",
  "status": "COMPLETE",
  "startedAt": "2026-08-14T21:09:32.335Z",
  "results": [
    {
      "subjectObjectTypeId": "0-1",
      "engagementType": "CALL",
      "targetObjectTypeId": "0-2",
      "associationCustomization": "PRIMARY_COMPANY",
      "id": "0-1_CALL_0-2"
    },
    {
      "subjectObjectTypeId": "0-1",
      "engagementType": "EMAIL",
      "targetObjectTypeId": "0-3",
      "associationCustomization": "FIVE_MOST_RECENTLY_ASSOCIATED",
      "id": "0-1_EMAIL_0-3"
    }
  ]
}

For this example, the following settings were updated:

A call logged on a contact record will automatically associate only with the contact’s primary associated company.
An email logged on a contact record will automatically associate with the contact’s five most recently associated deals.

​Understand auto-association settings

​Subject and target objects

​Association customization values

​Retrieve auto-association settings

​Retrieve current settings for an object

​Retrieve default settings for an object

​Update auto-association settings