--- title: "Auto-Linking, Basic Search and Detailed Lookup" slug: "auto-linking-basic-search-and-detailed-lookup" description: "Learn about auto-linking, basic search, and detailed lookup requests in Gladly's Customer Lookup. Find out how to structure your requests and handle the response." updated: 2026-01-13T19:48:00Z published: 2026-01-13T19:48:00Z canonical: "help.gladly.com/auto-linking-basic-search-and-detailed-lookup" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.gladly.com/llms.txt > Use this file to discover all available pages before exploring further. # Auto-Linking, Basic Search and Detailed Lookup **Unlinked Customer Profile** ![Interface element prompting to add a customer name and link to external customer.](https://cdn.us.document360.io/7047b671-c4f2-4df0-bb0a-b9b511fd2452/Images/Documentation/multi-source-link-to-external-system-1.webp?sv=2026-02-06&spr=https&st=2026-11-09T19%3A40%3A38Z&se=2026-11-09T20%3A40%3A38Z&sr=c&sp=r&sig=ly7oZSEqNE0brPRxuaHbYngatIo%2FNwK4qcun3vVhEwo%3D) **Linked Customer Profile** ![Customer details with options to unlink or merge customers displayed on the interface.](https://cdn.us.document360.io/7047b671-c4f2-4df0-bb0a-b9b511fd2452/Images/Documentation/unlink-customer-from-source.webp?sv=2026-02-06&spr=https&st=2026-11-09T19%3A40%3A38Z&se=2026-11-09T20%3A40%3A38Z&sr=c&sp=r&sig=ly7oZSEqNE0brPRxuaHbYngatIo%2FNwK4qcun3vVhEwo%3D) ## Request Structure The request structure Gladly sends to your Lookup Adaptor depends on the request type sent. In general, requests follow this structure: ```plaintext {    "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: ```plaintext {  "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](https://developer.gladly.com/rest/#operation/getCustomer) 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](https://developer.gladly.com/rest/#operation/createCustomer). - 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](https://help.gladly.com/developer-tutorials/docs/transactions). 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: ![User profile displaying name and custom attributes for identification purposes.](https://cdn.us.document360.io/7047b671-c4f2-4df0-bb0a-b9b511fd2452/Images/Documentation/profile_bottom.webp?sv=2026-02-06&spr=https&st=2026-11-09T19%3A40%3A38Z&se=2026-11-09T20%3A40%3A38Z&sr=c&sp=r&sig=ly7oZSEqNE0brPRxuaHbYngatIo%2FNwK4qcun3vVhEwo%3D) ![Contact information including address, emails, phones, and transaction details displayed clearly.](https://cdn.us.document360.io/7047b671-c4f2-4df0-bb0a-b9b511fd2452/Images/Documentation/profile_mapping_bottom.webp?sv=2026-02-06&spr=https&st=2026-11-09T19%3A40%3A38Z&se=2026-11-09T20%3A40%3A38Z&sr=c&sp=r&sig=ly7oZSEqNE0brPRxuaHbYngatIo%2FNwK4qcun3vVhEwo%3D) > [!CAUTION] > 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. > [!WARNING] > Note: Deeplinks > > 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](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. > [!NOTE] > 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. ### 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 information will be displayed in the Customer Profile. Otherwise, the Agent can click on the **Link to external customer** link under the Customer name. If the Lookup Adaptor returns 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](https://developer.gladly.com/rest/#operation/getCustomer) 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](mailto:person@person.com)","[person1@person.com](mailto: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](mailto: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](mailto: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](mailto:person1@person.com)", "[person2@person.com](mailto: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](mailto:person3@person.com)", "[person4@person.com](mailto: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](mailto:person1@person.com)", "[person5@person.com](mailto:person5@person.com)"], "id": "KPo4R27eQAyhb8WbKA1qQ", "name": "Person 1"}, "uniqueMatchRequired": false} | {"results":[{"externalCustomerID": "54321", "name": "Hi World", "customAttributes": {LoyaltyNumber": "101010"}}]} | ## Basic Search ### Trigger Criteria This trigger criterion 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: ```plaintext {  "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 query attributes section showing email attribute and label input fields.](https://cdn.us.document360.io/7047b671-c4f2-4df0-bb0a-b9b511fd2452/Images/Documentation/search-fields.webp?sv=2026-02-06&spr=https&st=2026-11-09T19%3A40%3A38Z&se=2026-11-09T20%3A40%3A38Z&sr=c&sp=r&sig=ly7oZSEqNE0brPRxuaHbYngatIo%2FNwK4qcun3vVhEwo%3D) ![Table displaying user information including name, email, and loyalty points.](https://cdn.us.document360.io/7047b671-c4f2-4df0-bb0a-b9b511fd2452/Images/Documentation/search-table-1024x156.webp?sv=2026-02-06&spr=https&st=2026-11-09T19%3A40%3A38Z&se=2026-11-09T20%3A40%3A38Z&sr=c&sp=r&sig=ly7oZSEqNE0brPRxuaHbYngatIo%2FNwK4qcun3vVhEwo%3D)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. ![Form displaying customer attributes like name, email, phone, and address fields.](https://cdn.us.document360.io/7047b671-c4f2-4df0-bb0a-b9b511fd2452/Images/Documentation/table-mappings-1024x420.webp?sv=2026-02-06&spr=https&st=2026-11-09T19%3A40%3A38Z&se=2026-11-09T20%3A40%3A38Z&sr=c&sp=r&sig=ly7oZSEqNE0brPRxuaHbYngatIo%2FNwK4qcun3vVhEwo%3D) 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](mailto:person1@person.com)", "id": "KPo4R27eQAyhb8WbKA1qQ", "name": "Person"}, "uniqueMatchRequired": false} | {"results":[]} | | Match in [CUSTOMER'S NAME] | {"lookupLevel": "BASIC", "query": { "email": "[person1@person.com](mailto: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 These 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 alters 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 summary showing fulfilled and refunded items with financial details and chat messages.](https://cdn.us.document360.io/7047b671-c4f2-4df0-bb0a-b9b511fd2452/Images/Documentation/Order-card-overview-1024x640.webp?sv=2026-02-06&spr=https&st=2026-11-09T19%3A40%3A38Z&se=2026-11-09T20%3A40%3A38Z&sr=c&sp=r&sig=ly7oZSEqNE0brPRxuaHbYngatIo%2FNwK4qcun3vVhEwo%3D) 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](https://developer.gladly.com/rest/#operation/getCustomer) 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**](mailto:person@person.com),[**person1@person.com**](mailto: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. | **Scenario** | **Sample search query** | **Sample expected response** | | --- | --- | --- | | Detailed lookup is requested by Gladly for a linked profile | {"lookupLevel": "DETAILED", "query": {"emails": ["[person1@person.com](mailto:person1@person.com)"], "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@example.com](mailto:email@example.com)"}], "phones":[{"original":"+16501234567", "type":"MOBILE"}], "transactions":[{"type":"GENERIC", "value1":"12345", "value2":"54321"}]}]} | > [!WARNING] > 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 attributes to display, you must engage with Gladly Support to help display them. For large batches of > 15 attributes, a Gladly Professional Services resource is typically required to do this. Please provide the keys you are using and the desired display label and placement to make the configuration as efficient as possible. ## Testing the Lookup Adaptor ### Setup You can follow [these](https://help.gladly.com/docs/set-up-and-edit-custom-integration?highlight=custom%20integration) steps to set up 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. ![Contact information section displaying email, phone, and customer ID details.](https://cdn.us.document360.io/7047b671-c4f2-4df0-bb0a-b9b511fd2452/Images/Documentation/auto_linking.webp?sv=2026-02-06&spr=https&st=2026-11-09T19%3A40%3A38Z&se=2026-11-09T20%3A40%3A38Z&sr=c&sp=r&sig=ly7oZSEqNE0brPRxuaHbYngatIo%2FNwK4qcun3vVhEwo%3D) 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). ![Search interface displaying an email input field for Breeze application.](https://cdn.us.document360.io/7047b671-c4f2-4df0-bb0a-b9b511fd2452/Images/Documentation/basic_search.webp?sv=2026-02-06&spr=https&st=2026-11-09T19%3A40%3A38Z&se=2026-11-09T20%3A40%3A38Z&sr=c&sp=r&sig=ly7oZSEqNE0brPRxuaHbYngatIo%2FNwK4qcun3vVhEwo%3D) 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. Users assigned the **Team Manager** or **Administrator** roles can contact [Gladly Support](https://help.gladly.com/product-docs/pages/en/contact-gladly-support-team). Log into Gladly as one of these roles, click![hamburger-menu-icon(1)](https://cdn.us.document360.io/7047b671-c4f2-4df0-bb0a-b9b511fd2452/Images/Documentation/hamburger-menu-icon(1).svg?sv=2026-02-06&spr=https&st=2026-11-09T19%3A40%3A38Z&se=2026-11-09T20%3A40%3A38Z&sr=c&sp=r&sig=ly7oZSEqNE0brPRxuaHbYngatIo%2FNwK4qcun3vVhEwo%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. - Please select the correct business impact (P1 to P4). - Most requests should be sent as a P4.