Download OpenAPI specification:Download
At Gladly, we believe that customer service is best when it's a conversation. That means more than just helping customers with one-off questions or issues, it's about making them feel known, valued, and respected for the individuals they are.
The Gladly API was built to help facilitate those relationships, providing agents with the rich customer context they need to deliver seamless experiences that make customers feel like they're more than just a number in a sea of others.
You can integrate easily with Gladly by calling Gladly's REST API and implementing the Lookup API to provide data from your own services.
Some examples of what you do through Gladly APIs include managing customer profile data, interacting with a customer's timeline, providing the latest information about a customer's orders, and more.
Clients can access the REST API via HTTPS at your organization's Gladly domain (e.g. https://{organization}.gladly.com
).
Resources follow REST semantics and utilize industry-standard HTTP verbs, response codes, and authentication schemes. In addition, all responses and payloads are in JSON with consistent error codes and formats.
The Gladly Lookup API allows your organization to provide data services to power the agent's experience with a complete view of your customers' information, transactions, and activity. You can provide a web service that implements the Lookup API and Gladly will call it when that data is needed.
Like the REST API, the Lookup API is specified using REST semantics, and exchanges JSON requests and responses authenticated and signed with secure keys.
Gladly will perform lookups when certain activities occur within Gladly, such as when a customer's profile is loaded.
Test the myriad possibilities of the Gladly API in a safe, secure space. We'll enable the Gladly API in a separate sandbox environment, so you can experiment freely without impacting your production environment (or vice versa).
Your sandbox environment is accessible at https://{organization}.gladly.qa
, where organization
is your company name. For specific API endpoints, see documentation below.
Think of this section as getting the keys to unlocking your access to the Gladly APIs. First, you'll need to set up an account with the necessary API permissions. With these permissions, you can then go on to create the API Token(s) you need to access Gladly's API resources.
Gladly Administrators can set API permissions on an agent-by-agent basis. We'll discuss how this maps to API access in the section on authentication below.
To allow a user to create API tokens and access the API:
We recommend creating a dedicated user to make API calls, whose account won't be used for agent and organization management. This will help you with any future audits of API activity vs. agent activity.
You must create an API token to access Gladly API resources (see above Permissions). If your profile already has access to the API User permission, you'll see a new menu item titled API Tokens:
Click on API Tokens, then the Add Token button on the upper right-hand corner of the page:
A token will be generated and named, by default, New Token (though depending on whether you have existing tokens, it may be named New Token 2, or New Token 3 etc.). You can rename the token to something more easily referenceable by clicking the name to edit it.
This token will be associated with your agent profile, which we will refer to as the API User in this document.
For security purposes, you'll only see a new token once before you navigate away from the page.
Should you lose this token, or wish to rotate your application keys, you can do the following:
Gladly API uses token-based Basic Authentication. API tokens are associated with designated Gladly users. To create and use an API token, your user must have the API User permission.
user name | password |
---|---|
agent email | API token |
The credentials must be passed via an Authorization
HTTP header. All requests must be made over HTTPS.
curl -u user@organization.com:$GLADLY_API_TOKEN \
https://organization.gladly.com/api/v1/organization
Security scheme type: | HTTP |
---|---|
HTTP Authorization Scheme | basic |
An Agent represents the user profile of a person who helps customers in Gladly. The API allows you to lookup agents who participated in conversations with customers.
Get an agent profile by their unique id.
agentId | string Example: "WmeA3Y51Q5ayCAaZ1AotIA" id of the agent |
Agent
A Public Answer in Gladly represents a consumer-facing Answer.
Answers API allows you to search and retrieve Public Answers (created directly in the Gladly UI), which you can display in the Gladly Sidekick web widget, use to build your website's help center/FAQ page, or publish on any page on your website.
This API can be used without an API token as it only provides access to public content. You may also work with your Customer Success Manager to enable CORS access so that the API can be used directly from client-side javascript.
Returns a list of answers that match the provided query string.
orgId | string Example: "ihKsWxiZCDVtXg1iwVmT9Q" id of your organization You can look up the ID using the Get organization API. |
q | string Example: "reset password" search term |
lng | string Example: "en-us" language code |
found answers
Returns the answer with the provided id.
orgId | string Example: "ihKsWxiZCDVtXg1iwVmT9Q" id of your organization You can look up the ID using the Get organization API. |
answerId | string Example: "1grfSzATQLa334VDLCWc4A" id of the answer |
answer
Communications API enables you to programatically send messages to your customers via Gladly communications channels such as SMS.
To send an SMS message to a customer specified by a mobile phone number.
SMS to send
customer required | object (customer with mobile number) |
from required | string (mobile number) |
body required | string (SMS message) |
the customer and conversation item ID
Invalid field(s) in request body
A Conversation in Gladly contains the timeline of activity for a customer including communications to and from your organization along with other internal and external activity. Conversations API enables you to interact with the customer conversation timeline.
A number of different types of items may appear in a customer's timeline. Each is described below.
Item Type | Create | Read | Delete |
---|---|---|---|
Chat Message | No | Yes | No |
Customer Activity | Yes | Yes | Yes |
No | Yes | No | |
Facebook Messenger Message | No | Yes | No |
Phone Call | No | Yes | No |
SMS Message | No* | Yes | No |
Topic Change | No | Yes | No |
* Messages can be sent through the Communications API.
Content of messages sent between Gladly and customers through Gladly Chat.
Information about activities customers participated in, for example, emails they received, issues in another system, or customer statisfaction surveys they answered.
These can be created through the API to bring in information from other systems.
Adding an activity to the customer timeline is not customer facing.
For example, posting an email activity to the timeline does not send an email to the customer.
Content of emails sent between Gladly and customers.
Content of messages sent between Gladly and customers on Facebook Messenger.
Information about phone calls that took place between Gladly and customers.
Content of SMS text messages sent between Gladly and customers. To send SMS messages to customers through the API, see Send SMS.
Interacting with tasks through the conversations API is deprecated. Use Tasks API instead.
Record of an agent adding or removing a topic from a conversation in Gladly.
To add items to the timeline for a customer specified by identifying information. If the customer doesn't exist, a new customer profile is created.
Conversation Item to create
id | string <= 50 characters Unique conversation item id. Must be URL safe and under 50 characters. An id will be automatically generated if one is not included. |
customer required | object (Customer Specification) Specifies the customer an item belongs to. You must provide exactly one of the values. |
content required | Customer Activity (object) or Task (deprecated) (object) (Conversation Item Content To Create) |
The created item
Invalid field(s) in request body
Specified id is in use
Returns the conversation item with the provided id.
itemId required | string Example: "pOVVdzweSumI4bFxjlT8LA" id of the conversation item |
conversation item
An item exists but is not supported by the API
An item with the given id could not be found
To add items to a customer's timeline.
customerId required | string Id of the customer associated with this item. You can look up the id using the Find customers API. |
Conversation Item to create
id | string <= 50 characters Unique conversation item id. Must be URL safe and under 50 characters. An id will be automatically generated if one is not included. |
content required | Customer Activity (object) or Task (deprecated) (object) (Conversation Item Content To Create) |
The created item
This customer id no longer exists, but has been moved because it has been merged with another customer
Invalid field(s) in request body
Customer with customerId does not exist
Specified id is in use
To delete an item.
customerId required | string Id of the customer associated with this item. You can look up the id using the Find customers API. |
itemId required | string Id of the item to be deleted. |
The item was deleted
An item with the given id, for the given customer id, could not be found
Get the list of items in the timeline of a conversation. The conversation represents a period of related interactions between a customer and your organization. The list is not paginated. The items are returned in ascending order by timestamp.
conversationId required | string Example: "9BcE2O0DQ2ynGHRmk9FeoA" Id of the conversation to get the timeline for |
The items on the conversation timeline
A conversation with the given id does not exist
A Customer in Gladly represents information about a customer of your organization including their profile, contact information, notes, and transactions.
Customers API allows you to add, update, and get customer profile data.
Id, mobile phone number, and email address must be unique across customer records. 409 errors returned will include details on any conflicts, such as a field being taken.
Additionally, errors may be returned due to customer profiles being merged. If a customer has been merged into another, requests to get a customer by id will return 301 errors specifying the new id of the customer, and requests to update a customer by id will return 404 errors.
Create a new customer with the supplied profile data.
Customer record to add.
name | string Customer's name |
address | string Customer's street address |
emails | Array of objects (email addresses) Customer's email addresses |
phones | Array of objects (phone numbers) Customer's phone numbers |
externalCustomerId | string Customer ID in your customer master |
customAttributes | object Organization-specific attributes from Customer Master. The shape of customAttributes is defined by the Customer Profile Definition. |
id | string Unique customer id. Must be URL safe and under 50 characters. An id will be automatically generated if one is not included |
customer created
error creating customer
Specified id is in use or a uniqueness constraint failed
Find customers by searching by choosing one of the following identifiers as query parameters:
/api/v1/customer-profiles?phoneNumber=%2B14151234567
string Example: "customer@email.net" customer email address to search on. | |
externalCustomerId | string Example: "a21c1636-c622-48b7-bf6a-d9032645aa55" customer unique id in your customer master. |
phoneNumber | string Example: "+16505551987" Phone number in E.164 format. The value should be URL escaped where |
found customers
error finding customers
Get a customer by unique id. If a customer has been merged into another, an error will be returned specifying the new id of the customer.
customerId | string Example: "OOrlNMXeS72gs_WEX2TtMg" id of the customer |
fetched customer
customer id no longer exists and has been changed due to a merge with another customer
customer not found
Update a customer by unique id with the supplied JSON patch.
You may supply only the properties which you want to update or insert into the profile.
When updating arrays, such as phones
and emails
you must provide the entire list of values
since it is not possible to add or delete a single value.
If a customer has been merged into another, an error will be returned specifying the new id of the customer.
customerId | string Example: "OOrlNMXeS72gs_WEX2TtMg" id of the customer |
JSON patch of customer profiles properties to insert or update.
name | string Customer's name |
address | string Customer's street address |
emails | Array of objects (email addresses) Customer's email addresses |
phones | Array of objects (phone numbers) Customer's phone numbers |
externalCustomerId | string Customer ID in your customer master |
customAttributes | object Organization-specific attributes from Customer Master. The shape of customAttributes is defined by the Customer Profile Definition. |
updated customer
error updating customer
customer not found
A Custom Report is a periodically run report built to your organization's specifications.
Custom Reporting API enables you to list and download custom reports compiled for your organization.
Retrieve a list of custom reports at the root level or folder path.
After retrieving a listing, you can continue to traverse each of the returned dirs
.
All paths must include the trailing slash.
dirPath | string Example: "Utilization%20Report/20190206223006/" Folder path of reports to list. |
report list
report not found