Client applications submit requests to UCS to identify contacts. UCS takes the contact data provided to the identify request (OMContacts/Identify) and tries to match it with its existing contact records based on certain attributes.
The attributes of the request OMContacts/Identify are the following:
- DatePattern—Defines how dates are formatted in the following attributes.
- CreateContact—Allows the creation of a new Contact if none was found.
- TenantId—The tenant where the Contact is to be found or created.
- SubscriberId—The subtenant where the Contact is to be found or created.
- MediaType—Defines how the contact should be identified, and what attributes are to be expected.
- <Contact Attribute>—The parameters that will be used to find or create the contact.
The identify request provides a media and several contact attributes.
- Contact identification is based on lookups.
- Lookups are specified per media.
- Lookups can be customized per media.
- If identification request has no media specified the media any is used.
- Default lookups are preconfigured for media any.
- When media has no custom lookups, the default ones are used (the same lookups as media any).
- As UCS allows multiple contacts with the same attributes (for example multiple contacts sharing the same email address), the default lookups are non unique.
- If CreateContact is set to true and the mandatory attributes are provided, then UCS searches for the contact in lookups related to the attributes from the identification request.
- If the contact is not found, it is created. Then the ID of the newly created contact is returned.
- If the contact is found, then the related ID is returned.
- If CreateContact is set to false, then UCS does not try to create the contact, but rather tries to identify it according to the selected lookup tables.
- By default, CreateContact is true.
- Creation of contact can be disabled for a media. If the option create-contact in section settings in the Annex tab of the media is set to false, UCS will perform identification only (no creation) for this media. This behavior is overridden if create-contact with value true is provided in the identification request.
- Creation of a contact can be allowed for a media only if a few mandatory attributes are present in the identification request. A comma-separated list of mandatory attributes must be set in the option minimum-creation-attributes in section settings in the Annex tab of the media. Example:
An identification strategy is a list of lookup tables applications use to identify a contact.
The identification strategy primarily depends on the media. For example, when receiving a phone call, the application probably wants to identify the contact with the caller phone number. However, the application that receives an email will rather use the From: address.
- The default strategy for email is EmailAddressLookup.
- The default strategy for voice is PhoneNumberLookup.
- There is no default strategy for SMS. A typical strategy is PhoneNumberLookup, EmailAddressLookup.
Configuring Identification Strategies
The list of lookup tables is defined for each tenant in the corresponding Media Type Business Attribute. The media any defines the default lookup list, and each media (email, chat,...) defines its own lookup list.
In the Annex tab of the media, under the section settings, the option names are identify-contact-1, identify-contact-2, identify-contact-n .
The value can be either the name of an existing lookup or a list of contact attributes separated with comma.
- If the value is EmailAddress, then the existing EmailAddressLastNameFirstNameLookup will be used.
- If the value is _facebookId, then UCS will create a custom lookup at first startup, with the condition that the _facebookId attribute is unique across all the contacts.
There are a number of predefined lookups (see Default Lookups).
A lookup table indexes contacts, according to one or more attributes.
FacebookIdLookup and TwitterIdLookup have a key made of only one attribute (FacebookId and TwitterId respectively), but it is possible to configure a lookup with a composite key—for example (PhoneNumber + FirstName) if different people are using the same phone line and need to be tracked separately.
The lookup tables must be created prior to starting UCS, and cannot be dynamically modified.
Unique, Multiple, and Regular Lookups
- Unique lookups, where a given key corresponds to a single item.
- Multiple lookups, where a given key can be associated with multiple values.
- Regular lookups, where a given key can be associated with a single item, but which allows other values when secondary keys are provided.
If a multiple lookup is selected, UCS returns the first result. In this case only, the result parameter NumberOfContactsFound can be greater than 1. You must expect unpredictable results if the lookup is not sorted. If no contact is found, no contact will be created and the parameter CreateContact is ignored.
EmailAddressLastNameFirstNameLookup and PhoneNumberLastNameFirstNameLookup are regular lookups because they can be searched with predictable results by providing the EmailAddress or the PhoneNumber alone. However, they can also be searched with unpredictable and possibly different results when providing optional parameters LastName and FirstName.
The default behavior of UCS 9 provides a similar default identification algorithm as UCS 8.x. To achieve this, some lookups are configured by default.
- The following are defined as regular lookups:
- EmailAddressLastNameFirstNameLookup—A non-unique lookup on the Contact’s EmailAddress, LastName, and FirstName parameters.
- PhoneNumberLastNameFirstNameLookup —A non-unique lookup on the Contact’s PhoneNumber, LastName, and FirstName parameters.
- The following are defined as multiple lookups:
- LastNameFirstNameLookup—A multiple lookup on the Contact’s FirstName and LastName parameters.
- FirstNameLookup—A multiple lookup on the Contact’s FirstName parameter.
The default value for the default media any is hard-coded to:
Unless otherwise configured, and whatever the media, the contact is always identified:
- First by email address.
- Then by phone number.
- Then by last name plus first name, or last name only.
- Finally by first name only.
Users can configure their own lookups through the REST API by using the createIdentificationKeysSchema request.