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.
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.
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:
The expected error response for when a HubSpot-enforced configuration limit is exceeded when creating new associations:
The expected error response for when a user-enforced configuration limit is exceeded when creating new associations:
The expected error response for when a default and/or HubSpot-enforced configuration limit is exceeded when creating new associations:
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/objects/{objectType})for Companies, Custom Objects, and other similar object types.
The expected error response for when a user-enforced configuration limit is exceeded:
The expected error response for when a default and/or HubSpot-enforced configuration limit is exceeded:
The expected error response when merging an object of the same type will be returned to you, stating the following message:
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.
ONE_TO_MANY. This enables one-to-one relationships.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.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.