Identity Resolution ExternalIDs

Default externalIDs

The Identity Graph creates or merges profiles based on externalIDs. ExternalIDs will become the identities attached to a user profile in the Profile explorer.

Segment automatically promotes the following traits and IDs in track and identify calls to externalIDs:

Custom externalIDs

Unify resolves identity for any other externalIDs that you bind to users - such as a phone number or any custom identifier that you support.

As long as you’ve configured custom externalIDs, such as phone, in your Space’s Identity Resolution rules, you can include it with the context.externalIds array, the properties object, or the context.traits object.

As seen in the example below, you can send custom externalIds in the context object of any call to Segment’s API.

The four fields below (id, type, collection, encoding) are all required:

As an example:

analytics.track('Subscription Upgraded', {
   plan: 'Pro',
   mrr: 99.99
}, {
  externalIds: [
    {
      id: '123-456-7890',
      type: 'phone',
      collection: 'users',
      encoding: 'none'
    }
  ]
})

Additionally, adding phone with the properties object gets picked up by Unify and applied as an externalID:

analytics.track('Subscription Upgraded', { plan: 'Pro', mrr: 99.99, phone: '123-456-7890'})

You can also include phone using the context.traits object and Unify adds it as an externalID to the profile.

analytics.track('Subscription Upgraded', { plan: 'Pro', mrr: 99.99}, {traits : {phone_number: '123-456-7890'}})

Unify creates a user (user_id: use_123) with the custom externalID (phone: 123-456-7890). Query the user’s phone record by using the externalID (phone: 123-456-7890), or update the profile with that externalID going forward. (Note: externalIDs must be lower-case.)

Viewing promoted externalIDs

Users can view which externalIDs are promoted on each event by viewing the raw payload on Events in the User Profile in the “external_ids” object.

For example, the following user had anonymous_id and user_id promoted as identifiers from the Course Clicked track call:

Example

For example, a new anonymous user visits your Pricing page:

analytics.page('Pricing', {
  anonymousId: 'anon_123'
  title: 'Acme Pricing',
  url: 'https://acme.com/pricing',
  referrer: 'https://google.com/'
});

At this point, the Identity Graph will create a new user with external id (anonymous_id: anon_123) and a persistent and globally unique segment_id, in this case: use_4paotyretuj4Ta2bEYQ0vKOq1e7.

Any new events received with the same external id (anonymous_id: anon_123) are appended to same user use_4paotyretuj4Ta2bEYQ0vKOq1e7.

Next, the user goes to a sign up form and signs up:

analytics.track('User Signup', {
  userId: 'use_123',
  anonymousId: 'anon_123'
});

At this point, the Identity Graph associates external ID (user_id: use_123) with the same user use_4paotyretuj4Ta2bEYQ0vKOq1e7.