Identify a visitor

Last updated June 17, 2020

_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. Other contact properties, including custom properties, can be updated with this function, but only an email will associate the data with a contact.
  • 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.