Auto-Linking, Basic Search and Detailed Lookup

13 min read

This guide provides detailed information for Customer Lookup queries.

How Do I Know A Profile Is Linked? #

You’ll know a Profile in Gladly is linked to an external system if you see a purple link underneath the Customer avatar.

This Profile is not linked.

This Profile is linked.

Request Structure #

The request structure Gladly sends to your Lookup Adaptor

depends on the request type sent.

In general, requests follow this structure:

Text

{
    "lookupLevel": "BASIC",
    "query": { ... },
    "uniqueMatchRequired": false
}

lookupLevel tells the lookup level: Auto-Linking and Basic Search requests are set to BASIC, whereas Detailed Lookup requests are set to DETAILED
query varies by the request type
uniqueMatchRequired is set to false for Auto-linking and Basic Search requests and true for Detailed Lookup requests

Read below to learn more about the differences between Auto-linking, Basic Search, and Detailed Lookup requests.

Response Structure #

The response structure your Lookup Adaptor should send back must match the following format:

Text

{
  "results": [
    {
      "externalCustomerId": "12345",
      "customAttributes": {
        "key": "value"
      },
      "transactions": [
        {
          "type": "GENERIC",
          "key": "value"
        }
      ],
      "emails": [
        {
          "original": "[email protected]"
        }
      ],
      "phones": [
        {
          "original": "+11234567890",
          "type": "MOBILE"
        }
      ]
    }
  ]
}

Each response is an Object, with a single key called results.
results is an Array of Customer Profile objects.
- Each Customer Profile object must have externalCustomerId set, which is the unique profile identifier in your Lookup Adaptor system of record.
- Each Customer Profile object may contain a customAttributes object, which are single-level key-value pairs of extended profile-level information to display on the Gladly Customer Profile. There is no nesting capability.
- Each Customer Profile may contain an address or name field, which are the customer’s address/name.
- Each Customer Profile may contain emails and/or phones Arrays whose formats are documented here.
- Each Customer Profile object may contain a transactions Array, which contains transaction objects that can be displayed. These objects only display during a Detailed Lookup, so there is no need to send them back in response to an Auto-Linking or Basic Search request
  - Each object in the transactions Array must have a type, which controls the layout of the transaction in Gladly. Gladly supports ORDER, FLIGHT, STAY, SUBSCRIPTION, or GENERIC layouts, which we cover in the Transaction Cards section. You can specify additional single-level key-value pairs in each transaction for Gladly to display. There is no additional nesting, with the exception of the products Array for ORDER and SUBSCRIPTION type transactions and the fulfillments Array for ORDER type transactions, which we cover in a subsequent section.

When a successful Detailed Lookup occurs, the above information maps in the following way to the Customer Profile in Gladly:

Watch Out – Specify unique customAttribute keys for each Lookup Adaptor

You should specify unique customAttribute keys for each Lookup Adaptor so they don’t accidentally override one another.

Note – Deep Links

If you send a value in a custom attribute (e.g: “14”), Gladly can use that value to create a deep-link using a static template.
For example, we can turn “14” into https://www.google.com?q=14 .
Link templates are static and dependent on the value returned in the custom attribute (i.e. exactly one dynamic value that must be part of the URL).
If you’d like to configure links in your Lookup Adaptor, work with your Gladly team.

Tip – All values must be returned as STRING

All values must be returned in STRING format. For example, external CustomerId should be return as a STRING in your response even if it is an integer in your system of record. Similarly, all values in the customAttributes object must be set to STRINGs in your response, even if they may be other formats (e.g.: boolean) in your system of record. Gladly will fail the lookup response otherwise.

Auto-Linking #

Trigger Criteria #

This trigger criteria happens when an Agent loads an unlinked Customer Profile on Gladly (e.g.: an Agent could load the Profile when they receive an email from a Customer) or makes an alteration to an unlinked Customer Profile on Gladly.

The request is also made when a new Contact comes in on an unlinked Customer Profile.

If the Profile has previously been unlinked, the Auto-Linking request will not trigger ever again.

The request payload includes most information Gladly has about the Customer. If Gladly identifies multiple matches in the System of Record, it will present Suggestions on the Customer Profile.

A Profile will be Auto-Linked if:

Auto-Linking is turned on in App settings in Gladly
Lookup Adaptor returns a well-formatted response, with only one result in the results Array
If email Auto-Linking is turned on, one of the emails returned in the Lookup Adaptor’s response matches an email in the Customer Profile
If phone Auto-Linking is turned on, one of the phone numbers returned in the Lookup Adaptor’s response matches a phone in the Customer Profile. Either the phone number in Gladly or in the Lookup Adaptor’s response must be set to type=MOBILE for this to auto-link.

Agent Experience #

If Auto-Linking occurs, a Detailed Lookup request will be issued to the Lookup Adaptor. If the Lookup Adaptor returns a well-formatted result, extended infromation will be displayed in the Customer Profile.

Otherwise, the Agent will be able to click on the Link to external customer link under the Customer name. If the Lookup Adaptor returned one or more valid results in the results Array, the results will auto-display in the results table. The table columns are configured in the App settings page on Gladly.

Payloads and Expected Responses #

When an Auto-Linking request is made, Gladly sends most of the Customer Profile information stored in Gladly to your Lookup Adaptor within the query object of the request body. The query object will generally follow this structure, with the following exceptions:

If emails exist in the Customer profile, they are sent as an Array of strings instead of an Array of email objects (e.g.: emails:[“[email protected]”,”[email protected]”])
If phones exist in the Customer profile they will just be sent as an Array of strings instead of an Array of phone objects (e.g.: “phones”:[“+16501234567″,”+16507891234”]). Each phone number will be in E.164 format.
externalCustomerId will not be sent as the profile has not been linked

Gladly expects your Lookup Adaper to respond with a result to Auto-link with, or a list of possible matches based on the query sent.

When an Auto-link occurs, Gladly will store the externalCustomerId and customAttributes values that were returned from your Lookup Adaptor prior to issuing a Detailed Lookup.

Example #

Scenario	Sample search query	Sample expected response
No email in Gladly No match in [CUSTOMER’S NAME]	{“lookupLevel”: “BASIC”, “query”: {“emails”: [], “id”: “KPo4R27eQAyhb8WbKA1qQ”, “name”: “Person”}, “uniqueMatchRequired”: false}	{“results”:[]}
One email in Gladly No match in [CUSTOMER’S NAME]	{“lookupLevel”: “BASIC”, “query”: {“emails”: [“[email protected]”], “id”: “KPo4R27eQAyhb8WbKA1qQ”, “name”: “Person”}, “uniqueMatchRequired”: false}	{“results”:[]}
One email in Gladly One match in [CUSTOMER’S NAME]	{“lookupLevel”: “BASIC”, “query”: {“emails”: [“[email protected]”], “id”: “KPo4R27eQAyhb8WbKA1qQ”, “name”: “Person”}, “uniqueMatchRequired”: false}	{“results”:[{“externalCustomerID”: “12345”, “name”: “Hello World”, “LoyaltyNumber”: “54321”}]}
Multiple emails in Gladly One match in [CUSTOMER’S NAME]	{“lookupLevel”: “BASIC”, “query”: {“emails”: [“[email protected]”, “[email protected]”], “id”: “KPo4R27eQAyhb8WbKA1qQ”, “name”: “Person”}, “uniqueMatchRequired”: false}	{“results”:[{“externalCustomerID”: “12345”, “name”: “Hello World”, “customAttributes”: {“LoyaltyNumber”: “54321”}]}
Multiple emails in Gladly No match in [CUSTOMER’S NAME]	{“lookupLevel”: “BASIC”, “query”: {“emails”: [“[email protected]”, “[email protected]”], “id”: “KPo4R27eQAyhb8WbKA1qQ”, “name”: “Person 1”}, “uniqueMatchRequired”: false}	{“results”:[]}
Multiple emails in Gladly Multiple matches in [CUSTOMER’S NAME]	{“lookupLevel”: “BASIC”, “query”: {“emails”: [“[email protected]”, “[email protected]”], “id”: “KPo4R27eQAyhb8WbKA1qQ”, “name”: “Person 1”}, “uniqueMatchRequired”: false}	{“results”:[{“externalCustomerID”: “54321”, “name”: “Hi World”, “customAttributes”: {LoyaltyNumber”: “101010”}}]}

Basic Search #

Trigger Criteria #

This trigger criteria happens when an Agent overrides the search query on a Customer Profile in Gladly using the search UI by navigating to the “Link to external Customer” link underneath the Customer name.

Agent Experience #

The Agent can type in an email address to find a matching Customer Profile.

You can configure the exact search fields (called Search Query Attributes) and their search field identifiers (called Search Result Attributes) in the App settings page on Gladly. If Gladly identifies multiple matches in the System of Record, it will present Suggestions on the Customer Profile.

Payloads and Expected Responses #

When a Basic Search request is made, Gladly will only send the Agent’s search to your Lookup Adaptor within the query object of the lookup request vs. the entire Customer Profile.

Gladly expects your Lookup Adaptor to respond back with a list of possible matches based on the query sent.

The query object in the request body will look like this:

Text

{
  "id": "customer-id---",
  "email": "[email protected]",
  "phone": "+1234567890",
  "firstName": "first name"
}

id is the Gladly Customer ID
All other keys are search fields identifiers you have configured in the App settings page within the Search Query Attributes panel

If your Lookup Adaptor responds back with well-formatted results, the results will be displayed in a table for the Agent to select from, like this:

A note on the table display:

If you have configured email as a table column, Gladly will retrieve this from the first email object in your “emails” Array for each Customer Profile object sent back in the result Array.
If you have configured phones as a table column, Gladly will retrieve this from the first phone object in your phones Array for each Customer Profile object sent back in the results Array.
If you have configured name as a table column, Gladly will retrieve this from the name field for each Customer Profile object sent back in the results Array.
If you have configured externalCustomerId as a table column, Gladly retrieves this from the externalCustomerId field for each Customer Profile object sent back in the results Array.
If you have configured address as a table column, Gladly will retrieve this from the address field for each Customer Profile object sent back in the results Array.
If you have configured other attributes as a table column (e.g.: loyaltyPoints), Gladly will retrieve this value from the matching key within the customAttribues object for each Customer Profile object sent back in the results Array.
Gladly does not display any information about transactions in a Basic search.

When an Agent chooses a Profile to link with, Gladly will store the externalCustomerId and customAttributes values that were returned from your Lookup Adaptor prior to issuing a detailed lookup.

Example #

Scenario	Sample search query	Sample expected response
No match in [CUSTOMER’S NAME]	{“lookupLevel”: “BASIC”, “query”: { “email”: “[email protected]”, “id”: “KPo4R27eQAyhb8WbKA1qQ”, “name”: “Person”}, “uniqueMatchRequired”: false}	{“results”:[]}
Match in [CUSTOMER’S NAME]	{“lookupLevel”: “BASIC”, “query”: { “email”: “[email protected]”, “id”: “KPo4R27eQAyhb8WbKA1qQ”, “name”: “Person”}, “uniqueMatchRequired”: false}	{“results”: [{“externalCustomerID”: “12345”, “name”: “Hello World”, “customAttributes”: {LoyaltyNumber”: “54321”, “zipCode”: “01234”, “vipStatus”: “GOLD”}}]}

Detailed Lookup #

Trigger Criteria #

This trigger criteria happens when a Gladly Customer Profile is linked to a Profile in your Lookup Adaptor, a new Contact comes in on a linked Profile, an Agent makes an alteration to a linked Customer Profile, or an Agent loads the Customer Profile on Gladly.

Agent Experience #

The Agent can see extended data refreshing on the Customer Profile, as well as any Actions you’ve returned in your Lookup Adaptor.

The Agent will still see the “Link to external customer” link if the Profile remains unlinked to at least one Lookup Adaptor.

Payloads and Expected Responses #

When a Detailed Lookup request is made, Gladly sends most of the Customer Profile information stored in Gladly to your connector within the query object of the request.

Gladly expects your connector to respond back with the Customer’s extended Profile information.

The query object will generally follow this structure, with the following exceptions:

If emails exist in the Customer profile, they will just be sent as an Array of strings instead of an Array of email objects (e.g.: emails:[[email protected],[email protected]])
If phones exist in the Customer profile they will just be sent as an Array of strings instead of an Array of phone objects (e.g.: phones:[+16501234567,+16507891234]). Each phone number is in E.164 format.
If customAttributes exist in the Customer profile, they will be represented in query at the query. level and not in the customAttributes object

Note that Gladly never sends back the transactions Array in the Detailed Lookup request. Gladly will, however, send back whatever customAttributes are stored in the Profile at the time of request.

Scenario	Sample search query	Sample expected response
Detailed lookup is requested by Gladly for a linked profile	{“lookupLevel”: “DETAILED”, “query”: {“emails”: [“[email protected]”], “id”: “KPo4R27eQAyhb8WbKA1qQ”, “name”: “Person”, “tier”: “vip”, “externalCustomerId”: “12345”}, “uniqueMatchRequired”: true}	{“results”:[{“externalCustomerId”:”12345″, “customAttributes”:{“tier”:”vip”, “lifetimeValue”:”$1,234.50″}, “name”:”Person”, “emails”:[{“original”:”[email protected]”}], “phones”:[{“original”:”+16501234567″, “type”:”MOBILE”}], “transactions”:[{“type”:”GENERIC”, “value1″:”12345”, “value2″:”54321”}]}]}

Note – Displaying Custom Attributes and Transaction Attributes

Gladly will store the information you send back in customAttributes and transactions when doing a Detailed Lookup.

To allow your attribute to display, you must engage with Gladly Support to help display them. For large batches of > 15 attribute, a Gladly Professional Services resource is typically required to do this.

Please provide the keys you are using and desired display label and placement to make configuration as efficient as possible.

Testing the Lookup Adaptor #

Setup #

You can follow these steps to setup a Lookup Adaptor.

Testing Auto-Linking #

Go to the Gladly homepage.
Click the + icon on the bottom of the screen.
Enter an email address in the email field you expect to Auto-Link. If you set up Auto-Linking for phone instead, enter a phone number in the phone field.

Gladly will make an Auto-Linking request to your Lookup Adaptor. If successful, you should see a subsequent Detailed Lookup request, and extended data get populated in the Customer Profile.

Testing Basic Search #

Click Link to external customer underneath the Customer name.
Enter your search query (e.g.: email).

Gladly makes a Basic Search request to your Lookup Adaptor. If the Lookup Adaptor returns valid results, you will see a table of results next to the search panel.

Testing Detailed Lookup #

From the results panel, select a Profile.
Click on Link.

Gladly will make a Detailed Lookup request to your Lookup Adaptor. If successful, you should see extended data get populated in the Customer Profile.

Was this article helpful?

Still stuck? How can we help?

Updated on January 8, 2024

0 0 votes

Article Rating

0 Comments

Inline Feedbacks

View all comments