Establish identity

🚧

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, you can 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 merge simplifies the ongoing maintenance of user attributes and allows you to use personalization without worrying about what attribute is stored in which contact record.

Prerequisites in Acoustic Campaign for calling the Establish Identity API

• Flexible (Non-keyed) Database
• REST API application tokens
• Custom lookup field in the database that is unique and identifies your customer. For example, account ID or an alphanumeric value.
• If your mobile push database contains required columns, ensure that those values are present in the records. There should be no missing values in the record 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"
  },
  "useCrmContactAsWinner": "Boolean"
}

Example:

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

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

Response

The API response will return the winner record. The winner record is the base record used for merging. Therefore, it has the system attributes of the oldest record and the newly created user attributes.

The following attributes are returned as part of the response that identifies the winner record:

Example Response for successful call

{
    "meta": {
        "attributes": {},
        "generalErrors": [],
        "fieldErrors": {},
        "links": [],
        "nextPageUrl": null
    },
    "data": {
        "winnerRecipientId": 3111723279,
        "winnerChannelIdentifier": "GuYYBfF6lEaWr6Qb"
    }
}

Use case

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 – [email protected]
Channel: Zujdd9d
Last modified: August 7, 2017

Contact specified by MUID/channel ID:

Created: August 15, 2017
MUID – Sksd03jdJKK
userId = null
Favorite Food – Burger
System column – Email – [email protected]
Channel: H892hH
Last modified: August 16, 2017

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

Resulting merged contact:

Created: August 15, 2017
MUID – Sksd03jdJKK
userId = 777374
Favorite Food – Burger
System column – Email – [email protected]
Channels: H892hH, Zujdd9d
Last modified: date/time of merge

Merge contacts from CRM and push enabled databases

When the database used to merge is enabled for CRM, the following merge logic is followed:

• The winner record (the base record used for merging) will be the record with CRM_Sync_ID.

📘

Note:

The lookup field should be unique per customer.

• The system fields from the winner record, including the CRM default fields CRM_Sync_ID, CRM_Contact_Type, CRM_Account_ID, and CRM_Enable_Sync, are merged.
• All user attributes from the winner record are merged.
• The attributes that are blank in the winner record but are found in the other record, including, but not limited to, the mobile user ID, are merged.

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