Establish Identity API

WARNING: This API results in a contact merge that is not reversible. Contact your onboarding specialist, services consultant, or Support, to discuss your specific use cases prior to implementation.

Overview

Within a mobile-enabled database, SDK generated contacts are created for each device. Using the Establish Identity API allows you to merge two contacts together to leverage the presence of attribute data in a single existing contact. The merge also conveniently associates each merged device with a single contact so that you can easily send push notifications to an individual and reach all of their registered devices with minimal effort.

• email
• SMS
• push

• email – email address
• SMS – phone number
• push – device association with token/registration id

Prerequisites in WCA for calling the Establish Identity API

• Flexible (Non-keyed) Database
• REST API application tokens
• Custom lookup field in the database that is a unique custom field that identifies your customer (for example: account ID or an alphanumeric value)
• If your mobile push database contains columns that are defined as required, ensure that values are present in records that you want to use when calling the Establish Identity API. If a column requires a value but the value is missing, the Establish Identity API call fails with a 500 error.

Attributes that are required for the Establish Identity API

• Channel (channel for Push or SMS)
• Qualifier (appkey for PUSH or campaign name for SMS)
• Destination (MUID|MobileChannelID for Push or SMS phone number for SMS)
• EstablishIdentitySpecification (JSON body includes the lookup key as the name attribute and the value)

EstablishIdentitySpecification Structure

{ "identity":{ "name":"string", "value":"string" } }

Example:
{ "identity":{ "name":"Alias Id", "value":"UserAccount4567" } }

Example API URL
https://api[your pod number].silverpop.com/restdoc/#!/databases/establishidentity_put_put_13

The use case that Establish Identity exists to fulfill is the association of one or more devices with a contact row in the database that contains extra contact attributes (name, email, and so on). A common approach is to pre-populate your mobile-enabled database with contact rows for all of
your customers and include more contact attributes such as email, name, and loyalty card information. One of these unique attributes are designated the lookup-key that you then use to merge devices.

Then, using an identification or authentication process, you collect the device/contact association and call the Establish Identity API to associate a device with an identified contact by lookup-key value. This process merges multiple devices for a user (iPhone and iPad, for example) into a single contact with pre-populated user attributes (name, email).

The term lookup-key contact refers to the contact row in the database that matches your lookup-key value that is provided in the Establish Identity API call.

Using a Facebook ID as the identity lookup-key and the call Establish Identity API to associate a device with an established contact row with your mobile-enabled database, the following outcomes are possible:

• If the device for which you are making the Establish Identity call does not exist due to the use of an incorrect MUID or channel ID, the API returns 404 – Not Found.
• If no contacts with that identity lookup-key value are in the database when you make the Establish Identity call, then the contact that is associated with the device you are attempting to merge is assigned the lookup-key value that was provided.
• If a different contact matches the identity lookup-key value, then the device and contact fields are merged. For example, if deviceA >contactA captures favoriteFood and contactB does not have favoriteFood, then the final contact contains favoriteFood. The Establish Identity API call is merging the device with the contact that has the matching identity lookup-key value. If merged devices are already present in the contact that matches the lookup-key value, then the new device is merged with them.
• Devices that are merged will have inbox messages that are available (depending on expiration dates) from the latest created contact.
• When merging a device that is associated with a contact that already has a lookup-key value and one or more associated devices (that were previously merged into that contact), all devices that are associated with the merge candidate are moved to the contact that matches the lookup-key that is provided in the Establish Identity API call.

It is the responsibility of the user to implement business logic that enforces proper merging of contacts. Do not use Establish Identity if you expect that multiple users share a device.

Potential API Outcomes

For the purposes of the discussion, note that device or merging contact refers to the contact/device that you specify to the Establish Identity API that uses MUID and channel ID. A lookup key contact refers to the contact specified by the lookup key and value found in the EstablishIdentitySpecification json. Every row in your push-enabled database is a contact. Every contact row in your push-enabled database that is created by an SDK app registration has a single device that is associated with it.

The use of the Establish Identity API merges an existing device that is associated with a contact row in your push-enabled database with another contact row in your database. As a result of this merge, only a single contact will remain. However, the precedence used to determine which attributes are favored when merging requires some discussion.

System attributes are taken from the earliest created or oldest contact.

System attributes include:

• Lead_source: from master contact
• CRM_sync: column is not merged
• Email system columns:

• If both contacts have values and both have the same values, the resulting merged contact will adopt the email of oldest or most aged contact. 
• If both contacts have values and they differ, the value is adopted from the oldest contact record.
• If only one contact has a value, it is adopted in the merged record.

• Last modified: a new timestamp is generated upon merge.
• Others are ignored.

Non-system attributes (all other attributes including attributes you create) are taken from the latest created or newest contact in the database. This includes MUID. When merging 2 contacts that each have a MUID assigned, the resulting MUID is that of the latest created or newest contact.

Note that regardless of the precedence above, if any attributes are null, the attribute value that is retained is the value that is not null.

A Simple Example

databaseId: 99999
channel: PUSH (push channel)
qualifier: ap56921D (app key)
destination: Sksd03jdJKK|H892hH (MUID | channel)
EstablishIdentitySpecification: { "identity":{ "name":"userId", "value":"777374" } }

Resulting API call URL structure: /databases/99999/establishidentity/PUSH-ap56921D
/Sksd03jdJKK|H892hH

Contact specified by lookup key:

Created: August 1, 2017
MUID – ZMjue73FFG
userId – 777374
Favorite Food – Pizza
System column – Email – albert.b.jerm@gmail.com
Channel: Zujdd9d
Last modified: August 7, 2017

Contact specified by MUID/channel ID:

Created: August 15, 2017
MUID – Sksd03jdJKK
userId = 777374
Favorite Food – Burger
System column – Email – bertrand.jerm@gmail.com
Channel: H892hH
Last modified: August 16, 2017

Execute API call:

/databases/99999/establishidentity/PUSH-ap56921D/Sksd03jdJKK|H892hH
{
    "identity": {
        "name": "userId",
        "value": "777374"
    }
}

Resulting merged contact

Created: August 15, 2017
MUID – Sksd03jdJKK
userId = null
Favorite Food – Burger
System column – Email – albert.b.jerm@gmail.com
Channels: H892hH, Zujdd9d
Last modified: date/time of merge

{ "identity":{ "name":"string", "value":"string" } }

{ "identity":{ "name":"Alias Id", "value":"UserAccount4567" } }

https://api[your pod number].silverpop.com/restdoc/#!/databases/establishidentity_put_put_13

Calling the wrong contact

Question: What happens when establishidentity calls the wrong contact?

Answer: If establishidentity is called on the wrong contact, for example a bad MUID or channel ID, the result is a 404 failure.

Contact or channel has no identity

Question: What happens when a contact/channel in the database just has an MUID/channel ID and no identity yet.?

Answer: When establishidentity is called with a new identity that is not already in use, for example, newidentity1234, the call is successful and the contact can be addressed as “newidentity1234”.

Contact has an old identity

Question: Contact or channel in the database has an identity that is assigned in the past?

Answer: Establishidentity is called for a contact that is not already in use, the call is successful and has a new identity, “newidentity1234”. The contact is not accessible as “oldidentity1234”. “oldidentity1234” is no longer in use.

Two contacts or channels

Question: What happens when two contacts or channels are called?

Answer: One contact (contact A/channel A) has an identity, “identity1234” assigned to it via a previous establishidentity call. A different contact (contact B/channel B) has no identity that is assigned to it yet.

When Establishidentity is called for contact B/channel B with “identity1234”:

• Contact A is merged with Contact B.
• Contact A is removed.
• A single contact, contact B, the result of merging A with B, remains and is addressable as “identity1234”.
• Contact B has two channels, channel A and channel B.

Two contacts or channels with identities assigned

Question: What happens when two contacts or channels already have identities that are assigned?

Answer: Contact A/channel A (“contactA1234”) and Contact B/channel B (“contactB5678”) already have identities that are assigned. Establishidentity is called with Contact B/Channel B to assign it the identity “contactA1234”.

When Establishidentity is called for Contact B/Channel B to assign it the identity “contactA1234”:

• The system merges contact A with contact B.
• Contact A is removed.
• A single contact (contact B, the result of merging A with B) is created and is addressable as “contactA1234”.
• Contact B has two channels (channel A and channel B).

Go Back to the Mobile App Messaging home page.