Gladly User Management API Guide

Auth method: HTTP Basic Auth (API token as username, API secret as password, Base64-encoded)

Setup steps

1. Log in to Gladly as an Admin.
2. Navigate to Settings > API Tokens.
3. Create a new API token; record the token ID and secret immediately (secret is shown once).
4. Base64-encode the string '{token_id}:{token_secret}'.
5. Pass the encoded value in the Authorization header as 'Basic {encoded_value}' on every request.
6. Optionally restrict the token to specific IP ranges in the token settings.

Required scopes

List Agents

• Method: GET
• URL: https://{org}.gladly.com/api/v1/agents
• Watch out for: Inactive agents are included by default; filter with ?active=true to exclude deactivated accounts.

Request example

GET /api/v1/agents?limit=20&cursor=abc123
Authorization: Basic {base64token}

Response example

{
  "items": [{"id":"agt_001","emailAddress":"jane@co.com","name":"Jane Doe","role":"AGENT","active":true}],
  "nextCursor": "def456"
}

Get Agent

• Method: GET
• URL: https://{org}.gladly.com/api/v1/agents/{agentId}
• Watch out for: Returns 404 if agent ID does not exist or belongs to a different organization.

Request example

GET /api/v1/agents/agt_001
Authorization: Basic {base64token}

Response example

{
  "id": "agt_001",
  "emailAddress": "jane@co.com",
  "name": "Jane Doe",
  "role": "AGENT",
  "active": true,
  "inboxes": ["inbox_1"]
}

Create Agent

• Method: POST
• URL: https://{org}.gladly.com/api/v1/agents
• Watch out for: A welcome/activation email is sent to the new agent automatically upon creation; no way to suppress this via API.

Request example

POST /api/v1/agents
Content-Type: application/json

{"emailAddress":"new@co.com","name":"New Agent","role":"AGENT"}

Response example

{
  "id": "agt_002",
  "emailAddress": "new@co.com",
  "name": "New Agent",
  "role": "AGENT",
  "active": true
}

Update Agent

• Method: PATCH
• URL: https://{org}.gladly.com/api/v1/agents/{agentId}
• Watch out for: PATCH replaces array fields (e.g., inboxes, teams) entirely; send the full desired array, not just additions.

Request example

PATCH /api/v1/agents/agt_002
Content-Type: application/json

{"role":"TEAM_LEAD","inboxes":["inbox_1","inbox_2"]}

Response example

{
  "id": "agt_002",
  "role": "TEAM_LEAD",
  "inboxes": ["inbox_1","inbox_2"]
}

Deactivate Agent

• Method: PATCH
• URL: https://{org}.gladly.com/api/v1/agents/{agentId}
• Watch out for: Gladly does not support hard-delete of agents. Deactivation (active=false) is the only offboarding mechanism via API.

Request example

PATCH /api/v1/agents/agt_002
Content-Type: application/json

{"active": false}

Response example

{
  "id": "agt_002",
  "active": false
}

List Teams

• Method: GET
• URL: https://{org}.gladly.com/api/v1/teams
• Watch out for: Team IDs are required when assigning agents to teams via the agent update endpoint.

Request example

GET /api/v1/teams
Authorization: Basic {base64token}

Response example

{
  "items": [{"id":"team_1","name":"Tier 1 Support"}]
}

List Inboxes

• Method: GET
• URL: https://{org}.gladly.com/api/v1/inboxes
• Watch out for: Inbox IDs must be retrieved before assigning agents; there is no lookup-by-name endpoint.

Request example

GET /api/v1/inboxes
Authorization: Basic {base64token}

Response example

{
  "items": [{"id":"inbox_1","name":"General Support","channelType":"EMAIL"}]
}

Get Agent Availability

• Method: GET
• URL: https://{org}.gladly.com/api/v1/agents/{agentId}/availability
• Watch out for: Read-only; agent availability cannot be set via the REST API.

Request example

GET /api/v1/agents/agt_001/availability
Authorization: Basic {base64token}

Response example

{
  "agentId": "agt_001",
  "status": "AVAILABLE",
  "updatedAt": "2024-11-01T10:00:00Z"
}

• Rate limits: Gladly enforces per-organization rate limits on API requests. Official documentation does not publish exact numeric limits publicly.
• Rate-limit headers: Yes
• Retry-After header: Yes
• Rate-limit notes: HTTP 429 is returned when rate limit is exceeded. Retry-After header is included in 429 responses. Gladly recommends exponential backoff.
• Pagination method: cursor
• Default page size: 20
• Max page size: 100
• Pagination pointer: cursor

• Webhooks available: Yes
• Webhook notes: Gladly supports outbound webhooks (called 'Notifications') that POST event payloads to a configured HTTPS endpoint. Webhooks are configured in Settings > Notifications in the Admin UI.
• Alternative event strategy: Polling the /api/v1/agents endpoint for agent change detection if webhook delivery is not suitable.
• Webhook events: conversation.created, conversation.assigned, conversation.closed, conversation.reopened, message.created, agent.created, agent.updated

• SCIM available: No
• SCIM version: Not documented
• Plan required: Enterprise
• Endpoint: Not documented

Limitations:

• Gladly does not offer a native SCIM 2.0 endpoint as of the latest available documentation.
• SSO via SAML 2.0 is available on Enterprise plans with Okta, Microsoft Entra ID, and Google Workspace.
• Automated provisioning/deprovisioning must be handled via the REST API (agents endpoints) or a middleware integration.
• Enterprise plan is required for SSO; SCIM support is not confirmed even at Enterprise tier.

Three lifecycle operations cover the majority of integration requirements:

• Provision: GET /api/v1/inboxes and GET /api/v1/teams to resolve IDs, then POST /api/v1/agents with emailAddress, name, role, inboxes, and teams. A welcome email fires automatically and cannot be suppressed. If the email already exists (including deactivated accounts), the API returns 409 Conflict - reactivate via PATCH instead of re-creating.

• Update: PATCH /api/v1/agents/{agentId} with the new role and the full desired inboxes array. PATCH treats array fields as full replacements, not appends - omitting an existing inbox removes it.

• Offboard: PATCH /api/v1/agents/{agentId} with {"active": false}. Hard-delete is not supported; deactivated agents remain in list responses unless filtered with ?active=true. If SSO is enabled, revoke the IdP session separately - API deactivation does not terminate active SSO sessions.

Provision a new support agent

1. Authenticate using Basic Auth with a valid Admin API token.
2. GET /api/v1/inboxes to retrieve the inbox ID(s) to assign the agent to.
3. GET /api/v1/teams to retrieve the team ID(s) if team assignment is needed.
4. POST /api/v1/agents with emailAddress, name, role, inboxes, and teams in the request body.
5. Store the returned agent id for future update or deactivation operations.
6. Note: a welcome email is sent to the new agent automatically.

Watch out for: If the email address already exists (even for a deactivated agent), the POST will return a 409 Conflict. Reactivate the existing agent via PATCH instead.

Update agent role and inbox assignments

1. Retrieve the agent's id via GET /api/v1/agents or from your internal records.
2. GET /api/v1/inboxes to confirm current inbox IDs.
3. PATCH /api/v1/agents/{agentId} with the new role value and the full desired inboxes array (not just additions).
4. Verify the response reflects the updated role and inbox list.

Watch out for: Sending only the new inbox in the inboxes array will remove all previously assigned inboxes. Always include the full desired set.

Offboard (deactivate) a departing agent

1. Retrieve the agent's id via GET /api/v1/agents?emailAddress={email} or from your records.
2. PATCH /api/v1/agents/{agentId} with body {"active": false}.
3. Confirm the response shows active: false.
4. If SSO is enabled, also disable or suspend the user in the IdP (Okta/Entra/Google Workspace) to block login.

Watch out for: Deactivating via the API does not terminate active SSO sessions. Revoke the IdP session separately to ensure immediate access removal.

The absence of SCIM is the primary integration risk: there is no standardized provisioning contract, so any automation you build is coupled to Gladly's proprietary REST schema and subject to undocumented rate limits (HTTP 429 with Retry-After; implement exponential backoff).

Pagination is cursor-based with a default page size of 20 and a maximum of 100 - full agent list traversal requires multiple requests and cursor chaining. Webhooks (agent.created, agent.updated) are available via Settings → Notifications but do not cover deactivation events explicitly, making polling GET /api/v1/agents the safer change-detection strategy for offboarding workflows.

An identity graph is essential here: without a persistent mapping of Gladly agent.id to your IdP's user object and HR system's employee ID, joiner/mover/leaver automation breaks on any email or name change, and the externalId field on the agent object is the recommended anchor for that cross-system linkage.