Auto-Linking, Basic Search and Detailed Lookup
  • 09 Sep 2022
  • 11 Minutes To Read
  • PDF

Auto-Linking, Basic Search and Detailed Lookup

  • PDF

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.
Picture1.jpg

This Profile is linked.
Picture1.jpg

Request Structure

The request structure Gladly sends to your Lookup Adaptor

depends on the request type sent.

In general, requests follow this structure:

{
    "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:

{
  "results": [
    {
      "externalCustomerId": "12345",
      "customAttributes": {
        "key": "value"
      },
      "transactions": [
        {
          "type": "GENERIC",
          "key": "value"
        }
      ],
      "emails": [
        {
          "original": "person@person.com"
        }
      ],
      "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. Gladly only supports one layout type per organization (i.e.: you can't mix and match ORDER and STAY layouts). 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, 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:

profile_bottom.png
profile_mapping_bottom.png

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 Professional Services team and send them the link format.

Tip - All values must be returned as STRING

All values must be returned in STRING format. For example, externalCustomerId 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. The phone number in the Lookup Adaptor's response must also be set to type=MOBILE.

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:["person@person.com","person1@person.com"])
  • 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": ["person1@person.com"], "id": "KPo4R27eQAyhb8WbKA1qQ", "name": "Person"}, "uniqueMatchRequired": false} {"results":[]}
One email in Gladly

One match in [CUSTOMER'S NAME]
{"lookupLevel": "BASIC", "query": {"emails": ["person1@person.com"], "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": ["person1@person.com", "person2@person.com"], "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": ["person3@person.com", "person4@person.com"], "id": "KPo4R27eQAyhb8WbKA1qQ", "name": "Person 1"}, "uniqueMatchRequired": false} {"results":[]}
Multiple emails in Gladly

Multiple matches in [CUSTOMER'S NAME]
{"lookupLevel": "BASIC", "query": {"emails": ["person1@person.com", "person5@person.com"], "id": "KPo4R27eQAyhb8WbKA1qQ", "name": "Person 1"}, "uniqueMatchRequired": false} {"results":[{"externalCustomerID": "54321", "name": "Hi World", "customAttributes": {LoyaltyNumber": "101010"}}]}

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.
image.png

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:

{
  "id": "customer-id---",
  "email": "email@email.com",
  "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

search-fields.png

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:
search-table.png

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.

table-mappings.png

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": ["person1@person.com"], "id": "KPo4R27eQAyhb8WbKA1qQ", "name": "Person"}, "uniqueMatchRequired": false} {"results":[]}
Match in [CUSTOMER'S NAME] {"lookupLevel": "BASIC", "query": {"email": ["person1@person.com"], "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.

Order card overview

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:[person@person.com,person1@person.com])
  • 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.

Note - Displaying Custom Attributes and Transaction Attributes

Gladly will store the information you send back in customAttributes and transactions when doing a Detailed Lookup. However, you must engage with a Gladly Professional Services resource to display these attributes on the Customer Profile for Agents to view. 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

  1. Go to the Gladly homepage.
  2. Click the + icon on the bottom of the screen.
  3. 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.
    image.png

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

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

image.png

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

  1. From the results panel, select a Profile.
  2. 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?