What's happening?
In March, we released a new collection of v3 CRM APIs into general availability.
The CRM APIs return association data representing the relationships between objects in the HubSpot CRM (contacts, companies, deals, quotes, line items, and tickets). It helps to manage and define those relationships, allowing you to create a more holistic picture of your customer interactions.
If your HubSpot app or custom integration is using association data then this breaking change will affect you.
As we grow and scale CRM objects, the volume of association data being returned has the potential to affect the HubSpot platform’s performance. To guard against this, we are changing the way we return association data in the response body for the CRM endpoints listed below.
Full list of affected APIs
- GET /crm/v3/objects/{objectType}
- GET /crm/v3/objects/{objectType}/{objectId}
- GET /crm/v3/objects/{objectType}/{objectId}/associations/{toObjectType}
- POST /crm/v3/associations/{fromObjectType}/{toObjectType}/batch/read
- PUT/crm/v3/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}/{associationType}
Here’s how we currently return CRM association data.
Right now, associated object IDs for multiple association types are returned in the response body. See example below:
Request:
GET https://api.hubapi.com/crm/v3/objects/deal/DealID?portalId=XXXXXX&properties=amount&associations=contact&associations=company
Response:
Note the long list of associations returned in the response. In the future, we will be returning association data using a new pagination system. See example below:
Here’s an example of CRM association data returned using pagination:
Request:
GET https://api.hubapi.com/crm/v3/objects/deal/DealID?portalId=XXXXXXX&properties=amount&associations=contact&associations=company&paginateAssociations=true
Response:
Going forward, if your request returns more than 100 associations, you will need to use the value of the after field returned in the response to get the next set of associated records.
To test the paginated results functionality before the rollout on January 18th 2021, you can include the paginateAssociations=true URL parameter (like in the example above). After January 18th 2021, all results will be paginated regardless of if the paginateAssociations query parameter is given.
The link field will provide the next paginated request URL for that object, with the after field value added to the end of the URL as a query parameter. See example below.
The batch endpoints that return multiple objects are going to have a separate "next page" request for each individual object.
Example:
link:"https://api.hubapi.com/crm/v3/objects/deal/DealID/associations/company?portalId=XXXXXXXX&after=MC01LTQ4Njg1NzEx"
When is this change happening?
This change will be taking place on January 18th 2021.
Please note: that there will be no change to the response for objects with less than or equal to to 100 associated objects of a given type. However, if apps are reading objects with greater than 100 associations per type and are relying on the initial response having all of the associated IDs, then those apps will stop working correctly after January 18th 2021.
Want to discuss this change? Hop on over to our community post here.