Associate deal to company using unique property (not hs_company_id) via API v4

Developer Support APIs & Integrations
1

I’m using the following endpoint to create associations between objects:

ruby

CopierModifier

https://api.hubapi.com/crm/v4/associations/deals/companies/batch/create

I’m trying to associate deals to companies, but instead of using the internal hs_company_id, I would like to use a custom unique property (e.g. code_client) to identify the company.

It seemed to me that this was possible using idProperty, but after several attempts, I haven’t been able to make it work. I’ve double-checked that the property is correctly defined as unique and the values are correct.

Here is an example of the payload I’m using:

{ “from”: { “id”: deal_id },

“to”: { “id”: comp_id, “idProperty”: “code_client” // ← the exact name of the unique property in HubSpot },

“types”: [{ “associationCategory”: “HUBSPOT_DEFINED”, “associationTypeId”: ASSOC_TYPE_ID }] }

But I get this response:

{ “status”: “COMPLETE”, “results”: [], “numErrors”: 1, “errors”: [{ “status”: “error”, “category”: “VALIDATION_ERROR”, “message”: “COMPANY=111111 is not valid” }] }

Any idea if idProperty is supported in this context, or if there’s another way to associate records using a unique property other than the internal ID?

Thanks in advance! :folded_hands:

2

Hey @GDiMaiolo,

To my knowledge, the /crm/v4/associations API does not support custom ID properties. It only works with internal HubSpot IDs (hs_object_id).

Suppose you want to associate a deal to a company using a custom unique property like code_client. In that case, you may be able to first look up the company’s internal ID using the Search API, then use that ID in your association call.

Refer:

Hope this might be a help!

Regards,

3

Hello @GDiMaiolo ,

Unfortunately, the idProperty field isn’t supported in the HubSpot Associations API. So, you can’t directly associate a deal with a company using a custom property like code_client.
Check similar community thread - https://community.hubspot.com/t5/APIs-Integrations/Is-it-possible-to-associate-an-object-using-a-custom-property/m-p/912293

What you should do instead -
Use the Search API to look up the company’s internal ID (hs_object_id) based on code_client.
Example:
GET /crm/v3/objects/companies/search

And then use that internal ID in your association request with:
POST /crm/v4/associations/deals/companies/batch/create
This is currently the only supported way to associate objects when working with custom properties.
Helpful links-

Search API guide - Accounts Dashboard | HubSpot
Associations v4 API docs - Accounts Dashboard | HubSpot

CRM Batch Read Companies (v3) - Accounts Dashboard | HubSpot
Hope this clears it up!

4

Hello,

Thanks to both of you for the clear and detailed response. I was specifically trying to avoid having to perform a search in order to limit the number of API calls.
It’s unfortunate that it’s not possible to create associations between objects using anything other than the primary internal ID.

Thanks again for your help!

regards,

Guillaume