Upcoming Change: Associations API Enables Admins to Configure Association Limits

hseligson — Thu, 03 Aug 2023 14:20:39 GMT

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.

V3 Associations API

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

{

"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:

{

"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"

}

V4 Associations API

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 885123456, 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"

]

}

"startedAt": "2023-06-06T17:23:45.236Z",

"completedAt": "2023-06-06T17:23:45.281Z"

}

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

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

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

{

"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:

{

"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:

{

"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 here within the Developer Community forum.

Re: Upcoming Change: Associations API Enables Admins to Configure Association Limits

MFall13 — Thu, 03 Aug 2023 15:06:16 GMT

Will there be an option to set association count maxes via the objects UI in HubSpot settings?

Re: Upcoming Change: Associations API Enables Admins to Configure Association Limits

hseligson — Thu, 03 Aug 2023 15:08:54 GMT

@MFall13 - Certainly. A UI component will be added to facilitate this change, enabling users to set their own limits in-app. We plan to share more information about this feature once it's available in the public beta.

Re: Upcoming Change: Associations API Enables Admins to Configure Association Limits

Sachavskyi — Thu, 21 Mar 2024 16:44:57 GMT

@hseligson How should we know these limits via API? When I set 1-to-1 limit to the association, I get ONE_TO_MANY via API, but I want ONE_TO_ONE.

Re: Upcoming Change: Associations API Enables Admins to Configure Association Limits

hseligson — Fri, 22 Mar 2024 13:55:33 GMT

Hi @Sachavskyi - Thanks for sharing this! When setting association label limits, we don't actually change the cardinality on the association definition. We enforce a layer on top of cardinality via the maxToObjectIds/maxFromObjectIds fields which is what determines the relationship reflected in the Label Limits column of the association settings table.

You can also confirm whether a configuration has been applied by referencing the following fields: hasUserEnforcedMaxToObjectIds and hasUserEnforcedMaxFromObjectIds.

I hope this helps!

Re: Upcoming Change: Associations API Enables Admins to Configure Association Limits

Sachavskyi — Fri, 22 Mar 2024 15:12:08 GMT

@hseligson Where can I find these fields via API (hasUserEnforcedMaxToObjectIds and hasUserEnforcedMaxFromObjectIds)?

We enforce a layer on top of cardinality via the maxToObjectIds/maxFromObjectIds fields which is what determines the relationship reflected in the Label Limits column of the association settings table.

Why you can't send this (Label Limits) field via the API?

Re: Upcoming Change: Associations API Enables Admins to Configure Association Limits

hseligson — Tue, 26 Mar 2024 13:48:04 GMT

@Sachavskyi, I did some digging and apologize for providing misinformation. Unfortunately, certain details seem to be excluded from our v3/v4 Association APIs.
This includes not only maxToObjectIds/maxFromObjectIds but also hasUserEnforcedMaxToObjectIds /hasUserEnforcedMaxFromObjectIds .

It's on our engineering team's radar to add association configuration support to our public APIs. I will do my best to keep tabs on this update, as it will help many of our customers with this issue.

Re: Upcoming Change: Associations API Enables Admins to Configure Association Limits

Sachavskyi — Tue, 26 Mar 2024 17:12:08 GMT

@hseligson Thank you! Need this feature asap.

topic Upcoming Change: Associations API Enables Admins to Configure Association Limits in Developer Announcements

Upcoming Change: Associations API Enables Admins to Configure Association Limits

What's changing?

What does it mean for developers?

Additional association configuration behavior

When is this happening?

Re: Upcoming Change: Associations API Enables Admins to Configure Association Limits

Re: Upcoming Change: Associations API Enables Admins to Configure Association Limits

Re: Upcoming Change: Associations API Enables Admins to Configure Association Limits

Re: Upcoming Change: Associations API Enables Admins to Configure Association Limits

Re: Upcoming Change: Associations API Enables Admins to Configure Association Limits

Re: Upcoming Change: Associations API Enables Admins to Configure Association Limits

Re: Upcoming Change: Associations API Enables Admins to Configure Association Limits