Identify a visitor

Last updated September 8, 2021

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

This endpoint is used to identify a visitor to your site. The unique identifier is an email address. If there is an existing contact record for that email address, it will be updated. Otherwise, a new contact record will be created. In both cases, the analytics data collected for the visitor will be associated with the contact record.

Use case for this endpoint: In addition to creating contacts by email address, this method can also be used to set or update other contact properties. Note: the email address of an existing contact cannot be updated with this method.

Note - There are a few things to keep in mind when using this function:
  • 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).
  • 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-app.

In addition to identifying a record by email address, you can also use a custom external ID to identify a visitor, by simply using 'id' as the identifier.  As with email, identifying a record using 'id will associate analytics data for the visitor with that ID.  However, unlike with an email address, including an 'id' by itself will not create a contact. Also, this 'id' is treated as a completely external identity, so while analytics data can be associated with a specific contact record by the ID (if, for example, you've previously identified a record by ID and by email, or the record was previously identified by ID and the visitor also has a form submission), the contact record cannot be looked up by this ID.

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.