Associations: why does v4 API drop support for type names?

[PCronin9]

With respect to custom associations that I create, my understanding of the following three concepts:

Label: the business-facing name of the assocation type. Can be changed in HubSpot's UI by suitably-privileged users.

Name: the "internal" name of the association type, e.g. the name my program can use to reference the type. Cannot be changed in HubSpot's UI without deleting and creating a new association type.

Type ID: an integer value assigned by HubSpot when a custom association type is created.

The v3 associations API speaks in terms of name and type ID,  and is easy to use. My v3 integrations can be hard-coded with the name of the associations I'm interested in, and not care what ID HubSpot assigned to it, nor worry if UI users change the associations' labels. Endpoints return the ID and name of association types, and my program can use the name to determine if the given association is relevant.

The v4 API does away with the type (name) and speaks in terms of label and type ID, neither of which is relevant to an integration. I can't hard-code the type ID into the program because it needs to vary across HubSpot accounts, and I can't hard-code the label into the program because it can be changed in the UI. The name is ideal, but is not available from v4 endpoints.

Paradoxically, to get around this problem, my integrations need to use the v4 Associations Schema > Definition > Create endpoint to create custom associations with a name (the internal name my program will use), and then in subsequent runs, use the v3 Assocations Schema > List association types endpoint to discover the IDs of the custom association types of interest.

Why does the v4 Associations API drop support for type names?

[suprdense]

Hey @PCronin9 ,

HubSpot’s v4 Associations API removed type names to separate what developers use from what users see in the UI.

You can still define a name when you create a custom association type, but that field is creation-only and will not appear in responses afterward. HubSpot wants integrations to rely on the typeId, which stays stable within a portal.

The label field is what users see in HubSpot. It can be edited, translated, and is meant only for display. By removing names from v4 responses, HubSpot ensures integrations do not break when an admin renames or localizes a label.

This change makes each portal’s schema self-contained and more reliable.

In practice:
- Create your custom associations when your app installs.
- Store the `typeId` that HubSpot returns.
- Use that `typeId` for all future association operations.

Using v3 to look up type IDs by name can still work for now, but it is only a temporary workaround. HubSpot expects integrations to manage and store their own IDs going forward.

I hope this explanation helps clarify the issue and gives you the context you needed. If it resolves your question, please consider marking it as the accepted solution and giving it an upvote — it’ll help others in the community facing the same problem.

[PCronin9]

The type name is also not editable by UI users, and isn't shown to UI users, so also falls into the category of "what developers use" instead of "what users see in the UI." The advantage of the type name is that I can simply hardcode it into my integration's source, instead of needing to build a state serialization mechanism for this one value, and needing to maintain one state serialization per HubSpot account that I work on (primary account plus developer/test accounts).

If that value is ever lost from the state, there is no reliable way to restore that value into integration state using the v4 Associations API, given the label is editable by UI users and is therefore not dependable for API use. Manual intervention is required, which is sort of against the whole point of an API.

So you said "HubSpot expects integrations to manage and store their own IDs going forward" and my question is -- why is this approach better than using the already-existing concept of type names? It seems the existing mechanism of type names is superior to requiring integrations to add the complexity of state management and offering no future support for the recoverability of that state should it be lost.

[chighsmith]

Hi there @PCronin9,

Thank you for your insightful observations about the differences between HubSpot’s v3 and v4 Associations APIs. 

You’re correct that while v3 reliably supports integrations through the stable internal “name,” v4 only offers label and type ID. 

The current best practice is to use v3 endpoints to resolve association names to IDs before working with v4. 

With all of that being said, I recommend sharing your feedback in the HubSpot Ideas Forum, as this is the best way to highlight the need for name support in v4 to HubSpot’s product team for future improvements.

Thank you for your contributions!

Cassie, Community Manager

[SteveHTM]

@PCronin9 - I understand this is just a personal perspective, but ever since I started using the V4 API I have been happy to take the approach that you describe - usingthe label value to auto-detect the typeID with the schema calls and then using that type ID for the actual association logic. I've found that it works for my integration efforts, where I sometimeas want to see beyong the standard typeID values (especially using custom objects etc.)

Hope this is helpful.

Steve

[PCronin9]

This approach is fine if UI users cannot alter the association type label names. Unfortunately that is not the case in my situation.

[chighsmith]

Hi @PCronin9,

Thank you for posting to the Community!

I will reach out to our team and keep you updated on this thread 🙂 

Cassie, Community Manager