Genesys Cloud User Management API Guide

Auth method: OAuth 2.0 (Client Credentials or Authorization Code grant)

Setup steps

1. Log in to Genesys Cloud Admin console and navigate to Admin > Integrations > OAuth.
2. Create an OAuth client; select grant type (Client Credentials for server-to-server, Authorization Code for user-delegated).
3. Assign required permission scopes to the OAuth client.
4. Note the Client ID and Client Secret.
5. POST to https://login.{region}.pure.cloud/oauth/token with grant_type=client_credentials and Base64-encoded credentials in the Authorization header to obtain a Bearer token.
6. Include the Bearer token in the Authorization header for all API requests.

Required scopes

List users

• Method: GET
• URL: /api/v2/users
• Watch out for: Default page size is 25; max is 500. Use pageNumber (1-indexed). The state filter defaults to active; pass state=any to include inactive users.

Request example

GET /api/v2/users?pageSize=25&pageNumber=1&state=active
Authorization: Bearer {token}

Response example

{
  "entities": [{"id":"uuid","name":"Jane Doe","email":"jane@example.com","state":"active"}],
  "pageSize": 25,
  "pageNumber": 1,
  "total": 150,
  "pageCount": 6
}

Get user by ID

• Method: GET
• URL: /api/v2/users/{userId}
• Watch out for: Use the expand query parameter (e.g., expand=skills,languages,groups) to include nested objects; they are omitted by default.

Request example

GET /api/v2/users/3f4e5d6c-...
Authorization: Bearer {token}

Response example

{
  "id": "3f4e5d6c-...",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "state": "active",
  "department": "Support",
  "version": 4
}

Create user

• Method: POST
• URL: /api/v2/users
• Watch out for: password is required unless the org enforces SSO-only login. Division defaults to Home if omitted. Email and username must be unique org-wide.

Request example

POST /api/v2/users
Content-Type: application/json
{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "username": "jane@example.com",
  "password": "Temp@1234!",
  "division": {"id": "home-division-uuid"}
}

Response example

{
  "id": "new-uuid",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "state": "active",
  "version": 1
}

Update user (partial)

• Method: PATCH
• URL: /api/v2/users/{userId}
• Watch out for: version field is mandatory in the request body for optimistic concurrency. A stale version returns HTTP 409 Conflict.

Request example

PATCH /api/v2/users/3f4e5d6c-...
Content-Type: application/json
{
  "version": 4,
  "department": "Engineering",
  "title": "Senior Engineer"
}

Response example

{
  "id": "3f4e5d6c-...",
  "name": "Jane Doe",
  "department": "Engineering",
  "title": "Senior Engineer",
  "version": 5
}

Delete (deactivate) user

• Method: DELETE
• URL: /api/v2/users/{userId}
• Watch out for: DELETE performs a soft delete (state=deleted), not permanent removal. The user record is retained. To disable without deleting, PATCH state to inactive instead.

Request example

DELETE /api/v2/users/3f4e5d6c-...
Authorization: Bearer {token}

Response example

{
  "id": "3f4e5d6c-...",
  "state": "deleted"
}

Search users

• Method: POST
• URL: /api/v2/users/search
• Watch out for: Search uses a POST body with a query array. Supports EXACT, CONTAINS, STARTS_WITH, REQUIRED, OPTIONAL types. Rate limits on search are lower than standard GET endpoints.

Request example

POST /api/v2/users/search
Content-Type: application/json
{
  "query": [{"type":"EXACT","fields":["email"],"value":"jane@example.com"}],
  "pageSize": 25,
  "pageNumber": 1
}

Response example

{
  "total": 1,
  "pageSize": 25,
  "pageNumber": 1,
  "results": [{"id":"uuid","name":"Jane Doe","email":"jane@example.com"}]
}

Assign roles to user

• Method: PUT
• URL: /api/v2/users/{userId}/roles
• Watch out for: This is a full replacement (PUT), not additive. Omitting a currently assigned role will remove it. Requires the authorization scope.

Request example

PUT /api/v2/users/3f4e5d6c-.../roles
Content-Type: application/json
["role-uuid-1", "role-uuid-2"]

Response example

HTTP 200 OK
[
  {"id":"role-uuid-1","name":"Agent"},
  {"id":"role-uuid-2","name":"Supervisor"}
]

Get user's queue memberships

• Method: GET
• URL: /api/v2/users/{userId}/queues
• Watch out for: joined=true filters to only queues the user is actively joined to. Queue membership is managed separately from user creation and requires routing configuration permissions.

Request example

GET /api/v2/users/3f4e5d6c-.../queues?joined=true
Authorization: Bearer {token}

Response example

{
  "entities": [{"id":"queue-uuid","name":"Support Queue","joined":true}],
  "pageSize": 25,
  "pageNumber": 1,
  "total": 1
}

• Rate limits: Genesys Cloud enforces per-organization rate limits on API requests. Limits vary by endpoint category. Burst and sustained limits apply.
• Rate-limit headers: Yes
• Retry-After header: Yes
• Rate-limit notes: Response headers include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After on 429 responses. Genesys Cloud publishes per-resource rate limit tables in the Developer Center. Limits are org-wide, not per-token.
• Pagination method: offset
• Default page size: 25
• Max page size: 500
• Pagination pointer: pageNumber / pageSize (1-indexed page number)

• Webhooks available: Yes
• Webhook notes: Genesys Cloud provides event-driven notifications via its Notifications API using WebSocket connections. Clients subscribe to topics (including user-related topics) and receive real-time events over a persistent WebSocket channel.
• Alternative event strategy: For outbound HTTP webhooks (push-based), Genesys Cloud supports EventBridge integration (AWS) and Process Automation triggers that can POST to external HTTP endpoints on user-related events.
• Webhook events: v2.users.{userId}.activity, v2.users.{userId}.presence, v2.users.{userId}.routingStatus, v2.users.{userId}.conversationsummary, v2.users.{userId}.geolocation, v2.users.{userId}.station, v2.users.{userId}.outofoffice

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise (SSO must be configured as a prerequisite)

• Endpoint: https://api.{region}.pure.cloud/api/v2/scim/v2

• Supported operations: GET /Users (list with filter), GET /Users/{id}, POST /Users (create), PUT /Users/{id} (full replace), PATCH /Users/{id} (partial update via RFC 7644 operations), DELETE /Users/{id} (deactivate), GET /Groups, GET /Groups/{id}, POST /Groups, PATCH /Groups/{id}, DELETE /Groups/{id}, GET /ServiceProviderConfig, GET /Schemas, GET /ResourceTypes

Limitations:

• SSO must be enabled and configured before SCIM provisioning is available.
• Sync is unidirectional: IdP pushes to Genesys Cloud; changes made directly in Genesys Cloud UI may be overwritten on next sync.
• DELETE via SCIM deactivates (soft-deletes) the user; it does not permanently remove the record.
• Custom Genesys Cloud attributes (skills, queues, roles) are not managed via standard SCIM schemas; use the REST API for those.
• Officially validated with Okta, Azure AD (Entra ID), and ADFS. Other IdPs may work but are not officially supported.
• SCIM Groups map to Genesys Cloud groups, not roles or divisions.
• Enterprise plan required; not available on lower-tier plans.

Provisioning a fully configured agent is a multi-step sequence with no atomic endpoint: POST /api/v2/users creates the account, PUT /api/v2/users/{userId}/roles assigns roles (full replacement - always fetch current roles first to avoid accidental removal), and POST /api/v2/routing/queues/{queueId}/members adds queue membership.

Partial failure at any step leaves the user in an incomplete state; implement rollback or idempotency logic accordingly.

Deactivating a departing employee requires resolving the UUID first (via GET /api/v2/users with a search query or POST /api/v2/users/search), then fetching the current version integer, then issuing PATCH /api/v2/users/{userId} with {"version": {n}, "state": "inactive"}. The version field is mandatory for optimistic concurrency - a stale value returns HTTP 409 Conflict. DELETE /api/v2/users/{userId} is a soft delete (state=deleted), not permanent removal; no hard-delete endpoint exists in the public API.

Bulk IdP sync via SCIM requires Enterprise plan and SSO configured as a prerequisite. The SCIM base URL is https://api.{region}.pure.cloud/api/v2/scim/v2; the connector authenticates with a Client Credentials token scoped to scim. SCIM handles core identity attributes (userName, givenName, familyName, active) and group membership, but routing skills, queue memberships, and role assignments beyond basic provisioning fall outside SCIM's scope and must be managed via the REST API separately.

Provision a new agent with role and queue assignment

1. POST /api/v2/users with name, email, username, password, and division to create the user account.
2. Capture the returned user id (UUID) from the response.
3. PUT /api/v2/users/{userId}/roles with an array of role UUIDs (e.g., Agent role) to assign roles.
4. POST /api/v2/routing/queues/{queueId}/members with body [{"id": "{userId}", "joined": true}] to add the user to the appropriate routing queue.
5. Optionally POST /api/v2/users/{userId}/routingskills to assign routing skills with proficiency levels.

Watch out for: Role and queue assignment are separate API calls after user creation. There is no single atomic endpoint to create a fully configured agent. If any step fails, the user may be partially provisioned.

Deactivate a departing employee

1. GET /api/v2/users?searchQuery={email} or POST /api/v2/users/search to resolve the user's UUID by email.
2. GET /api/v2/users/{userId} to retrieve the current version number.
3. PATCH /api/v2/users/{userId} with body {"version": {currentVersion}, "state": "inactive"} to disable login without deleting the record.
4. Optionally DELETE /api/v2/users/{userId} for a soft-delete if full removal from active roster is needed.

Watch out for: Setting state=inactive prevents login but retains historical interaction data. DELETE also soft-deletes; neither operation permanently purges the user record from the system.

Bulk-sync users from an IdP via SCIM

1. Confirm Enterprise plan is active and SSO is configured in Genesys Cloud Admin > Single Sign-on.
2. In the IdP (Okta or Azure AD), add the Genesys Cloud SCIM application and configure the SCIM base URL: https://api.{region}.pure.cloud/api/v2/scim/v2.
3. Generate a Genesys Cloud OAuth Client Credentials token with the scim scope and provide it as the Bearer token in the IdP SCIM connector.
4. Map IdP user attributes to SCIM schema fields (userName → email, givenName, familyName, active, etc.).
5. Assign users/groups in the IdP to the Genesys Cloud SCIM app to trigger initial provisioning via POST /Users.
6. Ongoing attribute changes in the IdP will trigger PATCH /Users/{id} calls automatically.
7. Monitor provisioning logs in the IdP and audit logs in Genesys Cloud Admin > Audit Viewer.

Watch out for: SCIM only manages core identity attributes. Routing skills, queue memberships, and role assignments beyond basic provisioning must still be managed via the REST API or manually in the Genesys Cloud UI. Changes made directly in Genesys Cloud to SCIM-managed fields will be overwritten on the next IdP sync.

The primary integration trap is assuming SCIM covers full agent configuration - it does not. SCIM is unidirectional (IdP to Genesys only), and any attribute changes made directly in the Genesys Cloud UI to SCIM-managed fields will be silently overwritten on the next IdP sync.

Custom Genesys attributes (skills, queues, roles) are outside standard SCIM schemas entirely.

A second trap is role assignment via PUT /api/v2/users/{userId}/roles: this is a full replacement, not an additive operation. Sending only the new role UUID without including existing assignments will strip all previously assigned roles. Always GET current roles before issuing a PUT.

For identity graph use cases, note that nested objects (skills, languages, groups, manager) are omitted from user responses unless explicitly requested via the expand parameter - pipelines that skip this will produce an incomplete identity record.

Additionally, the state filter default means any query that does not explicitly pass state=any will silently exclude inactive users from results, producing misleading counts in access audits or reconciliation jobs.