topic Re: Association's typeId field is not unique in APIs & Integrations

Association's typeId field is not unique

Sachavskyi — Thu, 19 Jun 2025 14:58:36 GMT

I want to create a new association label between Contact (0-1) and Company (0-2). So I sent the following request:

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

{
    "label": "Referred By",
    "name": "referredby"
}

And received this response:

HTTP/1.1 200 OK
...

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

Then, 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": 931,
            "label": "Billing Contact"
        },
        {
            "category": "HUBSPOT_DEFINED",
            "typeId": 279,
            "label": null
        },
        {
            "category": "HUBSPOT_DEFINED",
            "typeId": 1,
            "label": "Primary"
        }
    ]
}

Question:
Why is the typeId value 1 used for both my custom association label ("Referred By") and a built-in one ("Primary")?
Shouldn’t typeId values be unique across all labels?

Re: Association's typeId field is not unique

GiantFocal — Thu, 19 Jun 2025 15:26:37 GMT

Hi @Sachavskyi,

The typeId for association labels in HubSpot isn’t globally unique. It can be the same number for both custom (USER_DEFINED) and built-in (HUBSPOT_DEFINED) labels. That’s why you see typeId 1 for both your “Referred By” label and the “Primary” label.

To avoid confusion, always check both the category and typeId when working with association labels. This is how HubSpot’s API is designed, so it’s expected behavior.

Re: Association's typeId field is not unique

Sachavskyi — Fri, 20 Jun 2025 09:12:22 GMT

It's so confusing. Anyway, thank you, @GiantFocal

Re: Association's typeId field is not unique

Sachavskyi — Fri, 20 Jun 2025 15:44:13 GMT

@GiantFocal Thank you for your response!
I have one more question.
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 (it's ok as you explained to me):

{
    "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 this 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?

Re: Association's typeId field is not unique

GiantFocal — Sun, 22 Jun 2025 06:26:13 GMT

Hi @Sachavskyi,

Basically, the ‎`typeId` field isn’t unique across all labels. Instead, it’s only unique within each category (‎`USER_DEFINED` or ‎`HUBSPOT_DEFINED`). That’s why you can have ‎`typeId: 1` for both your custom label (“Referred By”) and the built-in label (“Primary”).

Unfortunately, HubSpot’s API doesn’t give you a straightforward way to link a label directly to a specific association configuration when they share the same ‎`typeId`. The only way to tell them apart is by looking at both the ‎`typeId` and the ‎`category` fields together.

So, whenever you’re working with association labels, always check both fields (‎`typeId` and ‎`category`) to make sure you’re referencing the right label. If you need to map these labels to specific associations in your system, you’ll probably need to keep track of that mapping yourself.

Hope that clears things up!

Re: Association's typeId field is not unique

Sachavskyi — Mon, 23 Jun 2025 17:19:34 GMT

@GiantFocal I would be happy to do this:

The only way to tell them apart is by looking at both the ‎`typeId` and the ‎`category` fields together.

but response for /crm/v3/schemas/0-1 endpoint doesn't have the `category` field, so I can't tell them apart.

Re: Association's typeId field is not unique

Jaycee_Lewis — Thu, 10 Jul 2025 03:12:58 GMT

Hey @GiantFocal and @Sachavskyi 👋 One additional question.

Have you thought about trying to:

Query the GET .../labels endpoint to find the correct category and typeId for the desired label.
Use both of these values in the PUT request to create the specific association.

{ "associationCategory": "USER_DEFINED", "associationTypeId": 1 }

I believe this is related to what @Sachavskyi was pointing towards when they noted they must provide bothassociationCategory and associationTypeId in the request to create a new association between two records using a specific label.

Talk soon! Jaycee

Re: Association's typeId field is not unique

Sachavskyi — Thu, 10 Jul 2025 09:52:51 GMT

Hey @Jaycee_Lewis.
Sorry, maybe I'm not fully understanding what you mean. I don’t have any issues creating specific associations. The issue is identifying which label corresponds to which association configuration when they both share the same typeId. For example, in my app, I want to display how many associations a user can create for a specific label.