Talkdesk User Management API Guide

Auth method: OAuth 2.0 (client_credentials grant)

Setup steps

1. Log in to Talkdesk Admin and navigate to Settings > Integrations > API Credentials.
2. Create a new OAuth 2.0 client application to obtain a client_id and client_secret.
3. POST to https://api.talkdeskapp.com/oauth/token with grant_type=client_credentials, client_id, and client_secret to receive a Bearer access token.
4. Include the token in all API requests as Authorization: Bearer .
5. Tokens expire; implement token refresh logic using the same client_credentials flow.

Required scopes

List Users

• Method: GET
• URL: https://api.talkdeskapp.com/users
• Watch out for: Inactive users are included by default; filter with status=active if needed.

Request example

GET /users?page[number]=1&page[size]=20
Authorization: Bearer <token>

Response example

{
  "users": [{"id":"uuid","name":"Jane Doe","email":"jane@example.com","status":"active"}],
  "meta": {"total":150,"page":1}
}

Get User

• Method: GET
• URL: https://api.talkdeskapp.com/users/{user_id}
• Watch out for: Returns 404 if user_id does not exist or belongs to a different account.

Request example

GET /users/abc-123
Authorization: Bearer <token>

Response example

{
  "id": "abc-123",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role": "agent",
  "status": "active"
}

Create User

• Method: POST
• URL: https://api.talkdeskapp.com/users
• Watch out for: A welcome/activation email is sent to the user upon creation; no option to suppress in standard API.

Request example

POST /users
Content-Type: application/json
{
  "name": "John Smith",
  "email": "john@example.com",
  "role": "agent"
}

Response example

{
  "id": "def-456",
  "name": "John Smith",
  "email": "john@example.com",
  "status": "active"
}

Update User

• Method: PATCH
• URL: https://api.talkdeskapp.com/users/{user_id}
• Watch out for: Only include fields to be changed; omitted fields are not modified.

Request example

PATCH /users/def-456
Content-Type: application/json
{
  "role": "supervisor"
}

Response example

{
  "id": "def-456",
  "role": "supervisor",
  "updated_at": "2024-06-01T10:00:00Z"
}

Deactivate / Delete User

• Method: DELETE
• URL: https://api.talkdeskapp.com/users/{user_id}
• Watch out for: Deactivation may be preferred over deletion to preserve historical reporting data. Confirm behavior with Talkdesk support.

Request example

DELETE /users/def-456
Authorization: Bearer <token>

Response example

HTTP 204 No Content

List Roles

• Method: GET
• URL: https://api.talkdeskapp.com/roles
• Watch out for: Role IDs are account-specific; do not hardcode role names across accounts.

Request example

GET /roles
Authorization: Bearer <token>

Response example

{
  "roles": [{"id":"role-1","name":"agent"},{"id":"role-2","name":"supervisor"}]
}

List Teams

• Method: GET
• URL: https://api.talkdeskapp.com/teams
• Watch out for: Team IDs required when assigning users to teams via POST /users or PATCH /users/{id}.

Request example

GET /teams
Authorization: Bearer <token>

Response example

{
  "teams": [{"id":"team-1","name":"Support Team A"}]
}

Get OAuth Token

• Method: POST
• URL: https://api.talkdeskapp.com/oauth/token
• Watch out for: Tokens expire in 3600 seconds by default; cache and refresh proactively to avoid 401 errors mid-workflow.

Request example

POST /oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=xxx&client_secret=yyy

Response example

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600
}

• Rate limits: Talkdesk enforces API rate limits but does not publicly document specific numeric thresholds per plan in official docs as of this research.

• Rate-limit headers: Unknown

• Retry-After header: Unknown

• Rate-limit notes: Official docs do not explicitly publish rate-limit headers or Retry-After behavior. Contact Talkdesk support for account-specific limits.

• Pagination method: offset

• Default page size: 20

• Max page size: 100

• Pagination pointer: page[number] / page[size]

• Webhooks available: Yes

• Webhook notes: Talkdesk supports webhooks for contact center events (calls, interactions) via the Talkdesk Webhooks API. User lifecycle events (create/update/delete) are not explicitly documented as webhook triggers in official docs.

• Alternative event strategy: Poll GET /users on a schedule to detect user changes, or use SCIM provisioning events from your IdP for user lifecycle automation.

• Webhook events: call.initiated, call.completed, interaction.created, interaction.updated

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Available across Talkdesk CX Cloud plans; Enterprise-tier context referenced in some documentation. Verify current plan eligibility with Talkdesk.

• Endpoint: https://api.talkdeskapp.com/scim/v2

• Supported operations: GET /Users, GET /Users/{id}, POST /Users, PUT /Users/{id}, PATCH /Users/{id}, DELETE /Users/{id}, GET /Groups, POST /Groups, PATCH /Groups/{id}, DELETE /Groups/{id}, GET /ServiceProviderConfig, GET /Schemas

Limitations:

• SCIM token is generated separately from OAuth API credentials; managed in Talkdesk Admin under SSO/SCIM settings.
• SCIM Groups map to Talkdesk Teams; not all team attributes are exposed via SCIM.
• Supported IdPs with documented setup: Okta, Microsoft Entra ID (Azure AD), OneLogin.
• Google Workspace SCIM integration is not officially documented by Talkdesk.
• PATCH operations use SCIM 2.0 patch syntax (RFC 7644); full PUT replaces the user object.

Three integration patterns cover the primary lifecycle operations.

For single-agent onboarding via REST: obtain a Bearer token via POST /oauth/token, resolve role and team UUIDs dynamically via GET /roles and GET /teams (never hardcode these

they are account-specific), then POST /users with name, email, role ID, and teams array.

A welcome email fires automatically on user creation with no documented suppression option;

coordinate timing with HR or IT workflows accordingly.

For scale provisioning, SCIM with Okta is the most documented path.

Generate a SCIM bearer token in Talkdesk Admin, configure the Okta Talkdesk app with base URL https://api.talkdeskapp.com/scim/v2, map userName to email, then assign users or groups in Okta to trigger provisioning.

SCIM Groups map to Talkdesk Teams - mismatched names between Okta groups and existing Talkdesk teams will create duplicate teams.

Microsoft Entra ID and OneLogin are also officially documented;

Google Workspace SCIM is not.

For offboarding via REST, prefer PATCH /users/{user_id} with status: inactive over DELETE to preserve historical call recording attribution and reporting data.

If SCIM is active, deprovision through the IdP only - mixing REST deactivation and SCIM deprovision on the same user risks conflicts.

Onboard a new agent via REST API

1. POST /oauth/token to obtain a Bearer access token.
2. GET /roles to retrieve the role ID for 'agent'.
3. GET /teams to retrieve the team ID for the target team.
4. POST /users with name, email, role ID, and teams array.
5. Store the returned user ID for future updates or deactivation.

Watch out for: A welcome email is automatically sent to the new user's email address upon creation; coordinate with HR/IT to avoid premature notifications.

Provision users at scale via SCIM with Okta

1. In Talkdesk Admin, navigate to Settings > Security > SCIM and generate a SCIM bearer token.
2. In Okta, add the Talkdesk application from the Okta Integration Network.
3. Configure the SCIM base URL as https://api.talkdeskapp.com/scim/v2 and paste the bearer token.
4. Map Okta profile attributes to Talkdesk SCIM user attributes (userName → email, etc.).
5. Assign users or groups in Okta to trigger SCIM provisioning to Talkdesk.
6. Test with a single user push before enabling group-level provisioning.

Watch out for: SCIM Groups in Talkdesk map to Teams; ensure team names in Talkdesk match group names pushed from Okta to avoid duplicate team creation.

Deactivate a departed employee

1. POST /oauth/token to obtain a fresh Bearer token.
2. GET /users?email=departed@example.com to resolve the user's Talkdesk UUID.
3. PATCH /users/{user_id} with {"status": "inactive"} to deactivate without deleting.
4. Verify the user can no longer log in while historical data is preserved.

Watch out for: If using SCIM, deprovisioning the user in the IdP will trigger a DELETE or deactivation via SCIM automatically; avoid double-deactivating via both REST and SCIM to prevent conflicts.

The dual-token architecture is the most common integration trap: developers who configure OAuth 2.0 correctly for the REST API and then attempt to reuse that token against SCIM endpoints will receive auth failures with no clear error message distinguishing the token type mismatch. Both tokens must be provisioned and rotated independently.

A second structural caveat applies to identity graph consistency: role IDs and team IDs are account-scoped UUIDs with no stable cross-account values. Any automation that hardcodes these identifiers - common when copying provisioning scripts between staging and production environments - will silently assign wrong roles or fail on team lookups.

Always resolve IDs dynamically via GET /roles and GET /teams at runtime to keep the identity graph accurate across environments.

API versioning is not prominently surfaced in Talkdesk's developer documentation, and rate-limit headers are undocumented publicly. Both represent operational risk for long-running integrations: breaking changes may not be announced with standard deprecation windows, and burst provisioning jobs may hit 429 thresholds without a reliable Retry-After signal.

Contact Talkdesk support to confirm account-specific rate limits before building high-volume provisioning pipelines.