vevee.analytics.alias()POST /api/v1/aliaspk_live_

Merge two ids that belong to the same person into a single profile. Despite the name, alias is a full merge - not a lightweight pointer. When either id is an APL anonymous session, the call is consent-gated under GDPR / ePrivacy.

i
Reach for identify() first. The normal anonymous-to-real flow is handled by identify() - it runs the same merge and writes profile properties in one call. Use alias() for the cases identify()doesn’t cover - e.g. linking a later-discovered secondary id to an existing person.

Signature

vevee.analytics.alias(
  distinctId: string,   // merge FROM - this person is absorbed, then deleted
  alias: string,        // merge INTO - this person survives and stays canonical
  options?: AliasOptions,
): Promise<AnalyticsAliasResponseData>

interface AliasOptions {
  consentGiven?: boolean;   // REQUIRED true when either id is an anonymous session
}
i
Direction matters. alias(a, b) merges person a into person b - the second argument is the survivor. To keep the real user as the canonical person, pass the real id as alias (second argument) and the anonymous / secondary id as distinctId (first).

Parameters

NameTypeDescription
distinctIdrequiredstringThe id to merge from. Its events and id mappings are re-pointed at alias’s person; its own person row is then deleted.
aliasrequiredstringThe id to merge into. Its person survives, stays canonical, and is marked identified. Created automatically if it has never been seen.
options.consentGivenoptionalbooleanSet true after obtaining explicit consent. Required when either id is recognised as an anonymous session - see Consent gate.

Response

interface AnalyticsAliasResponseData {
  personId: string;   // 'pid_…' - the surviving person both ids now resolve to
}
await vevee.analytics.alias('user_uuid_old', 'user_email@example.com');

Both ids look like real account identifiers (no anon_ prefix), so the SDK does not gate the call.

When either id is an APL anonymous session (a string returned by getAnonymousId(), recognised by its anon_ prefix), this links anonymous browsing to a real account and is consent-gated exactly like identify()’s merge.

await vevee.analytics.alias(anonId, user.id, { consentGiven: true });

Without consentGiven: true, the SDK throws consent_required (400). The server records a consent_audit_log entry once the merge runs.

!
The consent gate is heuristic: APL detects an anonymous session by the anon_ prefix that getAnonymousId() produces. If you mint your own anonymous ids without that prefix, you are responsible for acquiring consent before calling alias() to merge them into a real account.

What alias actually does

alias runs the exact same merge as identify(). When you call alias(distinctId, alias):

  • Every analytics event under distinctId’s person is re-attributed to alias’s person.
  • Every distinct-id mapping for distinctId’s person is re-pointed - afterwards both ids resolve to the surviving person.
  • Profile properties from both are merged; on a key conflict, alias’s person wins.
  • distinctId’s now-empty person row is deleted, and the survivor is marked identified.

Idempotent - if both ids already resolve to the same person there is nothing to do and the call is a safe no-op. The only thing alias does not do is write new profile properties: there is no $set / $set_once here.

Aggregate mode

alias() is disabled in aggregate mode and throws invalid_request.

Errors

  • consent_required (400) - either id had the anon_ prefix but consentGiven: true was not passed.
  • invalid_request (400) - called in aggregate mode, or malformed field.
  • analytics_quota_exceeded (429) - workspace is over its monthly analytics quota.
  • invalid_key (401) - bad or revoked API key.
i