External ID for Creating and Updating Users

An external ID is a unique contact identifier generated in your system. We recommend using an external ID as the main identifier in the API request field externalCustomerId (or user_id). It will help you to avoid duplicating contact profiles, collect all available data into a single contact profile, and get as complete information as possible about their interaction with your company.

Identifier Types

There are 2 types of contact identifiers — conditionally permanent and changeable:

• conditionally permanent — email, phone number, and other contact data received during contact’s registration.
• changeable — web cookies, mobile and web tokens.

As a rule, changeable IDs enter the system first, but the external ID is only linked to conditionally permanent IDs.

To better understand how contact data enters the system and how to optimize contact identification, consider 2 basic use cases: creating contacts from mobile applications and websites.

Use Case 1. Creating and Updating User from the Mobile App

1. User installs the application on a mobile device with Android OS.
2. The application transfers user's mobile token to eSputnik (API method Add/update a contact).
3. eSputnik creates user profile with this token as an ID.
4. User registers in the application.
5. Conditionally permanent identifiers such as email, phone number or name get into your system.
6. Your system assigns this user a unique ID and passes it to eSputnik along with other identifiers, including a mobile token (API method Add/update a contact).
7. eSputnik finds user profile with this mobile token and updates its profile by writing new identifiers to it.

Use Case 2. Creating and Updating User for the Website

1. Non-logged-in user visits your site.
2. Appropriate cookies are transmitted and recorded in eSputnik. User profile is not created (web tracking script is used).
3. User registers on the site or subscribes to the newsletter.
4. Conditionally permanent identifiers such as email, phone number or name get into your system.
5. Your system assigns this user a unique ID and passes it along with other IDs to eSputnik (Add/update a contact or Subscribe contact).
6. eSputnik saves the user with all transferred identifiers and adds their previous history of interaction with your site (cookies).

After user profile has been created in eSputnik with an External customer ID field, we recommend making each its update by externalCustomerId — for example, at login (Add/update a contact) or creating order (Add orders or Generate event). In this way, you will be able to constantly maintain the relevance of all user data since externalCustomerId is unique and immutable, while other identifiers, even conditionally constant ones, can change.

External User ID for Mapping Events with Users

The system automatically links events to user with the help of an event parameter that contains user identifier. If user ID is not specified in the event, the system searches the ContactId event parameter by default.

If you pass the identifier in the externalCustomerId field to the event, you do not need to configure the mapping additionally. But if this ID is passed in a field with a different name, it must be correlated with the External customer ID system field.

To do this:

1. Go to your account settings -> Events.

2. Enable Use custom parameter for event assignment switcher. Set your parameter name and select the External customer ID contact field.

3. Click Save.

External User ID in Single Contact API Methods

Updated logic of single API methods:

Add/update a contact

The system searches for a user by external ID when get a request:

• if contact profile with this external ID is found, it is updated with the data from the request;
• if contact profile with this external ID has been removed, it will be restored;
• If contact profile is not found, it will be created in the system;
• if there is no external ID in the request, the creation logic remains unchanged.

Update contact

The contactId is specified in the request URL, and the external ID is passed in the body:

• if this external ID already belongs to a contact with another contactId, an error will occur;
• if the external ID does not belong to another contact, the contact will be updated and given that ID;
• if there is no external ID in the request, the creation logic remains unchanged.

Get contact

The external ID is added to user data returned by request.

Subscribe contact

The external ID has the highest priority in the user search logic; if the contact profile with this identifier is not found, the system searches for it by email address, if the email is not found — by phone number.

External User ID in Bulk Contact API Methods

Updated logic of bulk API methods:

Search contacts

You can set the uniqueness of the contact search by the externalCustomerId field. In this case, you cannot set other search parameters.

Add/update contacts

When importing users to eSputnik, you can use any field to define their uniqueness. For example, import users with uniqueness by email and at the same time add or update their external ID.

Export External User ID to BigQuery and PostgreSQL

Export external IDs to BigQuery and PostgreSQL — they will appear in the corresponding column in the contacts table. By default, this option is available for all new exports. If you need to create one for existing exports, please contact our support team.