logo
Documentation Powered by ReDoc

Gladly API (1.0)

Download OpenAPI specification:Download

Introducing the Gladly API

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.

Overview

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.

REST API

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.

Lookup API

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.

Testing

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.

Getting Started

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.

Permissions

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:

  1. Log in to your Gladly instance
  2. Open up the menu on the top left-hand corner of the page
  3. Navigate to Settings > Users
  4. Search and click on the user profile you wish to give access to
  5. You'll see a permission called API User. Select it, while making sure to keep the user's Agent role intact.
  6. Hit Save to give access

Agent profile screen

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.

Creating API Tokens

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:

API Token Menu

Click on API Tokens, then the Add Token button on the upper right-hand corner of the page:

API Token Add

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.

API Token View

For security purposes, you'll only see a new token once before you navigate away from the page.

Replacing/Rotating API Tokens

Should you lose this token, or wish to rotate your application keys, you can do the following:

  1. Generate a new token
  2. Store the new token in a secure location
  3. Delete the old token
  4. Update your applications/scripts with the new token

Authentication

BasicAuth

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

Agents

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 Agent

Get an agent profile by their unique id.

path Parameters
agentId
string
Example: "WmeA3Y51Q5ayCAaZ1AotIA"

id of the agent

Responses

200

Agent

get /api/v1/agents/{agentId}
https://organization.gladly.com//api/v1/agents/{agentId}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "id": "WmeA3Y51Q5ayCAaZ1AotIA",
  • "name": "Amy Agent",
  • "emailAddress": "amy.agent@company.com"
}

Answers

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.

How a user creates a public answer in Gladly

How that answer is searched and displayed on the Sidekick web widget

Search public answers

Returns a list of answers that match the provided query string.

path Parameters
orgId
string
Example: "ihKsWxiZCDVtXg1iwVmT9Q"

id of your organization

You can look up the ID using the Get organization API.

query Parameters
q
string
Example: "reset password"

search term

lng
string
Example: "en-us"

language code

Responses

200

found answers

get /api/v1/orgs/{orgId}/answers/search?q=search+terms
https://organization.gladly.com//api/v1/orgs/{orgId}/answers/search?q=search+terms

Response samples

application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get public answer

Returns the answer with the provided id.

path Parameters
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

Responses

200

answer

get /api/v1/orgs/{orgId}/answers/{answerId}
https://organization.gladly.com//api/v1/orgs/{orgId}/answers/{answerId}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "id": "1grfSzATQLa334VDLCWc4A",
  • "name": "How to reset your password",
  • "bodyHtml": "<div><a href=\"/reset-password\">Click here</a> to reset your password</div>",
  • "language": "en-us"
}

Communications

Communications API enables you to programatically send messages to your customers via Gladly communications channels such as SMS.

Agent View

Agent View

Consumer View

Customer View

Send SMS

To send an SMS message to a customer specified by a mobile phone number.

Request Body schema: application/json

SMS to send

customer
required
object (customer with mobile number)
from
required
string (mobile number)
body
required
string (SMS message)

Responses

200

the customer and conversation item ID

400

Invalid field(s) in request body

post /api/v1/communications/sms
https://organization.gladly.com//api/v1/communications/sms

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "customer":
    {
    },
  • "from": "+14152223316",
  • "body": "hello, this is a sample SMS message!"
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "customerId": "gHufx-U3QqOmhvFuViceTw",
  • "conversationItemId": "pOVVdzweSumI4bFxjlT8LA"
}

Conversations

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.

Conversation Items

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

Chat Message

Content of messages sent between Gladly and customers through Gladly Chat.

Customer Activity

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

Email

Content of emails sent between Gladly and customers.

Facebook Messenger Message

Content of messages sent between Gladly and customers on Facebook Messenger.

Phone Call

Information about phone calls that took place between Gladly and customers.

SMS Message

Content of SMS text messages sent between Gladly and customers. To send SMS messages to customers through the API, see Send SMS.

Task

Interacting with tasks through the conversations API is deprecated. Use Tasks API instead.

Topic Change

Record of an agent adding or removing a topic from a conversation in Gladly.

Create item

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.

Request Body schema: application/json

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)

Responses

200

The created item

400

Invalid field(s) in request body

409

Specified id is in use

post /api/v1/conversation-items
https://organization.gladly.com//api/v1/conversation-items

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "id": "pOVVdzweSumI4bFxjlT8LA",
  • "customer":
    {
    },
  • "content":
    {
    }
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "id": "pOVVdzweSumI4bFxjlT8LA",
  • "customerId": "gHufx-U3QqOmhvFuViceTw",
  • "conversationId": "PmDVUfWfRjKuwb4VgA2zEA",
  • "timestamp": "2019-07-03T04:30:12.07Z",
  • "initiator":
    {
    },
  • "responder":
    {
    },
  • "content":
    {
    }
}

Get item

Returns the conversation item with the provided id.

path Parameters
itemId
required
string
Example: "pOVVdzweSumI4bFxjlT8LA"

id of the conversation item

Responses

200

conversation item

400

An item exists but is not supported by the API

404

An item with the given id could not be found

get /api/v1/conversation-items/{itemId}
https://organization.gladly.com//api/v1/conversation-items/{itemId}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "id": "pOVVdzweSumI4bFxjlT8LA",
  • "customerId": "gHufx-U3QqOmhvFuViceTw",
  • "conversationId": "PmDVUfWfRjKuwb4VgA2zEA",
  • "timestamp": "2019-07-03T04:30:12.07Z",
  • "initiator":
    {
    },
  • "responder":
    {
    },
  • "content":
    {
    }
}

Delete item

To delete an item.

path Parameters
itemId
required
string

Id of the item to be deleted.

Responses

204

The item was deleted

404

An item with the given id could not be found

delete /api/v1/conversation-items/{itemId}
https://organization.gladly.com//api/v1/conversation-items/{itemId}

Create item for customer

To add items to a customer's timeline.

path Parameters
customerId
required
string

Id of the customer associated with this item.

You can look up the id using the Find customers API.

Request Body schema: application/json

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)

Responses

200

The created item

301

This customer id no longer exists, but has been moved because it has been merged with another customer

400

Invalid field(s) in request body

404

Customer with customerId does not exist

409

Specified id is in use

post /api/v1/customers/{customerId}/conversation-items
https://organization.gladly.com//api/v1/customers/{customerId}/conversation-items

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "content":
    {
    }
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "id": "pOVVdzweSumI4bFxjlT8LA",
  • "customerId": "gHufx-U3QqOmhvFuViceTw",
  • "conversationId": "PmDVUfWfRjKuwb4VgA2zEA",
  • "timestamp": "2019-07-03T04:30:12.07Z",
  • "initiator":
    {
    },
  • "responder":
    {
    },
  • "content":
    {
    }
}

Delete item for customer

To delete an item.

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

Responses

204

The item was deleted

404

An item with the given id, for the given customer id, could not be found

delete /api/v1/customers/{customerId}/conversation-items/{itemId}
https://organization.gladly.com//api/v1/customers/{customerId}/conversation-items/{itemId}

List items in conversation

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.

path Parameters
conversationId
required
string
Example: "9BcE2O0DQ2ynGHRmk9FeoA"

Id of the conversation to get the timeline for

Responses

200

The items on the conversation timeline

404

A conversation with the given id does not exist

get /api/v1/conversations/{conversationId}/items
https://organization.gladly.com//api/v1/conversations/{conversationId}/items

Response samples

application/json
Copy
 Expand all Collapse all
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Customers

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.

Error Handling

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 customer

Create a new customer with the supplied profile data.

Request Body schema: application/json

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

Responses

201

customer created

400

error creating customer

409

Specified id is in use or a uniqueness constraint failed

post /api/v1/customer-profiles
https://organization.gladly.com//api/v1/customer-profiles

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "id": "OOrlNMXeS72gs_WEX2TtMg",
  • "name": "Francis Avallone",
  • "address": "4303 Spring Forest Ln, Westlake Village, CA 91362-5605",
  • "emails":
    [
    ],
  • "phones":
    [
    ],
  • "externalCustomerId": "a21c1636-c622-48b7-bf6a-d9032645aa55",
  • "customAttributes":
    {
    }
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "errors":
    {
    }
}

Find customers

Find customers by searching by choosing one of the following identifiers as query parameters:

/api/v1/customer-profiles?phoneNumber=%2B14151234567
query Parameters
email
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 + becomes %2B.

Responses

200

found customers

400

error finding customers

get /api/v1/customer-profiles
https://organization.gladly.com//api/v1/customer-profiles

Response samples

application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get customer

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.

path Parameters
customerId
string
Example: "OOrlNMXeS72gs_WEX2TtMg"

id of the customer

Responses

200

fetched customer

301

customer id no longer exists and has been changed due to a merge with another customer

404

customer not found

get /api/v1/customer-profiles/{customerId}
https://organization.gladly.com//api/v1/customer-profiles/{customerId}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "name": "Martha J Williams",
  • "address": "563 Rigoberto Station Apt. 197",
  • "emails":
    [
    ],
  • "phones":
    [
    ],
  • "externalCustomerId": "a21c1636-c622-48b7-bf6a-d9032645aa55",
  • "customAttributes":
    {
    },
  • "id": "OOrlNMXeS72gs_WEX2TtMg",
  • "createdAt": "2019-02-21T07:15:18.07272933Z",
  • "updatedAt": "2019-02-21T19:50:23.486566336Z"
}

Update customer

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.

path Parameters
customerId
string
Example: "OOrlNMXeS72gs_WEX2TtMg"

id of the customer

Request Body schema: application/json

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.

Responses

204

updated customer

400

error updating customer

404

customer not found

patch /api/v1/customer-profiles/{customerId}
https://organization.gladly.com//api/v1/customer-profiles/{customerId}

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "name": "Frankie Avalon",
  • "emails":
    [
    ],
  • "customAttributes":
    {
    }
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "errors":
    {
    }
}

Custom Reporting

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.

List Custom Reports

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.

path Parameters
dirPath
string
Example: "Utilization%20Report/20190206223006/"

Folder path of reports to list.

Responses

200

report list

404

report not found

get /api/customreporting/{dirPath}/
https://organization.gladly.com//api/customreporting/{dirPath}/

Response samples

application/json
Copy
 Expand all Collapse all