Skip to content
HubSpot Developer Changelog

Associations API Enables Admins to Configure Association Limits


An upcoming change to the Associations API gives customers with an Admin role control over the number of records associated with one another by introducing association configuration limits on an association type. Association configuration is the ability to control the number of records associated to each other.

What's changing?

Admins can set a max of 1 when configuring the number of records of one type that can be associated with one another. This association configuration will be reflected anywhere an association is created or edited, whether via the Associations API or within the HubSpot CRM Associations Settings for your HubSpot Pro account. 

Admins can set association configuration limits within the UI of their HubSpot account in the upcoming months when this change is live. The V4 Associations API will not yet provide the ability to set and update the association configuration limits.

What does it mean for developers?

Any limits set on the number of records with an association configuration will be validated. Those validations include the following restrictions based on the configured association subtype:

Subtype

Same-object type association definition

Cross-object type association definition

Unlabeled

Same limit both ways

Different limits for each direction

Symmetric labeled

Same limit both ways

Different limits for each direction

Asymmetric labeled

Different limits for each direction

Different limits for each direction

For same-object type associations (Unlabeled and Symmetric labeled), the limits are the same in both directions. However, for cross-object type associations and asymmetric labeled associations, the limits can vary in each direction.

When those validations are enforced, an error will occur and return a response message informing you of the error details. Association configurations are not enforced retroactively and will only take effect on new or future associations, not prior existing ones.

Below are the impacted HubSpot APIs and the expected error responses for user-enforced configuration limits and HubSpot-enforced limits when a configuration limit is exceeded.

Error response for when a default and or/user configuration limit is exceeded when creating new associations:

//Error response { "status": "error", "message": "One or more associations are invalid", "correlationId": "f243f6ac-8682-4e5c-92c1-e0b70ac1c9c2", "context": { "ASSOCIATION_USER_CONFIG_LIMIT_EXCEEDED": [ "Exceeded association limit of 1 for portalId 885123456, fromObjectId 51, associationType CONTACT_TO_DEAL" ], "associationTypeIdThatExceededLimit": [ "4" ], "limit": [ "1" ], "associationCategoryThatExceededLimit": [ "HUBSPOT_DEFINED" ] }, "category": "VALIDATION_ERROR" }

The expected error response for when a HubSpot-enforced configuration limit is exceeded when creating new associations:

//Error response { "status":"error", "message":"One or more associations are invalid", "correlationId":"f243f6ac-8682-4e5c-92c1-e0b70ac1c9c2", "context":{ "ASSOCIATION_LIMIT_EXCEEDED":[ "Exceeded association limit of 10000 for portalId 885123456, fromObjectId 51, associationType CONTACT_TO_DEAL" ], "associationTypeIdThatExceededLimit":[ "4" ], "limit":[ "10000" ], "associationCategoryThatExceededLimit":[ "HUBSPOT_DEFINED" ] }, "category":"VALIDATION_ERROR" }

The expected error response for when a user-enforced configuration limit is exceeded when creating new associations:

{ "status": "COMPLETE", "results": [], "numErrors": 1, "errors": [ { "status": "error", "category": "VALIDATION_ERROR", "subCategory": "crm.associations.ASSOCIATION_USER_CONFIG_LIMIT_EXCEEDED", "message": "Exceeded association limit of 1 for portalId 885030050, fromObjectId 51, associationCategory USER_DEFINED, associationTypeId 23", "context": { "associationSpec": [ "associationCategory USER_DEFINED, associationTypeId 23" ], "associationTypeIdThatExceededLimit": [ "23" ], "portalId": [ "885030050" ], "limit": [ "1" ], "fromObjectId": [ "51" ], "associationCategoryThatExceededLimit": [ "USER_DEFINED" ] } } ],

The expected error response for when a default and/or HubSpot-enforced configuration limit is exceeded when creating new associations:

{ "status": "COMPLETE", "results": [], "numErrors": 1, "errors": [ { "status": "error", "category": "VALIDATION_ERROR", "subCategory": "crm.associations.ASSOCIATION_LIMIT_EXCEEDED", "message": "Exceeded association limit of 10000 for portalId 885123456, fromObjectId 51, associationCategory USER_DEFINED, associationTypeId 23", "context": { "associationSpec": [ "associationCategory USER_DEFINED, associationTypeId 23" ], "associationTypeIdThatExceededLimit": [ "23" ], "portalId": [ "885030050" ], "limit": [ "10000" ], "fromObjectId": [ "51" ], "associationCategoryThatExceededLimit": [ "USER_DEFINED" ] } } ],

Note: Included within the error message are two new fields subCategory and context to differentiate the two different errors between user-enforced configuration limits and HubSpot-enforced limits.

  • V3 CRM Objects Association API (v3/objects/{objectType})

for Companies, Custom Objects, and other similar object types.

  1. When creating new objects with associations.
  2. When creating new associations on objects.

The expected error response for when a user-enforced configuration limit is exceeded:

//Error response { "status":"error", "message":"One or more associations are invalid", "correlationId":"1f79c839-57e1-4d02-86a6-860f01660527", "context":{ "ASSOCIATION_USER_CONFIG_LIMIT_EXCEEDED":[ "Exceeded association limit of 1 for portalId 885123456, fromObjectId 51, associationType CONTACT_TO_DEAL" ], "associationTypeIdThatExceededLimit":[ "4" ], "limit":[ "1" ], "associationCategoryThatExceededLimit":[ "HUBSPOT_DEFINED" ] }, "category":"VALIDATION_ERROR" }

The expected error response for when a default and/or HubSpot-enforced configuration limit is exceeded:

//Error response { "status":"error", "message":"One or more associations are invalid", "correlationId":"1f79c839-57e1-4d02-86a6-860f01660527", "context":{ "ASSOCIATION_LIMIT_EXCEEDED":[ "Exceeded association limit of 10000 for portalId 885123456, fromObjectId 51, associationType CONTACT_TO_DEAL" ], "associationTypeIdThatExceededLimit":[ "4" ], "limit":[ "10000" ], "associationCategoryThatExceededLimit":[ "HUBSPOT_DEFINED" ] }, "category":"VALIDATION_ERROR" }

The expected error response when merging an object of the same type will be returned to you, stating the following message:

//Error response { "status":"error", "message":"Association configuration limits are exceeded in portal 885123456 when merging 8234 into 23 of object type 0-1", "correlationId":"b123d456-c7ad-8910-bff1-b2a345c6b78", "category":"VALIDATION_ERROR" }

Note: When a record with an association configuration is merged specifically with a HubSpot V3 Object API, the new record will have the combined associations of both records. HubSpot will validate against the association configuration limits set by the Admin. Should there be too many combined associated records, the merge will fail.

Additional association configuration behavior

  • Users can set configuration limits 1 in both association directions when cardinality is ONE_TO_MANY. This enables one-to-one relationships.
  • A single association will not override another when a max record limit is met. Instead, the association will not succeed.
  • The user cannot set a max limit of “0”.
  • Some associations will succeed if records are associated in bulk with a BATCH request, while others will fail depending on their configuration. If there is a failure, an error response message will be returned informing which associations have failed.

When is this happening?

The implementation of this change is scheduled to take place between September and October of 2023. We will provide further updates on this announcement once a confirmed date is available.

Please let us know if you have any feedback or questions by joining the conversation in the Developer Community forum.