RingCentral User Management API Guide

Auth method: OAuth 2.0

Setup steps

1. Register an application at https://developers.ringcentral.com/my-account.html#/applications
2. Select the appropriate auth flow: Authorization Code (user-facing apps), JWT (server-to-server/service accounts), or Client Credentials
3. Note the Client ID and Client Secret from the app dashboard
4. For JWT flow: create a service account user in RingCentral Admin Portal and generate a JWT credential
5. Exchange credentials for an access token at https://platform.ringcentral.com/restapi/oauth/token
6. Include the access token as a Bearer token in the Authorization header of all API requests
7. Access tokens expire in 1 hour; use the refresh token (Authorization Code flow) or re-authenticate (JWT flow) to obtain a new one

Required scopes

List Users (Extensions)

• Method: GET
• URL: https://platform.ringcentral.com/restapi/v1.0/account/{accountId}/extension
• Watch out for: Use accountId '~' to reference the authenticated user's account. Filter by type=User to exclude non-user extensions (departments, voicemail boxes, etc.).

Request example

GET /restapi/v1.0/account/~/extension?type=User&status=Enabled&perPage=100&page=1
Authorization: Bearer {access_token}

Response example

{
  "uri": "https://platform.ringcentral.com/restapi/v1.0/account/~/extension?page=1&perPage=100",
  "records": [{"id": "12345", "extensionNumber": "101", "name": "Jane Doe", "status": "Enabled"}],
  "paging": {"page": 1, "perPage": 100, "totalPages": 3, "totalElements": 250}
}

Get User

• Method: GET
• URL: https://platform.ringcentral.com/restapi/v1.0/account/{accountId}/extension/{extensionId}
• Watch out for: Use extensionId '~' to retrieve the currently authenticated user's own profile.

Request example

GET /restapi/v1.0/account/~/extension/12345
Authorization: Bearer {access_token}

Response example

{
  "id": "12345",
  "extensionNumber": "101",
  "contact": {"firstName": "Jane", "lastName": "Doe", "email": "jane@example.com"},
  "status": "Enabled",
  "type": "User"
}

Create User (Extension)

• Method: POST
• URL: https://platform.ringcentral.com/restapi/v1.0/account/{accountId}/extension
• Watch out for: Newly created users have status 'NotActivated' until they complete email verification or an admin activates them. A license must be available in the account to assign to the new user.

Request example

POST /restapi/v1.0/account/~/extension
Authorization: Bearer {access_token}
Content-Type: application/json
{
  "type": "User",
  "contact": {"firstName": "John", "lastName": "Smith", "email": "john@example.com"},
  "extensionNumber": "102"
}

Response example

{
  "id": "67890",
  "extensionNumber": "102",
  "status": "NotActivated",
  "contact": {"firstName": "John", "lastName": "Smith", "email": "john@example.com"}
}

Update User

• Method: PUT
• URL: https://platform.ringcentral.com/restapi/v1.0/account/{accountId}/extension/{extensionId}
• Watch out for: PUT replaces the full resource; omitting optional fields may clear them. Use only the fields you intend to set.

Request example

PUT /restapi/v1.0/account/~/extension/12345
Authorization: Bearer {access_token}
Content-Type: application/json
{
  "contact": {"firstName": "Jane", "lastName": "Doe-Updated", "department": "Engineering"}
}

Response example

{
  "id": "12345",
  "contact": {"firstName": "Jane", "lastName": "Doe-Updated", "department": "Engineering"},
  "status": "Enabled"
}

Disable / Suspend User

• Method: PUT
• URL: https://platform.ringcentral.com/restapi/v1.0/account/{accountId}/extension/{extensionId}
• Watch out for: Setting status to 'Disabled' suspends the user but retains their data and license. There is no dedicated PATCH endpoint; use PUT with the status field.

Request example

PUT /restapi/v1.0/account/~/extension/12345
Authorization: Bearer {access_token}
Content-Type: application/json
{
  "status": "Disabled"
}

Response example

{
  "id": "12345",
  "status": "Disabled"
}

Delete User (Extension)

• Method: DELETE
• URL: https://platform.ringcentral.com/restapi/v1.0/account/{accountId}/extension/{extensionId}
• Watch out for: Deleting an extension is irreversible and releases the license. Only extensions of type 'User' with status 'Disabled' or 'NotActivated' can typically be deleted via API.

Request example

DELETE /restapi/v1.0/account/~/extension/12345
Authorization: Bearer {access_token}

Response example

HTTP 204 No Content

List User Roles / Permissions

• Method: GET
• URL: https://platform.ringcentral.com/restapi/v1.0/account/{accountId}/extension/{extensionId}/assigned-role
• Watch out for: Role assignment is separate from user creation. Roles must be pre-configured in the RingCentral Admin Portal before assignment via API.

Request example

GET /restapi/v1.0/account/~/extension/12345/assigned-role
Authorization: Bearer {access_token}

Response example

{
  "uri": "...",
  "records": [{"id": "1", "displayName": "Standard User", "siteCompatible": true}]
}

Bulk Create/Update Users

• Method: POST
• URL: https://platform.ringcentral.com/restapi/v1.0/account/{accountId}/extension/bulk-create
• Watch out for: Bulk operations are asynchronous; check individual record statuses in the response. Partial failures are possible - some records may succeed while others fail.

Request example

POST /restapi/v1.0/account/~/extension/bulk-create
Authorization: Bearer {access_token}
Content-Type: application/json
{
  "records": [
    {"type": "User", "contact": {"firstName": "A", "email": "a@x.com"}},
    {"type": "User", "contact": {"firstName": "B", "email": "b@x.com"}}
  ]
}

Response example

{
  "response": [
    {"id": "111", "status": "NotActivated"},
    {"id": "112", "status": "NotActivated"}
  ]
}

• Rate limits: RingCentral enforces per-app, per-user rate limits grouped by API usage plan (Light, Medium, Heavy, Auth). Limits are applied per minute. Exceeding limits returns HTTP 429.
• Rate-limit headers: Yes
• Retry-After header: Yes
• Rate-limit notes: Each endpoint is classified into a usage plan (Light/Medium/Heavy/Auth). Headers X-Rate-Limit-Limit, X-Rate-Limit-Remaining, X-Rate-Limit-Window, and Retry-After are returned. User-management endpoints (read/write extensions) are typically Heavy plan.
• Pagination method: offset
• Default page size: 100
• Max page size: 1000
• Pagination pointer: page and perPage (page is 1-indexed; perPage sets page size)

• Webhooks available: Yes
• Webhook notes: RingCentral supports webhooks via its Subscription API. Subscriptions are created via POST to /restapi/v1.0/subscription and deliver events to a publicly accessible HTTPS endpoint. Subscriptions expire and must be renewed (max TTL is configurable, typically up to 20160 minutes / 14 days).
• Alternative event strategy: RingCentral also supports WebSocket-based subscriptions (PubNub transport deprecated) for real-time event delivery without requiring a public endpoint.
• Webhook events: /restapi/v1.0/account//extension, /restapi/v1.0/account//extension//presence, /restapi/v1.0/account//extension//message-store, /restapi/v1.0/account//extension//telephony/sessions, /restapi/v1.0/account//extension/~/voicemail

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise (RingEX Ultra or Enterprise tier; SSO must be configured as a prerequisite)

• Endpoint: https://platform.ringcentral.com/scim/v2

• Supported operations: GET /Users (list users), GET /Users/{id} (get user), POST /Users (create user), PUT /Users/{id} (replace user), PATCH /Users/{id} (update user), DELETE /Users/{id} (delete user), GET /Groups (list groups), GET /ServiceProviderConfig, GET /Schemas

Limitations:

• SSO (SAML 2.0) must be enabled before SCIM provisioning can be activated
• SCIM provisioning requires Enterprise-tier plan (Ultra or above for RingEX)
• Supported IdPs with native connectors: Okta, Microsoft Entra ID (Azure AD), OneLogin
• Group provisioning support is limited; not all IdP group-push features are fully supported
• SCIM token is generated in the RingCentral Admin Portal under Tools > User Management > SCIM
• SCIM token does not use OAuth 2.0; it is a static bearer token generated in the admin UI

Provisioning a new employee requires a POST to /restapi/v1.0/account/~/extension with type=User and core contact fields.

The returned user will have status NotActivated - a separate PUT to /assigned-role is needed to set the role, and a license must be confirmed available via GET /account/~/service-info before bulk runs, or the create call will fail.

Deprovisioning requires a PUT with status=Disabled before a DELETE can be issued; attempting to DELETE an Enabled extension returns an error, and deletion is irreversible - voicemail and call logs are lost.

SCIM sync with Okta requires the account to be on an Enterprise/Ultra plan with SAML 2.0 SSO already active.

The SCIM bearer token is generated under Tools > User Management > SCIM in the Admin Portal - it is a static credential, not an OAuth token, and does not expire automatically but can be revoked.

Group push support via SCIM is limited; verify supported attributes in the Okta RingCentral OIN app configuration before relying on group-based provisioning.

Webhook subscriptions for real-time user-state events expire at approximately 14 days and require explicit renewal logic to avoid event gaps.

Provision a new employee

1. POST /restapi/v1.0/account/~/extension with type=User, contact.firstName, contact.lastName, contact.email to create the extension
2. Note the returned extension id; status will be 'NotActivated'
3. PUT /restapi/v1.0/account/~/extension/{id}/assigned-role to assign the appropriate role (e.g., Standard User)
4. Optionally assign a phone number via PUT /restapi/v1.0/account/~/extension/{id}/phone-number
5. Trigger activation email or set status to 'Enabled' if SSO is configured (user won't need password)

Watch out for: A license must be available in the account before creating a new user. Check account license availability via GET /restapi/v1.0/account/~/service-info before bulk provisioning.

Deprovision a departing employee

1. GET /restapi/v1.0/account/~/extension?email={email} to locate the user's extensionId
2. PUT /restapi/v1.0/account/~/extension/{id} with status=Disabled to immediately suspend access
3. Optionally reassign or forward the user's phone number to another extension
4. DELETE /restapi/v1.0/account/~/extension/{id} to permanently remove the extension and release the license

Watch out for: DELETE will fail if the extension is still in 'Enabled' status. Always disable first. Deletion is irreversible; voicemail and call logs associated with the extension are lost.

Sync users via SCIM with Okta

1. Ensure RingCentral account is on an Enterprise/Ultra plan with SSO (SAML 2.0) configured
2. In RingCentral Admin Portal, navigate to Tools > User Management > SCIM and generate a SCIM bearer token
3. In Okta, add the RingCentral application from the Okta Integration Network (OIN)
4. Configure the SCIM base URL as https://platform.ringcentral.com/scim/v2 and paste the bearer token
5. Enable provisioning features: Push New Users, Push Profile Updates, Deactivate Users
6. Assign users/groups in Okta to trigger SCIM provisioning to RingCentral

Watch out for: SCIM token is a static credential - store it securely. If SSO is not configured before enabling SCIM, provisioning will fail. Group push support is limited; verify supported attributes in the Okta RingCentral app configuration.

The most common integration failure mode is treating the REST API and SCIM API as a unified identity graph when they are not.

Writes via SCIM are not guaranteed to be immediately visible via REST API reads, which breaks any provisioning pipeline that creates a user via SCIM and then immediately queries the REST API to confirm or enrich the record. Build explicit retry and consistency-check logic between the two surfaces.

The Heavy rate limit (10 req/min per app per user) on extension endpoints is the second trap: sequential per-user provisioning loops will hit this ceiling quickly. Use bulk-create for initial loads and design incremental sync to batch updates.

Finally, the SCIM static token is a single credential with no automatic rotation - treat it as a high-value secret, store it in a secrets manager, and implement revocation procedures as part of your offboarding runbook for the integration itself, not just for end users.