topic Re: `category` field in associations in APIs & Integrations

`category` field in associations

Sachavskyi — Tue, 24 Jun 2025 14:50:43 GMT

I'm retrieving the association configuration (specifically, I want to know maxToObjectIds) using the /crm/v3/schemas/0-1 endpoint. In the response, I see two associations with the same ID:

{
    ....
    "associations": [
        {
            "fromObjectTypeId": "0-1",
            "toObjectTypeId": "0-2",
            "name": "CONTACT_TO_COMPANY",
            "cardinality": "ONE_TO_ONE",
            "inverseCardinality": "ONE_TO_MANY",
            "hasUserEnforcedMaxToObjectIds": false,
            "hasUserEnforcedMaxFromObjectIds": false,
            "maxToObjectIds": 1,
            "maxFromObjectIds": 50000,
            "id": "1",
            "createdAt": null,
            "updatedAt": null
        },
        {
            "fromObjectTypeId": "0-1",
            "toObjectTypeId": "0-2",
            "name": "referredby",
            "cardinality": "ONE_TO_ONE",
            "inverseCardinality": "ONE_TO_MANY",
            "hasUserEnforcedMaxToObjectIds": false,
            "hasUserEnforcedMaxFromObjectIds": false,
            "maxToObjectIds": 1,
            "maxFromObjectIds": 50000,
            "id": "1",
            "createdAt": null,
            "updatedAt": null
        }
    ]
}

Notice: we don't have category field here.
The next step: I want to know labels for these associations and I sent a request to retrieve all association labels between Contact and Company:

GET https://api.hubapi.com/crm/v4/associations/0-1/0-2/labels HTTP/1.1

And got the following response:

HTTP/1.1 200 OK
.....

{
    "results": [
        {
            "category": "USER_DEFINED",
            "typeId": 1,
            "label": "Referred By"
        },
        {
            "category": "HUBSPOT_DEFINED",
            "typeId": 1,
            "label": "Primary"
        }
    ]
}

My question is:
How can I determine which label corresponds to which association configuration when they both share the same typeId?

I need category field in the /crm/v3/schemas/0-1 response.

Re: `category` field in associations

Jaycee_Lewis — Wed, 25 Jun 2025 20:32:07 GMT

Hey, @Sachavskyi 👋 Great question. And one that uncovers a current limitation in the API design.

Have you tried something like:

call the `GET /crm/v4/associations/{fromObjectTypeId}/{toObjectTypeId}/labels` endpoint to get the `typeId` and category for all association types
filter this list and find your target association (e.g., where label is "Referred By" and category is USER_DEFINED). Note its `typeId`
call the `GET /crm-object-schemas/v3/schemas/{objectType}` endpoint
find the association where the `id` matches the `typeId` from step 2 and the name logically matches your custom association's name (e.g., `referredby`)
you can then pull the `maxToObjectIds` from that object

And if this doesn't work, please let us know, as that is useful in continued troubleshooting.

Best,

Jaycee

Re: `category` field in associations

GRajput — Thu, 26 Jun 2025 07:01:52 GMT

Hi @Sachavskyi

I think you want to know which type ID is corresponding to which association. If so, here is the link that will tell the typeID and Association type -

https://developers.hubspot.com/docs/guides/api/crm/associations/associations-v4

I hope this will help you out. Please mark it as Solution Accepted and upvote to help another Community member.

Thanks!

Re: `category` field in associations

Sachavskyi — Thu, 26 Jun 2025 09:29:30 GMT

Hey, @Jaycee_Lewis!

Thank you for your response, but it doesn’t work as expected:

Find the association where the id matches the typeId from step 2 and the name logically matches your custom association's name (e.g., referredby).

What do you mean by "the name logically matches your custom association's name"? How can I reliably do that in my code?
For example, what if I have an association with "label": "Referred By" and "name": "test"? In that case, I wouldn’t be able to find the correct association based on a "logical" match to the name.

That’s why I believe the best solution would be to include the category field in the response of GET /crm-object-schemas/v3/schemas/{objectType}, so we can reliably match associations using both typeId and category.

Re: `category` field in associations

Jaycee_Lewis — Tue, 08 Jul 2025 16:57:02 GMT

Hey @Sachavskyi 👋 You've correctly identified a current limitation of the API. There's no better workaround at the moment.

The best way to get this in front of our product team is to submit your findings through the official Developer Feedback form. That's the most effective channel for suggesting the exact kind of improvement you've detailed here. — Jaycee