What we do
Tools
Industries
Department
How we workLet's talk →
Home/Gladly
Gladly

The Gladly API, and How Outside Data Reaches the Customer Timeline

A customer writes in about a late parcel. The agent can scroll back through two years of that person's conversations in Gladly, and still has to open another tab to find the tracking number. The Gladly API closes that gap in two directions: your code calls Gladly, or Gladly calls your code while the agent is looking at the profile.

Where Gladly stops

The agent has the full history but not the current facts about orders, billing and the account.

Stuck on Gladly? Let's solve it →
Gladly API basics

Docs: developer.gladly.com. Requests go to your own Gladly address, https://yourcompany.gladly.com/api/v1/..., and Gladly can switch on a separate sandbox at yourcompany.gladly.qa.

Auth: HTTP Basic over HTTPS. The user name is an agent's email and the password is that user's API token.

More settings API Tokens Create Token

First call: search for a customer with GET /api/v1/customer-profiles?email=..., which returns up to 50 matching profiles, newest update first.

Limits: by default, 10 requests a second per HTTP method, counted across every token in your organization. Report calls are tighter: 10 a minute, and 2 running at once.

Calling Gladly, or letting Gladly call you

Most Gladly integrations use both. The question is which data goes where.

REST API

Your code calls Gladly

  • Create, find and update customer profiles, and read conversations, tasks and agents.
  • Add Customer Activity to the timeline: a return received, a survey answered, an issue logged in another system. Gladly notes these aren't sent to the customer.
  • Register webhooks so your code hears when a conversation closes or a profile changes.
Lookup Adaptor

Gladly calls your code

  • You run a small web service that implements Gladly's Lookup API, with signed JSON requests.
  • Gladly asks it for data at moments like an agent opening a profile, so orders, loyalty points or lifetime value show up current.
  • It can also offer Actions, such as cancelling an order or awarding points, without the agent leaving Gladly.

Facts that change by the hour, like order status, belong in a lookup. Events worth keeping in the customer's history belong in the timeline as activity. If your store platform already has a ready-made Gladly integration, use it, and save the API for the systems that don't.

Your first authenticated Gladly request

  1. 1

    Give one user the API User permission

    Settings Users

    Open the user's profile, tick API User, leave the Agent role in place, and save. Gladly suggests a dedicated user just for API calls, which keeps audits simple when you're asked who changed what.

  2. 2

    Create and name the token

    More settings API Tokens Create Token

    Click the token's name to rename it after the integration that will use it. Store it in your secrets manager straight away.

    Watch for: Gladly shows a new token only once. Leave the page without copying it and you'll be making another.

  3. 3

    Try it against the sandbox

    The sandbox at yourcompany.gladly.qa is kept apart from production, so test profiles and test webhooks can't reach real customers. Ask Gladly to enable it if you don't have one yet.

  4. 4

    Look up a customer

    curl -u agent@yourcompany.com:$GLADLY_API_TOKEN "https://yourcompany.gladly.com/api/v1/customer-profiles?email=jo@example.com". You can also search by phone number or by externalCustomerId, the ID from your own system of record.

    Watch for: matching on email alone. Writing your own customer ID onto the profile makes every later sync far less ambiguous.

  5. 5

    Read the rate headers on the response

    Ratelimit-Limit-Second and Ratelimit-Remaining-Second show where your organization stands this second. On a 429, retry with an exponential backoff that includes some randomness, as Gladly's docs advise.

A home goods brand whose agents stopped switching tabs

A direct-to-consumer home goods brand: Gladly for support, orders in the store platform, billing in accounting.

Before

Agents opened a customer's Gladly timeline and saw every past conversation, but not the order, the invoice or whether a refund had gone through.

They went looking in other tools, then entered any refund a second time in accounting afterward.

After

Order, billing and account details now sit in the timeline itself.

A refund issued from Gladly posts to accounting on its own, so the agent answers once and moves to the next customer.

Gladly webhook and sync traps

The webhook refuses to save

How you'll know: Creating or enabling the webhook fails, though the URL is right.

Fix: Gladly sends a PING event whenever you enable a webhook or change its URL, and the change only sticks if your endpoint answers with a 200. New webhooks start disabled. You can have up to 20 per organization.

Events stop after one bad hour

How you'll know: Nothing arrives, and the API users in your organization got an email from Gladly.

Fix: A failed delivery, meaning anything outside 2xx or no answer in 15 seconds, is retried 4 times: after 30 seconds, 5 minutes, 30 minutes and an hour. Then the webhook is deactivated. Fix the endpoint, switch it back on under Settings > Webhooks, and read back anything that changed while it was off. The last 100 request logs help you find where it broke.

A receiver anyone can post to

How you'll know: Your endpoint accepts any request that looks like a Gladly event.

Fix: Set Basic credentials or a header token on the webhook. Gladly sends them with every delivery, so the receiver can reject anything without them.

A backfill slowing down live lookups

How you'll know: Agent-facing calls start getting 429s the morning a bulk import runs.

Fix: The per-second limit counts every token your organization holds. Pace the bulk job on the remaining-requests header and leave room for the calls agents are waiting on.

Two profiles for one customer

How you'll know: The same order shows on one profile but not the other.

Fix: Gladly merges profiles and fires CUSTOMER_PROFILE/MERGED when it does. Listen for it and move your stored link to the surviving profile.

Gladly, the product behind the API

Is Gladly a CRM?

No, not as a sales tool. There's no pipeline or deal stage. What Gladly keeps for each customer is one running history of support conversations across phone, chat, email and SMS, which covers part of what a CRM gives a support team.

What is Gladly used for?

Running customer service. Calls, chats, emails and texts from one person land in a single continuing conversation instead of a fresh ticket each time, and that's the main thing setting it apart from a ticketing system.

Where do I log into Gladly?

At your organization's own Gladly address, which is usually a subdomain such as yourcompany.gladly.com set up when the workspace was created. That's the same address the API uses. If you don't have the link, your Gladly administrator does.

Can the Gladly API create webhooks, or only the settings page?

The API creates them, and settings bring them back. You create a webhook through the API, choosing its events, URL and credentials. Reactivating one that Gladly switched off after failed deliveries happens under Settings > Webhooks.

Who builds a Gladly Lookup Adaptor?

Whoever owns the systems the data lives in, because the adaptor runs on your side and talks to them. n-frames writes and tests that service for brands whose order, billing or subscription data has no ready-made Gladly integration, along with the refund posting to accounting.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.