Filter retrieved associations by associationTypeId (v4)

Developer Support APIs & Integrations
1

Using the v3 schemas API I’ve been able to fetch the schema for my contacts object so that I can read the association definitions. Here is an example of one such definition that I’ve retrieved from the returned schema.associations array:

{
	fromObjectTypeId: '0-1',
	toObjectTypeId: '0-1',
	name: 'friend',
	cardinality: 'ONE_TO_MANY',
	inverseCardinality: 'ONE_TO_MANY',
	hasUserEnforcedMaxToObjectIds: true,
	hasUserEnforcedMaxFromObjectIds: true,
	maxToObjectIds: 1,
	maxFromObjectIds: 1,
	id: '3',
	createdAt: null,
	updatedAt: null
 // No Label?? (**)
},

Another question: Why is the label (if exists) not included here? It seems to be included when the associated object itself is retrieved later (see **)

Now using this association I want to use the associations API to grab the associated ‘friend’ of one of my contacts with record id 92131509275 (Brayden). So I make a callout to:

/crm/v4/objects/0-1/92131509275/associations/0-1

This returns a list of ALL contacts associated with Brayden

{
 ok: true,
 status: 200,
 statusText: 'OK',
 url: 'https://api.hubapi.com/crm/v4/objects/0-1/92131509275/associations/0-1?',
 data: {
 results: [
 {
 toObjectId: 78157755542,
 associationTypes: [
 // Label included here (**)
 { category: 'USER_DEFINED', typeId: 1, label: 'Co Worker' },
 { category: 'USER_DEFINED', typeId: 3, label: 'Friend' },
 { category: 'HUBSPOT_DEFINED', typeId: 449, label: null }
 ]
 },
 {
 toObjectId: 78158615374,
 associationTypes: [ { category: 'HUBSPOT_DEFINED', typeId: 449, label: null } ]
 }
 ]
 }
}​

(**) Also why is the label included here but not included in the schema? For my implementation I would much prefer users to see the label (from schema bulk callout) instead of having to rely on the internal ID. Fetching for the labels individually is also pretty impossible with rate limits/overhead.

I know that I can do filtering on the client side to only get associations where there exists a category with typeId=3 (friend association type id). But what if I’m accessing a record that has thousands and thousands of other contacts associated? Association upper limits seem to be around ~50,000. Will I really have to put my server through that much overhead to retrieve a specific type of association? This will also take so long with throttling and rate limiting that my requsts will time out, I tried query parameters such as ?associationTypeId=3 but that does not seem to work on this endpoint.

I know there was a v1 equivalent to do this. For example I could do:

/crm-associations/v1/associations/92131509275/USER_DEFINED/3

Which would give me the result below (notice how: 78158615374 Maria Johnson is omitted from the server response here, because she is not associated using the associationTypeId of 3)

{
 ok: true,
 status: 200,
 statusText: 'OK',
 url: 'https://api.hubapi.com/crm-associations/v1/associations/92131509275/USER_DEFINED/3?',
 data: { results: [ 78157755542 ], hasMore: false, offset: 78157755542 }
}

So my 2 general questions are:

  1. Is there an equivalent query parameter or URL parameter for v4 that allows me to search for associated object specifically by association type id, similar to the last URL param of v1?
  2. Why is the label not included in the schema.associations? It seems to be included when the associated objects themselves are fetched.
2

@GarnetYeates - Thanks for the well documented question here. I’ll try and answer from my experience - others in the community may have deeper knowledge.

Q1) I don’t believe you can query based on association type ID as a filter in the way you have described with the current API. Maybe something to be written up as an idea?

Q2) Doesn’t you schema response include the string ‘friend’ since it’s a property of the schema definition of that particular type of association. That corresponds 1:1 with the label used when an association of this type is actually created between two objects.

Hope this is helpful.

Steve

3

Thank you for the quick response.

Regarding your Q1 answer) Doesn’t seem to be a thing in v4 as far as I know, but it was a thing in v1. If you see the bottom example you can see that the server response omits Maria Johnson because she doesn’t fall under typeId=3. Here is the v1 documentation:

GarnetYeates_0-1737056499855.png
GarnetYeates_0-1737056499855.png754×458 49.7 KB

Link. It seems like the :definitionId lets you filter to only get associations that fall under a specific definition. In the v1 example it omits Maria because she isn’t associated using the ‘friend’ association definition. To elaborate further, if I did

/crm-associations/v1/associations/92131509275/HUBSPOT_DEFINED/449

then it would give me all associated contacts (because I think 449 is the ‘primary’). But doing USER_DEFINED/3 only gives me records associated through the ‘friend’ definition. I was hoping there would be an equivalent filter for v4 because the v1 syntax is wonky (having to know to put USER_DEFINED or HUBSPOT_DEFINED when the schema associations response doesn’t tell you whther it was defined by hubspot or the user so it’s hard to track), and there are also limitations to v1 regarding certain association retrievals.

Regarding your Q2 answer) The ‘friend’ included in that response is the internal name of the association, but I was hoping to be able to also get the association label (Friend) because it’s a more ‘user-readable’ abstraction of the internal name. I could imagine situations where the internal name differs enough from the label to create confusion for end-users.

4

I’m betting the v1 API doesn’t support the whole range of associations now possible, including user defined types which you may well need here.

I have seen other cases where the documentation of new API versions was incomplete for a while (including assoc v4), so maybe we are just nt seeing the full picture.

Steve