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.
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: 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.
Transactions #
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.
Actions #
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:

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