# Identity Resolution ExternalIDs

* FREE: x
* TEAM: x
* BUSINESS: ✓
* ADDON: ✓

Unify requires a Business tier account and is included with Engage.

See the [available plans](https://segment.com/pricing), or [contact Support](https://segment.com/help/contact/)

> \[!NOTE]
>
> For spaces created after September 27th, 2020, please refer to the [Identity onboarding guide](/docs/segment/unify/identity-resolution/identity-resolution-onboarding/).

## 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.

> \[!TIP]
>
> Navigate to **Unify > Profile explorer** to view identities attached to a profile, along with custom traits, event history, and more.

![A sample profile's identity list that includes email, user\_id, and multiple anonymous\_ids.](https://docs-resources.prod.twilio.com/82c79ffaf9a742f440fe4433edd8ae491eb1bbfa95c3f4ccf2eeaa704cc58b42.png)

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

| External ID Type    | Message Location in Track or Identify Call                                                                    |
| ------------------- | ------------------------------------------------------------------------------------------------------------- |
| user\_id            | userId                                                                                                        |
| email               | traits.email, context.traits.email or properties.email                                                        |
| android.id          | context.device.id when context.device.type = 'android'                                                        |
| android.idfa        | context.device.advertisingId when context.device.type = 'android' AND context.device.adTrackingEnabled = true |
| android.push\_token | context.device.token when context.device.type = 'android'                                                     |
| anonymous\_id       | anonymousId                                                                                                   |
| ga\_client\_id      | context.integrations\['Google Analytics'].clientId when explicitly captured by users                          |
| ios.id              | context.device.id when context.device.type = 'ios'                                                            |
| ios.idfa            | context.device.advertisingId when context.device.type = 'ios'                                                 |
| ios.push\_token     | context.device.token when context.device.type = 'ios'                                                         |

> \[!NOTE]
>
> The Google clientID (ga\_clientid) is a unique value created for each browser-device pair and will exist for 2 years if the cookie is not cleared. The analytics.reset() call should be triggered from Segment end when the user logs off. This call will clear the cookies and local Storage created by Segment. It doesn't clear data from other integrated tools. So on the next login, the user will be assigned with a new unique anonymous\_id, but the same ga\_clientid will remain if this cookie is not cleared. Hence, the profiles with different anonymous\_id but with same ga\_clientid will get merged.

## 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:

| Key        | Value                                                                        |
| ---------- | ---------------------------------------------------------------------------- |
| id         | value of the externalID                                                      |
| type       | name of externalID type (`app_id`, `ecommerce_id`, `shopify_id`, and more)   |
| collection | `users` if a user-level identifier or `accounts` if a group-level identifier |
| encoding   | `none`                                                                       |

As an example:

```js
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:

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

You can also include `phone` using the [`context.traits`](/docs/segment/connections/sources/catalog/libraries/website/javascript/identity/#saving-traits-to-the-context-object) object and Unify adds it as an externalID to the profile.

```js
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:

![Raw payload showing external\_ids with collection, type, id, and encoding details for user events.](https://docs-resources.prod.twilio.com/7061580d7d50d89dfc65a634da3986a080db7466141900effd28f18f017b7640.png)

## Example

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

```js
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`.

![An anonymous user associated to an external id in the Identity Graph.](https://docs-resources.prod.twilio.com/27cd8dda5207f43b32b187781f768b68ebb4d0206e45a5c7deaa5ff6c3bd282c.png)

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:

```js
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`.

![Identities associated to a user in the Identity Graph.](https://docs-resources.prod.twilio.com/db548f660ee4952496ceb9f0d0900ba686378075310d94704dd98dba998566c3.png)