Email or PK for Contact API


The API documentation for Contacts says, "the primary key for a contact in the HubSpot system is an email address".

But there are API methods which allow updating the email address of a contact - although this can't be done by email, but using the "vid".

So the vid appears to be the actual PK. But when you create contacts (in bulk at least) you are not told the vid. You would have to fetch the vid by email, and then update by vid.

From this, I have questions:

  • Is it possible to specify an id field to be the PK of a contact, or can it only be the vid?
  • Are we expected to store the Hubspot vid in our own system to facilitate synchronisation and lookups?
  • Can a contact have more than one email address? (For example, home and work)


Hi @stewart,

The actual contacts backend is more complicated than the API Documentation implies. The way you structure your own DB should differ depending on how exactly you're interacting with the HubSpot API. Let's address your questions individually first, and we can come back to that.

  • A contact's vid is internal, so it isn't a property in the same way First Name is. It's not possible to create a custom ID property that acts as the PK in HubSpot.
  • You're not required to store the vid for your contacts in your own system, but many integrators choose to do so for the exact reasons you're describing (facilitating sync & lookups).
  • A contact can have multiple email addresses, but it will always have a single primary email address. The primary email of a contact is stored in the email property, while the secondary email addresses are stored as a semi-colon separated list in the hs_additional_emails property. Secondary email addresses can be used to look up contacts in the same way primary email addresses can.

Does that help answer your question? I'd generally recommend using vid as a primary key, unless the way your app interacts with HubSpot would make that difficult (for example, if you create large numbers of contacts via the batch create method). If using vid would be difficult, and you always know a contact's email in your external system, then using email as the primary key might be the better move.


Thank you Derek.

I'm not finding it easy to discover documentation about updating hs_additional_emails via the Contacts API. Which page should I be looking at please?

I have experimented with adding a secondary email via the Web UI, and found the data comes back as part of identity-profiles array. Is this how it should be posted?

Also in identity-profiles I saw an item with type LEAD_GUID. What relationship does this have with vid or with uniquely identifying the contact?

Basically I'm looking for a method of including our own primary key and being to fetch directly using that key also.

For example, if someone changes their email address, it seems we would have to first fetch the vid using the old email, and then use that retrieved vid as the key to post the new email.

What is the recommended way to use our own primary key to reference a Contact?


Actually, I've also just seen properties called profile-token and profile-url. What role do these play? Where can I find the documentation on these please?


Hi Derek,

I've been experimenting with your suggested property hs_additional_emails and the API returns to me "hs_additional_emails" is a calculated property; its value cannot be set.

So I think your answer is incorrect. Have I misunderstood something?




Hi @stewart,

I didn't mean to imply that it was possible to edit the hs_additional_emails property. The hs_additional_emails property is read-only, and it's not currently possible to add email secondary email addresses to contacts via the API. When I said:

Secondary email addresses can be used to look up contacts in the same way primary email addresses can.

What I meant was that using a secondary email address with endpoints like the 'Get contact record by email' endpoint will still return the correct contact record. A contact record can have secondary emails, but each email address can only be associated with a single contact record.

Some notes on your other questions:

  • Identity profiles are included in the response from the Contacts API, but they're only used internally and can't be edited via the API. Identity profiles are associated with how HubSpot manages deduplication; the hs_additional_emails property is a reflection of some of these identity profiles.
  • LEAD_GUID is a type of identity profile that is unassociated with contact's email(s). It's only used internally.
  • profile-token and profile-url are associated with the public contact record; the token is a part of the URL. Neither of these fields are associated with a contact's email(s) or identity.

It's not possible to define a custom property that acts as a primary key. It's possible to look up contacts by either email or vid; deciding which to use depends on how exactly you find you need to look up contacts. If you could give me some more context on your use case, I can likely give you some more specific recommendations.


Hi Derek,
Sorry, I missed the notification of your reply, so I only saw this this morning.

Our context was that we need to synchronize 40,000 users from our system into Hubspot via the API.

The bulk contact API does not return the created vids - it returns 204 with no content.

We wanted to be able to lookup contacts in Hubspot using our own PK - especially as a user is free to change their email in our system. Our system updates Hubspot asynchronously, so if the email changes at our end, and the update fails at Hubspot's end (network outage, let's say) there is a danger that you can't find that correct contact again, unless we store the previous email. (Or a resilient retry mechanism, which is a lot of overhead for one data field)

We were thinking of fudging it by sending "" as the email, and using a secondary email field as the real email.

Do you think Hubspot could consider supporting a searchable, indexed "external_pk" field on a Contact?


Hi @stewart,

A searchable, indexed external primary key isn't something that's currently in planning, but the team is open to the idea. For this specific idea, I would encourage you to check out the Ideas Forum on the HubSpot Community.

One way you might consider running the import is doing the following:

  1. Bulk import your contacts, including your own primary key as a custom contact property
  2. Pull batches of contacts from the 'Recently modified contacts' endpoint, including the primary key property, and cross reference with the records in your system to get the vid