The 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 Lookup Adaptor allows 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 everything into one.
Before you start
Before you build your Lookup Adaptor, look at Gladly's suite of app integrations. We may have an app you can utilize without needing a custom Lookup Adaptor.
To guide your process, we suggest you start with our Developer Guide on building a Lookup Adaptor.
Key Concepts
As with all things Gladly, Customers are the central pillar. Below are 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. A Lookup Adaptor allows you to extend the profile with custom attributes from your system of record.
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 in your Customer Profile and used in other parts of Gladly's products like People Match, Rules, etc.
Note - Custom attributes may not be available when Rules execute
The Lookup before Rules routing behavior is activated by default, allowing the Lookup Adaptor to retrieve custom attributes (e.g., lifetime value spend) from an external system before Rules run. This allows you to utilize custom attributes in Rules to route Customers to certain Inboxes or Agents. You can deactivate Lookup before Routing. Rules are executed in parallel with custom attribute lookup through the Lookup Adaptor. However, due to lookup latencies outside Gladly's control, there is no guarantee that the Rule will have the latest custom attribute value before the Customer is routed.
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 pre-set cards that can help showcase variable information about the Customer, like orders and flights. You may choose 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 Gladly various data 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, such as returns and refunds.
Building a Lookup Adaptor
To accomplish the above, you must build a Lookup Adaptor between your system of record and Gladly. You may build as many Lookup Adaptors as you'd like! For example, you might want to build one for your OMS and another for your loyalty points provider.
Tip – A Customer Profile in Gladly can be linked to multiple Lookup Adaptors. However, the Customer 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 several out-of-the-box apps built using Lookup Adaptors, which you can connect to without any extra coding! For example, here are our documents 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 with a correctly formatted response, Gladly will initiate a Detailed Lookup request to retrieve more detailed information on the Customer Profile.
If auto-linking is unsuccessful or not configured, an Agent can still click 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 fill in manually. When the Agent clicks on Search, a Basic Search request will be issued to your Lookup Adaptor. Your Lookup Adaptor should return a list of potential matching results. If your Lookup Adaptor responds 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
In subsequent sections, we'll delve into the Customer Profile object structure and how to extend it.
When your Lookup Adaptor sends back a Detailed Lookup response, it can also specify a list of Actions the Agent can 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. In subsequent sections, we'll also delve into Actions and how to build them.
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 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.
.svg?sv=2022-11-02&spr=https&st=2025-05-13T02%3A00%3A02Z&se=2025-05-13T02%3A16%3A02Z&sr=c&sp=r&sig=%2FhmbKVGty1vFFtzvvdI7Os55GOcTBpUEw4xnykLknjU%3D)
on the top-left corner, then click Contact Gladly Support. Gladly Support's primary operating hours are Monday through Friday, 6 AM to 6 PM Pacific Time, but you can submit a request anytime.