Skip to main content
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.
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.

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.

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:
The response contains a results array. Each item in the array represents one auto-association setting and includes the following fields:

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:
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: 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:
A successful response returns the updated settings in a results array which will look similar to the following:
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.
Last modified on September 9, 2026