HubSpot API Import Prioritizing Email Address over Unique ID

[CSteinbach]

We just ran into a challenge with how HubSpot handles contact imports via API, and I could use some help figuring out a solution. Even though we have "Intnernal ID" set as the unique identifier, HubSpot still prioritizes email addresses. That means if a contact’s email already exists in HubSpot, the API ignores the new upload—even if the "Intnernal ID" is different.

Because of this, around 7,000 "Intnernal ID" from today’s import didn’t make it into the system. This doesn't appear to be a bug, just the way HubSpot works, and we only caught it by digging into the API call details.

Has anyone encountered this before? Any ideas for workarounds or API settings that might help us get these contacts imported correctly?

[CSteinbach · Accepted solution]

So it sounds like one option might be retrieving the hs_object_id using the CIF to update records rather than attempting to reimport them.

It may be worth exploring whether we can leverage this to ensure CIF-based updates work as expected.

Another potential workaround is creating a file that includes only the "CIF," "First Name," and "Last Name," while leaving out the "Email" property. This could force the system to check only CIFs, but it would only work if updating email addresses isn’t necessary - though, we would need to update email addresses regularly. 

[KRodriguez90]

From what I understand, when you're importing via the HubSpot API, it prioritizes the unique ID (like vid or id) over the email address if both are present in the payload. So even if the email points to another contact, the API will update the contact with the ID you provided. If you want to prioritize email instead, it's better to skip the ID altogether in your request and let HubSpot match based on the email field. Just be careful if there’s a chance of duplicate emails across contacts

[BérangèreL]

Hi @CSteinbach, I hope that you are well!

Thanks for asking the HubSpot Community, and thanks @KRodriguez90 for your help!

Here is the documentation "Imports API" that might help you!

What about exporting the contacts to get the Record ID, then on the file, only using the "Record ID", "First name" and "Last name", and not having the "email" property, to force the system to only check Record IDs, if that's what you'd like?

But this would only work if you don't need to update the email addresses.

I hope this helps!

Have a lovely day! 🌞

Warmly,
Bérangère

[CSteinbach · Accepted solution]

So it sounds like one option might be retrieving the hs_object_id using the CIF to update records rather than attempting to reimport them.

It may be worth exploring whether we can leverage this to ensure CIF-based updates work as expected.

Another potential workaround is creating a file that includes only the "CIF," "First Name," and "Last Name," while leaving out the "Email" property. This could force the system to check only CIFs, but it would only work if updating email addresses isn’t necessary - though, we would need to update email addresses regularly. 

[BérangèreL · Accepted solution]

Hi @CSteinbach, thanks for getting back to me!

If you do need to update the email addresses as well, then, you'll have to add the "email" property in the import file.

I understand that then the system will prioritize the email, instead of the ID.

Just to understand your use case here, why would you want to create a new Record ID 2 with the same email address as another Record ID 1?

If you create a new contact, when importing, you only need to add the email address of the contact.

The Record ID is populated after the import and is created by the system, once imported successfully.

Thanks and Kind Regards,
Bérangère

[CSteinbach]

It looks like we’ll need to find a workaround. I appreciate your help. The industry I work in is highly regulated, and core databases are structured at the account level rather than the contact level. We often have multiple email addresses per account or contacts sharing the same email across multiple accounts.

Managing this data can be challenging without a data warehouse or a transformation layer before it enters HubSpot. It’s frustrating that HubSpot doesn’t support multiple instances of the same email address, even when a different unique identifier is set. Platforms like Salesforce and other CRMs offer more flexibility in this regard.

[BérangèreL]

Hi @CSteinbach, I'd recommend sharing your valuable feedback via the HubSpot Developer Feedback Form, then the Team can review it. Thank you!

Also, I'd love to put you in touch with our Top Experts: Hi @sylvain_tirreau, @Anton and @WesQ can you think of a workaround to help @CSteinbach, please?

Have a beautiful weekend and thanks so much in advance for your help!
Bérangère