Announcing a change to how v3 CRM APIs return association data

[rhenry]

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=con...

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=co...

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=MC01L..."

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.

If you have any questions or comments, please let us know here in the forum thread.

[BHarrison-Cook]

Hi,

I am using https://api.hubapi.com/crm/v3/associations/companies/contact/batch/read? to return a list of associations for a batch of company ids.  From this endpoint, I receive the from_id, to_id and the association type

Due to the change, the companies with more than 100 contact associations are being returned with the next link as https://api.hubapi.com/crm/v3/objects/0-2/4917560421/associations/0-1?portalId=XXXXXXX&after=MC0yLTE... which is a completely different end point. Therefore we cannot simply pass the after parameter and paginate through the original call. Instead, for any company id in the results of the original batch call, which have more than 100 contacts, we have to make additional calls to this new end point for each company id returned. 

However, the new end point provided in the link field (as above) returns a different JSON string. It only returns the to_id and association type. Meaning you have to find a way to retain the company id for each individual call in order to obtain the same details as per the first original call (https://api.hubapi.com/crm/v3/associations/companies/contact/batch/read?).

This is very tedious and long winded, especially when dealing with multiple company id's which is what I am doing. As I have built a routine that downloads any modified records since my last call, in order to record changes in our datawarehouse. So on any given day, I can be downloading 100's of company records that have been modified and then need to download all of their associations.

From my testing, I have also noticed that the next link then doesn't seem to paginate further and returns the full list of remaining associations.  i.e. if a Company has 300 contact associations, the initial call using https://api.hubapi.com/crm/v3/associations/companies/contact/batch/read? would return 100 associations, then the next link would return the remaining 200. Can you confirm this is true?

Is there an easier way to download all Associations that exist for a batch of IDs?