Architecture

From a high-level, the Lookup Adaptor functions like this:

Auto-Linking, Basic Search and Detailed Lookup requests

Each of these requests is sent as a POST request over HTTPS to the Lookup Adaptor(s) you configured, with a JSON body of a specific format.
When a Lookup Adaptor receives these POST requests, it must parse and process them (e.g.: search your OMS for orders associated with this Customer).
The Lookup Adaptor must then respond back to Gladly with a JSON body of a specific format so Gladly can present that information to Agents and use it for routing purposes.
Gladly stores information returned by your Lookup Adaptor under certain scenarios (e.g., a Detailed Lookup's valid response).

Watch Out - Implementing Actions

Free shippingActions build on top of a Detailed Lookup, so if you'd like to build Actions, you'll first need to build a Lookup Adaptor capable of processing and responding to Auto-Linking, Basic Search, and Detailed Lookup requests. on all orders

Actions

Actions may be returned as part of a response to a Detailed Lookup request.
Actions on the Profile level display as part of the Plus Menu button on the bottom of the Customer Profile screen. Actions on the transaction level will display as buttons underneath a transaction.
When an Agent clicks these buttons, Gladly issues a GET request to your Lookup Adaptor asking it to provide information on what form fields Gladly should display for the Agent to fill in before performing this Action.
When the Agent fills in the form fields and submits the Action, Gladly will issue a POST request to your Lookup Adaptor with information on their form entries. Your Lookup Adaptor must then process this Action and then respond back to Gladly with a status.
Upon completion of an Action, Gladly will then issue another Detailed Lookup request.

Tip: Transaction-level Actions
Actions at the transaction-level are only available for ORDER type transactions.

Gladly Requests Made

IP Addresses

Gladly requests will be made from these set of IP addresses.

Request Headers and Authentication

Every request that Gladly makes to your Lookup Adaptor will come with a set of headers, some of which you can configure.

Headers may include the following:

Header Name	Value	Is Always Sent?
content-type	application/json	yes
accept	application/json	yes
gladly-time	timestamp of request. format is YYYYMMDDTHHMMSSZ	yes
gladly-correlation-id	A string indicating the Gladly request ID	yes
user-agent	Go-http-client/1.1	yes
content-length	The POST body content length	yes, if a POST request is made
gladly-authorization	Gladly-signed authorization string. More information on how requests are signed can be found here.	yes
authorization	OPTIONAL Basic auth header that can be set when configuring Lookup Adaptor in Gladly	no - can be configured in app settings
www-authenticate	OPTIONAL Basic Auth realm that can be set when configuration Lookup Adaptor in Gladly	no - can be configured in app settings
CUSTOM_HEADER	OPTIONAL custom headers whose names and values can be set when configuring the Lookup Adaptor in Gladly	no - can be configured in app settings

Note: Authentication
Gladly currently supports sending Basic Auth headers, custom static headers, and the gladly-authorization signed string in requests.

Requests Sent

Tip: Where requests are made
All Auto-Linking, Basic Search and Detailed Lookup requests are made to the URL you configured in the App page on Gladly. The Action Button Clicked and Action Form Submitted URLs can be lightly customized, which we will delve into in the Actions tutorial.

Event Name	HTTP Method	Purpose	When	Agent Experience	Developer Experience	Code Samples
Auto-Linking	POST	Automaticaly link a Profile in Gladly with another Profile in your system without Agent intervention	Lookup Adaptor will receive a POST request from Gladly. If Lookup Adaptor responds with the correctly formatted response, Gladly will automatically link the Profile and then issue a Detailed Lookup request.	If successful, the Gladly customer profile will display detailed information returned from your system.	Lookup Adaptor will receive a POST request from Gladly. If Lookup Adaptor responds with correctly formatted response, Gladly will automatically link the Profile and then issue a Detailed Lookup request.	Sample
Basic Search	POST	If auto-linking is not successful (or is turned off), an Agent can use Basic Search to search your system and manually choose a customer record to link to a Gladly Customr Profile	Triggered when Agent manuallly searches for another Profile in your system to link to within Gladly	Agent populates search fields and clicks "Search." If successful, results display for Agent to link.	Lookup Adaptor will receive a POST request for a Basic Search. If Lookup Adaptor responds with correctly formatted responses, Gladly will display a set of results to Agent to select from. If Agent selects a profile to link to, Gladly will issue a Detailed Lookup request	Sample
Detailed Lookup	POST	Show extended information about a linked Customer Profile on Gladly	Agent views a linked Profile for the first time after logging into Gladly or after refreshing their browser Triggered when Profile is linked Triggered after an Action is performed Triggered when an Agent makes an edit on a linked Customer Profile Triggered when a non-phone Contact comes into a linked Profile or an Agent views the Profile after accepting call Triggered when Agent manually clicks on Refresh Data button on linked Profile	Agent sees extended information/actions	Lookup Adaptor will receive a POST request for a Detailed Lookup. If Lookup Adaptor responds with correctly formatted response, Gladly will display extended information for Agents	Sample
Action Button Clicked	GET	Display form that Agent can enter custom values into to perform an Action on the Profile within Gladly This is only available after the Profile has been linked! Actions at the transaction level are only available for ORDER-type transactions	Triggered when an Agent clicks on an Action button in Gladly	Form displays for Agent to fill in and submit	Lookup Adaptor will receive a GET request asking for form settings to display. If response is correctly formatted, form will display for Agent.	Sample
Action Form Submitted	POST	Perform an Action on Gladly on behalf of Customer (e.g.: cancel an order; award loyalty points) This is only available after Profile has been linked! Actions at the transaction level are only available for ORDER-type transactions	Triggered when an Agent submits Action form on Gladly	Action status / results shown to Agent in Gladly	Lookup Adaptor will receive a POST request with values Agent submitted in the form generated by "Action Button Clicked" event to process. Lookup Adaptor needs to return back status, after which a Detailed Lookup request will be issued.