Identify a visitor

Last updated March 4, 2022

_hsq.push(["identify", { {identity details} }]);

Use this endpoint to identify website visitors and contacts.

  • Visitor: refers to any website visitor, regardless of whether they’re a HubSpot contact. HubSpot does not create records for visitors like it does for contacts.
  • Contact: refers to a visitor or offline contact that has a record in HubSpot. A contact can be identified by its unique email address.

To manually identify a visitor or contact, you can use either an email address or unique external ID:

  • email: identify a visitor by email address when you want to update an existing contact or create a new one. If a contact with that email exists in HubSpot, their contact record will update with the analytics data. If no contact exists at that email address, a new record will be created.
  • id: a custom external ID that identifies the visitor. Identifying a visitor with this ID will associate analytics data to that visitor. However, using the ID alone will not create a contact in HubSpot. Analytics data can only be associated with an existing contact through this method when:
    • the visitor was previously identified by both ID and email.
    • the visitor was previously identified by ID and also has a form submission associated with their record.

Please note: this external ID can only be used with the HubSpot tracking code. This ID cannot be used to retrieve or update any records through any other HubSpot tools or APIs. If you know the visitor’s email address, it’s recommended to use that as the unique identifier. Similarly, you should only identify a visitor with by ID when you don’t know their email address.

If you’ve previously sent analytics data to HubSpot using the visitor’s ID only, you can later include both the ID and an email address to associate the data from that ID with a contact. The existing contact will then be updated or created if no contact currently exists.

 
When using this function, keep the following in mind:

  • This function call stores the data in the tracker, but the data is not actually passed to HubSpot with this call. The data will only be passed when tracking a pageview or an event (with either the trackPageView or trackEvent functions).
  • A contact can only have one ID and/or email address associated with them. If you try to assign two IDs to one email, only the first ID will be associated with the email address.
  • You must include an email address to tie the data to a contact.
  • If your account was created before September 8, 2021 and is set up to allow contact properties to be updated through the tracking code, you can also include other contact properties to be updated with this function.
  • This function will not restore previously deleted contacts. These contacts must be restored in HubSpot.

 

About

Jobs

Learn Inbound

Support

Locations

HubSpot, Inc.
25 First Street, 2nd Floor
Cambridge, MA 02141
European Headquarters
Ground Floor, Two Dockland Central
Guild Street, Dublin 1
Asia/Pacific Office
20 Hunter St, Level 7
Sydney NSW 2000
View our other locations
/* This example grabs the value of a query string parameter '?email=' and uses that to identify the visitor */ function getParameterByName(name) { var match = RegExp('[?&]' + name + '=([^&]*)').exec(window.location.search); return match && decodeURIComponent(match[1].replace(/\+/g, ' ')); } var _hsq = window._hsq = window._hsq || []; _hsq.push(["identify",{ email: getParameterByName("email") }]); /* This example sets the email, as well as a custom property favorite_color */ var _hsq = window._hsq = window._hsq || []; _hsq.push(["identify",{ email: getParameterByName("email"), favorite_color: 'orange' }]); /* This example sets the email, as well as a custom external id for the visitor. This assumes that your site includes a variable named 'user' that includes that user's id in an 'id' property, and their email in an 'email' property. */ var _hsq = window._hsq = window._hsq || []; _hsq.push(["identify",{ email: user.email, id: user.id }]);