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.

Conceptually, there are three contact types of interest for this API:

  • email
  • SMS
  • push

Each of these records minimally captures certain user attributes:

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

The Establish Identity API allows you to merge these contact types into a single contact record where you can capture and store specific user attributes such as name, loyalty card information, account number, etc. in a single record. This simplifies ongoing maintenance of user attributes and allows you to use personalization without worrying about what attribute is stored in which contact record.

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)
Parameter Value Description Parameter Type Data Type
databaseId required Database ID for PUSH application or SMS campaign path long
channel required Channel (SMS/PUSH) path String
qualifier required AppKey for Push application path String
destination required Destination for this contact (mobile user ID and channel ID for PUSH/SMS phone number for SMS) path String
EstablishIdentitySpecification required Establish identity Specfication data body Model

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.


12 comments on"Establish Identity API"

  1. Noam Oded June 13, 2017

    Hi. I did not completely understand where do I need to set each parameter in the API call:
    does “path” mean in the url (as in QueryString) ?
    does “body” mean json body in http POST request?
    also:
    1.where di I find my databaseId in the WCA console? ic was not able to find it.
    2.what is Xtify user ID ?
    3. what the difference between channel and channelID?
    4. in the ‘EstablishIdentitySpecification’ body , does ‘name’ field should contain the field name of the contact ‘lookup key’ in the database (like email)?
    5. where do I set the ‘MobileUserId’ filed that is generated by the mobile SDK (iOS & Android)?

    thank you

    • Hello Noamo,
      I have been made aware that our Customer Support team has assisted you with these questions.

      Thank you
      Jeri

  2. Good respond in return of this difficulty
    with genuine arguments and explaining all
    concerning that.

  3. Is this every Establish API call will create any new Data Job with description (Merge duplicate contacts to master contact from contact source, and delete deprecated contacts.)?
    Is there any reason?

    • Hello Shahin,
      I’m not sure what you are asking. Can you provide more information?

      Thank you
      Jeri

  4. My app has a log-in screen.
    More than one user can log-in at different times.
    How can I separate them so that I won’t send a push notification to the wrong device and capture wrong behaviour data for that user? And how can I detect if the user is logged in before sending this push notification?

    Also, a single contact can access my app through multiple devices. How can I merge these devices to the same user account/contact?

    • Hi Jared,
      I am researching this information and I will get back to you.

      Thank you,
      Jeri

  5. Morish Gohil February 22, 2019

    Hi, i am trying to use Establish Identity API to merge multiple contacts based on Mobile number in my WCA Database.

    Email Mobile Mobile User Id
    morish@gmail.com 855000000 8Y7G05cJmDO8Fgkw
    sid@gmail.com 855000000 WX4R33lldEW3ERBe
    Blank 855000000 SDF2fdsDSEGW1gre

    In this database Mobile is the custom look up field

    This is one of the URL generated from SDK from which i have picked channel ID
    https://sdk6.ibm.xtify.com/dla/1.0/apps/bcnuissCQO/users/WX4R33lldEW3ERBe/channels/Zeiron7X/locations/?uuid=your_beacon_UUID

    I am currently using Swagger UI to push

    https://api6.ibmmarketingcloud.com:443/rest/databases/2630000/establishidentity/Push-bcnuissCQO/WX4R33lldEW3ERBe%7CZeiron7X

    and EstablishIdentitySpecification parameter as

    {
    “identity”: {
    “name”: “Mobile”,
    “value”: “855000000”
    }
    }

    I and getting the below response.

    Response Body : no content
    Response Code : 200
    Response Headers :
    {
    “Date”: “Fri, 22 Feb 2019 11:19:21 GMT”,
    “Server”: “”,
    “Connection”: “Keep-Alive”,
    “Keep-Alive”: “timeout=15, max=100”,
    “Content-Length”: “0”,
    “Content-Type”: “text/plain; charset=UTF-8”
    }

    1 : Please help me fix the error.
    2 : What will be the final output when the API is called correctly. as per the document it should create a single row for all the 3 device and latest user attributes will be updated.

  6. 1) Please can you document the response json in the event or a correct merge.
    2) please can you document the response json and error codes in case of common errors.
    3) a number of different errors result in same 404 response, please can you document the different possible “generalErrors” error messages as this needs to be parsed to read the string (e.g. “Database not found”) so we can assigned them unique error codes and process accordingly. We assume thest message strings are fixed, so we can parse for them.

    • Hello John,
      I have reached out to the team to see what we can provide for you. I will be back in touch.

      Thank you
      Jeri

  7. 1) Please can you document the response json in the event or a correct merge.
    2) please can you document the response json and error codes in case of common errors.
    3) a number of different errors result in same 404 response, please can you document the different possible “generalErrors” error messages as this needs to be parsed to read the string (e.g. “Database not found”) so we can assigned them unique error codes and process accordingly. We assume thest message strings are fixed, so we can parse for them.

    • Hello Simon,
      I have reached out to the team to see what we can provide for you. I will be back in touch.

      Thank you
      Jeri

Join The Discussion

Your email address will not be published. Required fields are marked *