Identity resolution

How Outlit connects anonymous visitors, known contacts, and customer accounts.

Outlit links anonymous website visitors, known contacts, and customer accounts in the customer context graph. The Outlit Browser SDK records the first landing page, referrer, UTM data, and anonymous browsing; identifying that same browser visitor with an email connects their earlier history to a contact. An email-only call from an Outlit server SDK does not identify an otherwise anonymous browser visitor.

Identify from forms

By default, Outlit automatically identifies visitors when they submit a form containing an email field—no code required.

How it works

When a form is submitted, Outlit:

1. Detects email by looking for:

   • Field names: email, e-mail, user_email, emailAddress
   • Input type: type="email"
   • Any field with a valid email value (fallback)

2. Extracts name by looking for:

   • Full name: name, full_name, fullname, your_name
   • First name: first_name, fname, firstname, given_name
   • Last name: last_name, lname, surname, family_name

3. Calls identify() automatically:

// This happens behind the scenes when a form with email is submitted
identify({
  email: '[e-mail]',
  traits: {
    name: 'Jane Doe',      // If full name found
    firstName: 'Jane',     // If first name found
    lastName: 'Doe'        // If last name found
  }
})

The form submission event is still captured separately. Auto-identify adds an additional identify event when an email is found.

Disabling auto-identify

If you prefer to handle identification manually:

Script tag

<script
  src="https://cdn.outlit.ai/stable/outlit.js"
  data-public-key="pk_xxx"
  data-auto-identify="false"
  async
></script>

React

<OutlitProvider publicKey="pk_xxx" autoIdentify={false}>
  {children}
</OutlitProvider>

npm

outlit.init({
  publicKey: 'pk_xxx',
  autoIdentify: false
})

How identity resolution works

For example, two anonymous visits with different visitor IDs both identify as [e-mail]. Outlit links both histories to the same contact. A server event for usr_456 that identifies with the same email joins that contact’s customer profile too.

Identity priority

When multiple identifiers exist, Outlit uses this priority order:

Priority	Identifier type	Example	Source
1 (Highest)	Email	[e-mail]	Identify call, form submission
2	External User ID	usr_12345	Auth provider (Supabase, Auth0)
3	Fingerprint	device_abc123	Outlit server SDK (device identifier)
4 (Lowest)	Anonymous ID	abc-def-123	Browser visitor ID

Resolution process

When you call identify():

1. Search existing contacts by provided identifiers
2. Match found? Link the anonymous visitor to existing contact
3. No match? Create a new contact and, when the evidence supports it, a customer profile

Identifying a person does not request a merge of separate customer records. Review customer merge suggestions through Identity.

When customerId is provided with an identify call, Outlit also links that contact to your system-owned account/workspace identifier. That is how earlier customerId-only server events become part of the same customer profile once a user identifies.

Outlit treats organizational domains differently from common personal email providers. An address like [e-mail] can establish company account context, while [e-mail], academic addresses, and other personal/common-provider emails are resolved as personal contacts unless another source links them to an account.

Identifier types

Email (primary)

Email is the most reliable identifier because it’s unique per person, verified through login/signup, and works across devices.

outlit.identify({
  email: '[e-mail]', // Primary identifier
  traits: { name: 'Jane' }
})

External user ID

Your application’s internal user ID (from Supabase, Auth0, Firebase, etc.):

outlit.identify({
  userId: 'usr_12345', // Your auth system's ID
  email: '[e-mail]',
  traits: { authProvider: 'auth0' }
})

Customer ID

Your system-owned customer, account, or workspace ID. Use this when product usage or billing is account-scoped:

outlit.identify({
  email: '[e-mail]',
  userId: 'usr_12345',
  customerId: 'cust_123', // Your app's account/workspace/customer ID
  customerTraits: { plan: 'enterprise' }
})

Server-side track() calls can also use customerId without a user identity:

outlit.track({
  customerId: 'cust_123', // Your app's account/workspace/customer ID
  eventName: 'account_synced'
})

Those events are attributable immediately to the account/workspace and can later link to the contact resolved from email when identify({ email, customerId }) is sent.

Anonymous visitor ID

Generated for browser visitors once tracking is enabled:

// Generated and stored once tracking is enabled (null before then)
const visitorId = outlit.getVisitorId()
// "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

This ID is stored in localStorage and cookies, persists across sessions (same browser), and gets linked to contact after identify. With the default autoTrack: "auto" mode, nothing is stored in regions that require opt-in consent (EEA, UK, Switzerland, or unknown) until enableTracking() runs.

The visitor ID cookie is set on your root domain, so example.com and app.example.com share one ID. Install the Browser SDK on both your marketing site and your app, and identify users after login with setUser() or identify(). Their earlier marketing-site visits then link to the contact. Sites on different root domains don’t share an ID.

Fingerprint (device ID)

For native apps without browser storage (desktop, mobile, CLI), use a fingerprint—a stable device identifier you generate and manage:

// Outlit Rust SDK
client.track_by_fingerprint("app_opened", fingerprint("device_abc123"))
    .send()
    .await?;

// Later, link to user
client.identify(email("[e-mail]"))
    .fingerprint("device_abc123")
    .send()
    .await?;

See Device Tracking for implementation details.

How identifiers connect activity

Outlit links histories when they share an exact identifier, such as the same email or user ID. When two customer records might match but the evidence is ambiguous, Outlit presents a merge suggestion for review instead of combining them automatically.

Linking examples

Same email, different visitor IDs

User visits on phone (visitorId: A), then laptop (visitorId: B), identifies with same email on both.

Result: Both visitor histories link to one contact.

Email change / correction

User identifies as [e-mail], later updates to [e-mail] while logged into same account (userId).

Result: The shared user ID can link activity to the known contact; review conflicting records before any customer merge.

Multiple auth methods

User signs up with email, later links Google OAuth which has different email.

Result: The shared user ID can connect the activity to the same contact.

Earlier visitor events keep their original timestamps when they join a known contact’s timeline. Merging two customer records is a separate reviewed action; see the merge workflow.

Browser vs server identity

Browser tracking

Anonymous visitors are supported

• visitorId generated once tracking is enabled
• Events stored until identification
• Later linked via identify() or setUser()

// Works without identity
outlit.track('page_viewed', { page: '/pricing' })

// Later, when they sign up
outlit.identify({ email: '[e-mail]' })

// Or for SPAs, use setUser after authentication
outlit.setUser({
  email: '[e-mail]',
  userId: 'usr_123'
})

Server tracking

Identity or account attribution required

• User-scoped events use email, userId, or fingerprint
• Account-scoped events can use customerId only
• customerId links account/workspace activity to contacts when identify uses the same ID
• For device/app tracking, use fingerprint (learn more)

// User-scoped event
outlit.track({
  email: '[e-mail]',
  eventName: 'subscription_created'
})

// Account/workspace-scoped event
outlit.track({
  customerId: 'cust_123', // Your app's account/workspace/customer ID
  eventName: 'workspace_synced'
})

Best practices

1. Identify early

Call identify() as soon as you have user information:

// After login
function onLogin(user: { email: string; id: string; plan: string }) {
  outlit.identify({
    email: user.email,
    userId: user.id,
    traits: { plan: user.plan }
  })
}

// After form submission
function onFormSubmit(data: { email: string }) {
  outlit.identify({
    email: data.email,
    traits: { source: 'contact_form' }
  })
}

2. Always send both identifiers

When you have both email and userId, send both:

// Good - creates strong identity link
outlit.identify({
  email: user.email,
  userId: user.id,
  traits: { plan: user.plan }
})

// Less good - single identifier
outlit.identify({
  email: user.email,
  traits: { plan: user.plan }
})

Review identity across connected sources

Tracking identifiers are one part of customer identity. Outlit also links records from connected billing, CRM, and other sources to the customer profile. Open the customer’s Coverage tab to inspect the sources behind that account and investigate missing or unexpected matches.

An Identity review page is available in some workspaces for inspecting identifiers and merge suggestions. Ask your Outlit contact about access. Identity resolution continues to operate when this review page is unavailable.

For programmatic diagnosis, use outlit customers identity <customer-uuid> and outlit identity suggestions list. Customer merges require exact IDs and a reviewed preview before execution. Follow the merge workflow rather than merging based on a similar name alone.

Debugging

Common identity issues:

• Events not linking to user: Ensure identify() is called after authentication and that email/userId matches what you expect.
• Duplicate customer profiles: Inspect their identifiers and source coverage. Different emails, missing shared identifiers, and personal-email accounts can produce separate records. Review any merge suggestion before combining records; contact Outlit when the correct match is unclear.
• Anonymous history not appearing: The identify() call must carry the same browser/device identifier used for the earlier activity. Check that tracking was enabled and the same public key was used, then allow for background processing.

Next steps

Website visitors

Deep dive into the anonymous phase

API reference

Direct API for custom integrations