• 22 Dec 2022
  • 5 Minutes To Read
  • PDF


  • PDF

The Gladly Lookup Adaptor is a piece of middleware you build, host, and maintain that displays additional information about a Customer directly in Gladly from your external sources (e.g., BigQuery).

The goal of the Gladly Lookup Adaptor is to allow Agents to view extended information and perform actions on a Customer profile in external systems directly within Gladly.

This introduction and the following articles provide detailed guidelines for rolling it all into one.

Before You Start

To guide your process, we suggest you start with our Developer Guide.

Tip - Out of the Box Lookup Adaptors

Before you build your own Lookup Adaptor, take a look at Gladly's suite of Customer Profile integrations here! We may have one you can already utilize without needing to code.

Key Concepts

As with all things Gladly, Customers are the central pillar. Below is some key terminology of our wrap-around Customer care.

Customer System of Record

Your internal database or application with Customer information.

Customer Profile

A Customer Profile on Gladly may contain their name, email(s), phone(s), and address, which may be extended with Custom Attributes from your system of record via a Lookup Adaptor.

Custom Attributes

Attributes about your Customers from your System of Record (e.g., birthday, lifetime value, loyalty number, shoe size) sent to Gladly via your Lookup Adaptor. They can be included on your Customer Profile but also used in other parts of Gladly's products like People Match, Rules, etc.

Note - Custom attributes may not be available when Rules execute
Rules are executed in parallel with a custom attribute lookup. This means a Rule may execute but we cannot guarantee the Rule will have the latest custom attribute value in the Rule. In many cases, Rules will run and complete before a lookup completes. This is due to a lookup making a call to an external system that cannot provide any latency guarantee in Gladly, so Gladly prioritizes inbound Contact routing instead of lookup data.

Note: Gladly will need to assist you with displaying each attribute your Lookup Adaptor sends to Gladly that you'd like to display on the Customer Profile.


An array of objects consisting of a group of Gladly-defined Custom Attributes displayed in a pre-set cards that can help showcase variable information about the Customer, like orders and flights. You may choose between GENERIC, ORDER, FLIGHT, SUBSCRIPTION, and STAY cards. You can implement multiple types of transaction cards.


Updates an Agent can perform on a Customer Profile or ORDER type Transaction in your System of Record through Gladly (e.g., offer a discount, refund an order).

External Customer ID

Unique identifier in your Customer System of Record, stored in Gladly profile as a foreign key.

What Is Lookup?

Lookup allows Agents on Gladly to link a Gladly Customer Profile to an external Profile in another system of record. Upon linking, Gladly can showcase extended information & actions on the Customer Profile that the Lookup Adaptor sends to Gladly.

Once linked, Gladly will display more detailed information about the Customer. For example, Gladly can display the Customer’s most recent orders.

By implementing a Lookup Adaptor, you can send a variety of data to Gladly to be viewed in the Customer Profile, such as Customer loyalty points, total lifetime value, historical orders, and more. You can even integrate Actions directly within Gladly, like the following:

Order card overview

Building A Lookup Adaptor

To accomplish the above, you must build a Lookup Adaptor between your system of record to Gladly. You may build as many Lookup Adaptors as you'd like! For example, you might want to build a Lookup Adatper for your OMS and another one for your loyalty points provider.

Tip - Linking Gladly Customer Profiles

A Customer Profile in Gladly can be linked to multiple Lookup Adaptors. However, the Profile may only be linked to one entry within each Lookup Adaptor.

How Does It Help Agents?

A Lookup Adaptor helps Agents by bringing data out of a separate window, tab, or application and putting that information directly in the Gladly Customer Profile. If Gladly identifies multiple matches in the System of Record, it will present Suggestions on the Customer Profile.

Should We Build a Lookup Adaptor?

Gladly has a number of out-of-the-box Lookup Adaptors you can connect without any extra coding! For example, here are our docs on BigCommerce and Magento. We recommend you read through those before you decide to invest in Lookup.

How It Works


An unlinked Customer Profile will typically initiate an Auto-Linking request to your Lookup Adaptor upon a new Contact, Profile edit, or Profile load (exception: when the Profile has been previously unlinked). If you've set up auto-linking, and your Lookup Adaptor responds back with a correctly formatted response, Gladly will then initiate a Detailed Lookup request to your Lookup Adaptor to retrieve more detailed information on the Customer Profile.

If auto-linking is unsuccessful or not configured, an Agent can still click on the "Link to external Customer" button underneath the Customer name to manually search for a record to link to within your Lookup Adaptor(s).


Search fields (called Search Query Attributes) you configured in your App settings page are displayed for the Agent to manually fill in. When the Agent clicks on Search, a Basic Search request will be issued to your Lookup Adaptor. Your Lookup Adaptor should return back a list of potential matching results. If your Lookup Adaptor responds back with a correctly formatted response, Gladly will display these results (called Search Results Attributes) in a table whose format is configured in the App settings page on Gladly.

The Agent can then choose a profile to link with. Once they click on Link, Gladly will issue a Detailed Lookup request to your Lookup Adaptor to retrieve more detailed information on the Customer Profile.

Once linked, a Detailed Lookup request will be issued when a new Contact comes in, when an Agent navigates to the Customer Profile, or when an Agent refreshes the browser while viewing a Customer Profile.

You can use the Detailed lookup to extend the Gladly Customer Profile object in two ways:

  • Profile-level custom attributes (e.g., lifetime value)
  • A list of transactions (e.g., historical orders) associated with this Profile

We'll delve into the Customer Profile object structure and how to extend it in subsequent sections.

When your Lookup Adaptor sends back a Detailed Lookup response, it can also specify a list of Actions that the Agent is allowed to take on this Profile. These Actions can be specified at the Profile level (e.g., add loyalty points) or the transaction level (e.g., cancel an order) for ORDER type transactions. We'll also delve into Actions and how to build them in subsequent sections.

Tip - Actions are only available for ORDER type transactions

Please note Actions are only available for ORDER type transactions!

Initial Setup

To activate your Lookup Adaptor, please follow these directions.

Subsequent tutorials will delve much deeper into the Lookup Adaptor architecture, request, and response formats.

Tip - Professional Services Fee

If you are building a Lookup Adaptor and would like to show extended custom attributes tied to the Customer Profile, you will need to set up a paid Professional Services engagement to provide you with that assistance. Please contact your Gladly CSM or the Gladly Support team to kickstart this engagement.

Was this article helpful?

What's Next