Jump to: navigation, search

Identify Customer

Prerequisites: You need to enable profiles in UCS.
GET /profiles


Identifies a customer based on the Identification Key information submitted with the query. In addition to the identified customer ID, your application can retrieve profile and extension information based on the query fields. Query strings should be URL Encoded. If the "id_key" parameter is not specified, then UCS uses the following algorithm:

  1. Starting with the identification key with the lowest ID, UCS determines the number of attributes in the key which are covered by the data specified in the "expr" parameter.
  2. If all attributes are covered, then use this key. Otherwise, record the number of sequential attributes covered, starting from the left. For example, if key 1 consists of attributes (a, b, c), and "expr" contains (a, b) then the score is 2.
  3. If no key is selected after iterating through all the defined keys, choose the key with the highest score from Step 2. In the event of a tie, UCS selects the key with the smallest ID.



  • The identification keys exist.
Use the Create Identification Key operation to create Identification Keys.
Method GET
URL /profiles
Field Name   Type   Mandatory Description
URI Parameters
id_key string no The key name used for identification.

UCS can infer the key based on the attributes included in the "expr" parameter. However, explicitly specifying the identification key with your application improves performance.

include_profile token no
  • "no" (default) to return the list of customers IDs without their profile attributes.
  • "yes" to return all the profile attributes of the identified customers.
extensions string no The names of the extension to return with the customer profiles. Your application can specify multiple values separated with comas, such as: extensions=contacts,purchases
include_extensions token no
  • "always" (default) to return the extensions specified with the field "extension" if one or more customers are identified.
  • "unique" to return the extensions identified in parameter "extensions" if a unique customer is identified.
<attribute name> string yes One or more identification keys used to identify the customer, for instance: last_name=Doe&first_name=Jane

Attribute names with no prefix are supposed to be profile attributes. To refer to the attributes of an extension, your application must use the extension name as a prefix for the attribute: <ext-name>.<attribute-name>


The Context Management Service API answers with HTTP codes for every request. The following table shows the correct response for a successful request. See HTTP Response Codes and Errors for further details on the possible codes that this operation can return.

HTTP code 200
HTTP message OK



 GET /profiles/contacts.phone_number=408-888-3214&extensions=contacts,purchases&include_profile=yes

Result: Multiple profiles
If multiple customers called from the specified phone number, then the output contains profiles for each matched customer:

 200 OK
 [{"customer_id": "2DC255C02AF", "name": "Doe, John", "birthdate": "1976-05-10"},
 {"customer_id": "DDF295802AF", "name": "Doe, Jane", "birthdate": "1978-02-25"}]

Result: One profile
If a single customer is called from the specified phone number, then the complete profile for that customer is returned.

200 OK
{ "customer_id": "0004Va58A92T0017 ", 
 "name": "Doe, John", 
 "birthdate": "1976-05-10",
 "EmailAddress": [
 "contacts": [
  {"phone": "408-555-1234", "ext": "1234"},
  {"phone": "408-832-7712"} ],
 "preferences": { "newsletter": "y", "new_offers": "n", "email": "html" } 

Result: No result
If no customers match the specified criteria, then the output is an empty array:

This page was last edited on September 7, 2018, at 10:34.
Comments or questions about this documentation? Contact us for support!