> ## 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: 6c937145-5b2b-4723-9fff-5c4e10245f4a --- # Auto-associations API (BETA) > Read and update how HubSpot automatically associates activities with CRM objects. export const BetaDisclaimerBanner = () => This functionality is currently in beta. By participating in this beta, you agree to HubSpot's Developer Terms and Developer Beta Terms. Note that the functionality is still under active development and is subject to change based on testing and feedback. ; export const RequiredIndicator = () => { return required ; }; export const ScopesList = ({scopes = [], description = "This API requires one of the following scopes:"}) => { if (!scopes || scopes.length === 0) { return null; } const sortedScopes = scopes.sort((a, b) => a.localeCompare(b)); return
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
; }; 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](https://knowledge.hubspot.com/object-settings/configure-automatic-activity-associations). ## 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](#retrieve-current-settings-for-an-object) 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: ```json theme={null} { "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](#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: ```json theme={null} { "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](#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: ```json theme={null} { "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: ```json theme={null} { "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.