Skip to main content
POST
Identify a visitor
Call this when a visitor signs in. Send the anonymous ID their events used before signing in, and your user ID for them.
Events still recorded under the anonymous ID move onto the user, and the user’s profile is rebuilt with them. What someone browsed before signing in then shapes their recommendations, on that device and on every other device where they sign in. After the call, send user_id for that person on later events and recommendation requests. The JavaScript SDK calls this for you from identify(userId). See Identity for the full sign-in and sign-out flow.

What moves

  • Only events still recorded under the anonymous ID move. An event moves once.
  • Events older than the workspace’s retention period stay where they are, as do events beyond the newest 5,000.
  • The anonymous ID stays on each event, so Data → Users can show which device it came from.

When nothing moves

A refused link still returns 200, with linked: false and a reason: Calling it again for the same pair is safe. It returns already_linked and moves anything sent anonymously since the last call.

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

Links an anonymous visitor to a known user. anonymousId and userId are accepted as aliases.

anonymous_id
string
required

The anonymous ID the visitor's events were sent with before they signed in.

Maximum string length: 255
Example:

"aid_7f3c2b91e0"

user_id
required

Your stable user ID for the person who signed in. Use the same value for later events and recommendations.

Maximum string length: 255
Example:

"user-123"

source
string

Optional label for what made the link, shown in the console. The JavaScript SDK sends js-sdk.

Maximum string length: 64
Example:

"checkout-login"

Response

Link result. A refused link is still a 200 with linked: false and a reason.

object
enum<string>
Available options:
identify
anonymous_id
string
user_id
string
linked
boolean

True when the anonymous ID is now linked to this user.

events_moved
integer

Earlier events moved from the anonymous ID onto the user by this call.

reason
enum<string>

linked: first link. already_linked: linked to this user before; any events sent anonymously since were moved. linked_to_other_user: the anonymous ID belongs to someone else (for example a shared device), nothing moved. same_id: the two IDs are equal. erased: one of the IDs was erased, nothing moved.

Available options:
linked,
already_linked,
linked_to_other_user,
same_id,
erased
embedding_refresh
object

Whether the user's profile is being rebuilt with the moved events.