8x8 Administration User Management API for provisioning, updating and deprovisioning users across an 8x8 UCaaS/CCaaS tenant.
openapi: 3.0.0
info:
title: 8x8 Administration - User Management API
version: "1.0"
description: |
User management API providing endpoints to create, retrieve, list, update, and delete users.
The current version of the API is v1.0.
## Authentication
All requests to this API require authentication using an API key. Include your API key in the request header:
```
x-api-key: YOUR_API_KEY
```
## Versioning
The API version is specified through a vendor-specific media type. Send it in the `Content-Type` header for requests that carry a payload (such as `POST` and `PUT`) and in the `Accept` header for requests that return a payload (`GET`, and asynchronous `DELETE` operations that return an operation resource).
```
Content-Type: application/vnd.users.v1+json # on POST/PUT (request payload)
Accept: application/vnd.users.v1+json # on GET (response payload)
```
## Base URL
`https://api.8x8.com/admin-provisioning`
## Endpoints
| Endpoint | Method | Purpose | Async? |
|----------|--------|---------|--------|
| `/users` | GET | Retrieve paginated list of users with filtering | No |
| `/users` | POST | Create a new user account | Yes |
| `/users/{userId}` | GET | Retrieve a specific user's details | No |
| `/users/{userId}` | PUT | Update an existing user account | Yes |
| `/users/{userId}` | DELETE | Remove a user account | Yes |
## OpenAPI Specification
Download the complete OpenAPI specification: [user-api-v1.yaml](/administration/user-api-v1.yaml)
servers:
- url: https://api.8x8.com/admin-provisioning
description: Production
security:
- ApiKeyAuth: []
paths:
/users:
get:
operationId: listUsers
summary: List users
description: |
List users with optional filtering, sorting, and infinite scroll pagination.
Uses scrollId-based pagination for efficient navigation through large datasets.
tags:
- Users
parameters:
- name: X-Request-Id
in: header
description: Optional request identifier for tracking
required: false
schema:
type: string
format: uuid
- name: pageSize
in: query
description: 'Number of items per page (default: 100)'
required: false
schema:
type: integer
example: 100
- name: scrollId
in: query
description: 'Scroll identifier for retrieving the next page of results'
required: false
schema:
type: string
- name: filter
in: query
description: "RSQL filter expression (e.g., 'basicInfo.userName==jane.doe@corp.com', 'basicInfo.status==ACTIVE')"
required: false
schema:
type: string
example: "basicInfo.status==ACTIVE"
- name: sort
in: query
description: "Sort expression. Use '+' prefix or no prefix for ascending order, '-' prefix for descending order (e.g., 'basicInfo.userName', '+basicInfo.userName', or '-basicInfo.userName')"
required: false
schema:
type: string
example: "basicInfo.userName"
responses:
'200':
description: Successful response with paginated users
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/UserPage'
'400':
description: Bad Request - Invalid query parameters or filter syntax
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidSort:
summary: Invalid sort parameter
value:
status: 400
title: "Validation error"
errors:
- code: "VALIDATION_ERROR"
field: "sort"
message: "Invalid sort parameter"
invalidFilter:
summary: Invalid filter syntax
value:
status: 400
title: "Validation error"
errors:
- code: "VALIDATION_ERROR"
field: "filter"
message: "Invalid filter syntax"
conflictingParameters:
summary: Conflicting query parameters
value:
status: 400
title: "Conflicting query parameters"
errors:
- code: "CONFLICTING_QUERY_PARAMETER"
message: "Cannot use scrollId with other first-page query parameters"
'503':
description: Service Unavailable - Service unavailable due to connectivity or network issues
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 503
title: "Service unavailable"
errors:
- code: "SERVICE_UNAVAILABLE"
message: "Service unavailable"
'500':
description: Internal Server Error - Unexpected error occurred
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 500
title: "Internal Server Error"
errors:
- code: "UNKNOWN"
message: "An unexpected error occurred"
post:
operationId: createUser
summary: Create user
description: |
Create a new user.
This operation is asynchronous and returns an Operation object to track progress.
tags:
- Users
parameters:
- name: X-Request-Id
in: header
description: Optional request identifier for tracking
required: false
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/User'
responses:
'202':
description: User creation operation initiated successfully
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/Operation'
'400':
description: Bad Request - Validation errors
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
validationError:
summary: Field validation errors
value:
status: 400
title: "Validation error"
errors:
- code: "VALIDATION_ERROR"
field: "basicInfo.userName"
message: "must not be blank"
- code: "VALIDATION_ERROR"
field: "basicInfo.primaryEmail"
message: "must be a well-formed email address"
- code: "VALIDATION_ERROR"
field: "basicInfo.firstName"
message: "size must be between 2 and 128"
duplicateUserName:
summary: Duplicate userName
value:
status: 400
title: "Validation error"
errors:
- code: "VALIDATION_ERROR"
message: "userName already in use"
invalidSite:
summary: Invalid site
value:
status: 400
title: "Validation error"
errors:
- code: "VALIDATION_ERROR"
field: "basicInfo.site.id"
message: "Either site id or name must be provided"
'403':
description: Forbidden - Customer ID mismatch
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 403
title: "Forbidden"
detail: "CustomerId mismatch: 0012J00042NkZQIQA3 vs 0012J00042NkZQIQA4"
errors:
- code: "FORBIDDEN"
message: "CustomerId mismatch: 0012J00042NkZQIQA3 vs 0012J00042NkZQIQA4"
'408':
description: Request Timeout - Downstream service timeout
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 408
title: "Request Timeout"
errors:
- code: "REQUEST_TIMEOUT"
message: "Request to downstream service timed out"
'503':
description: Service Unavailable - Service unavailable due to connectivity or network issues
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 503
title: "Service unavailable"
errors:
- code: "SERVICE_UNAVAILABLE"
message: "Service unavailable"
'429':
description: Too Many Requests - Rate limit exceeded
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 429
title: "Too Many Requests"
errors:
- code: "TOO_MANY_REQUESTS"
message: "Rate limit exceeded, please try again later"
'500':
description: Internal Server Error - Unexpected error occurred
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 500
title: "Internal Server Error"
errors:
- code: "UNKNOWN"
message: "An unexpected error occurred"
/users/{userId}:
get:
operationId: getUser
summary: Get user by ID
description: Retrieve a specific user by their ID
tags:
- Users
parameters:
- name: X-Request-Id
in: header
description: Optional request identifier for tracking
required: false
schema:
type: string
format: uuid
- name: userId
in: path
description: User identifier
required: true
schema:
type: string
example: "hvOB1l3zDCaDAwp9tNLzZA"
responses:
'200':
description: User retrieved successfully
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/User'
'404':
description: User not found
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 404
title: "Not Found"
errors:
- code: "NOT_FOUND"
message: "Resource not found"
'503':
description: Service Unavailable - Service unavailable due to connectivity or network issues
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 503
title: "Service unavailable"
errors:
- code: "SERVICE_UNAVAILABLE"
message: "Service unavailable"
'500':
description: Internal Server Error - Unexpected error occurred
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 500
title: "Internal Server Error"
errors:
- code: "UNKNOWN"
message: "An unexpected error occurred"
put:
operationId: updateUser
summary: Update user
description: |
Update an existing user by their ID.
This operation is asynchronous and returns an Operation object to track progress.
tags:
- Users
parameters:
- name: X-Request-Id
in: header
description: Optional request identifier for tracking
required: false
schema:
type: string
format: uuid
- name: userId
in: path
description: User identifier
required: true
schema:
type: string
example: "hvOB1l3zDCaDAwp9tNLzZA"
requestBody:
required: true
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/User'
responses:
'202':
description: User update operation initiated successfully
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/Operation'
'400':
description: Bad Request - Validation errors
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
validationError:
summary: Field validation errors
value:
status: 400
title: "Validation error"
errors:
- code: "VALIDATION_ERROR"
field: "basicInfo.userName"
message: "must not be blank"
mismatchedUserId:
summary: Mismatched userId in payload
value:
status: 400
title: "Mismatched userId in url vs payload"
detail: "Mismatched userId in url vs payload: hvOB1l3zDCaDAwp9tNLzZA vs anotherUserId"
errors:
- code: "VALIDATION_ERROR"
field: "basicInfo.userId"
message: "Mismatched userId in url vs payload: hvOB1l3zDCaDAwp9tNLzZA vs anotherUserId"
duplicateUserName:
summary: Duplicate userName
value:
status: 400
title: "Validation error"
errors:
- code: "VALIDATION_ERROR"
message: "userName already in use"
'403':
description: Forbidden - Customer ID mismatch
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 403
title: "Forbidden"
detail: "CustomerId mismatch: 0012J00042NkZQIQA3 vs 0012J00042NkZQIQA4"
errors:
- code: "FORBIDDEN"
message: "CustomerId mismatch: 0012J00042NkZQIQA3 vs 0012J00042NkZQIQA4"
'404':
description: User not found
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 404
title: "Not Found"
errors:
- code: "NOT_FOUND"
field: "basicInfo.userId"
message: "User not found"
'408':
description: Request Timeout - Downstream service timeout
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 408
title: "Request Timeout"
errors:
- code: "REQUEST_TIMEOUT"
message: "Request to downstream service timed out"
'503':
description: Service Unavailable - Service unavailable due to connectivity or network issues
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 503
title: "Service unavailable"
errors:
- code: "SERVICE_UNAVAILABLE"
message: "Service unavailable"
'429':
description: Too Many Requests - Rate limit exceeded
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 429
title: "Too Many Requests"
errors:
- code: "TOO_MANY_REQUESTS"
message: "Rate limit exceeded, please try again later"
'500':
description: Internal Server Error - Unexpected error occurred
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 500
title: "Internal Server Error"
errors:
- code: "UNKNOWN"
message: "An unexpected error occurred"
delete:
operationId: deleteUser
summary: Delete user
description: |
Delete a specific user by their ID.
This operation is asynchronous and returns an Operation object to track progress.
tags:
- Users
parameters:
- name: X-Request-Id
in: header
description: Optional request identifier for tracking
required: false
schema:
type: string
format: uuid
- name: userId
in: path
description: User identifier
required: true
schema:
type: string
example: "hvOB1l3zDCaDAwp9tNLzZA"
responses:
'202':
description: User deletion operation initiated successfully
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/Operation'
'503':
description: Service Unavailable - Service unavailable due to connectivity or network issues
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 503
title: "Service unavailable"
errors:
- code: "SERVICE_UNAVAILABLE"
message: "Service unavailable"
'500':
description: Internal Server Error - Unexpected error occurred
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.users.v1+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 500
title: "Internal Server Error"
errors:
- code: "UNKNOWN"
message: "An unexpected error occurred"
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
schemas:
User:
type: object
properties:
basicInfo:
$ref: '#/components/schemas/BasicInfo'
directoryInfo:
$ref: '#/components/schemas/DirectoryInfo'
serviceInfo:
$ref: '#/components/schemas/ServiceInfo'
assignmentInfo:
$ref: '#/components/schemas/AssignmentInfo'
required:
- basicInfo
BasicInfo:
type: object
properties:
userId:
type: string
description: "Unique ID of the user"
example: "hvOB1l3zDCaDAwp9tNLzZA"
readOnly: true
nullable: true
customerId:
type: string
description: "Unique ID of the customer account"
example: "0012J00042NkZQIQA3"
nullable: true
createdTime:
type: string
format: date-time
description: "Date/time the user was created"
example: "2025-01-01T01:02:03Z"
readOnly: true
nullable: true
lastUpdatedTime:
type: string
format: date-time
description: "Date/time the user was last updated"
example: "2025-01-02T01:02:03Z"
readOnly: true
nullable: true
scimProvider:
type: string
description: "The Identity Provider linked to the user for SCIM provisioning"
example: "okta"
nullable: true
userName:
type: string
description: "Unique username used for logging into services"
example: "jane.doe@corp.com"
minLength: 3
maxLength: 70
pattern: '^[A-Za-z0-9.@\-_/]+$'
firstName:
type: string
description: "User first or given name"
example: "Jane"
minLength: 2
maxLength: 128
pattern: "^[A-Za-z0-9.,\\-_()' ]+$"
lastName:
type: string
description: "User surname or family name"
example: "Doe"
minLength: 2
maxLength: 30
pattern: "^[A-Za-z0-9.,\\-_()' ]+$"
status:
type: string
enum: [ACTIVE, INACTIVE]
description: "User status controls whether user can log in or use services"
example: "ACTIVE"
nullable: true
locale:
type: string
enum: [da-DK, de-DE, en-AU, en-GB, en-US, es-ES, fi-FI, fr-BE, fr-CA, fr-CH, fr-FR, it-IT, ja-JP, nl-BE, nl-NL, no-NO, pl-PL, pt-BR, pt-PT, sv-SE, zh-CN]
description: "Language for voice prompts, email notifications and device display"
example: "en-US"
nullable: true
timezone:
type: string
description: "Time zone used for downloading call recordings and viewing call queues"
example: "Europe/London"
nullable: true
primaryEmail:
type: string
description: "Email used for password setup and onboarding information"
example: "jane.doe@corp.com"
format: email
minLength: 5
maxLength: 128
ssoProvider:
type: string
description: "The Identity provider linked to the user for Single Sign-On"
example: "Okta"
nullable: true
ssoFederationId:
type: string
description: "The Identity Provider's ID for the user for Single Sign-On"
example: "jdoe@corp.com"
nullable: true
site:
$ref: '#/components/schemas/Site'
required:
- userName
- firstName
- lastName
- primaryEmail
Site:
type: object
properties:
id:
type: string
description: "Unique ID of the users's site"
example: "SAH3U8guQaK4WQhpDZi0rQ"
nullable: true
name:
type: string
description: "The name of the user's site"
example: "Headquarters"
nullable: true
pbxName:
type: string
description: "Unique code name of the PBX on which the user's site resides"
example: "corpco01"
nullable: true
DirectoryInfo:
type: object
properties:
department:
type: string
description: "Free text field to store the user's department"
example: "Sales"
minLength: 1
maxLength: 100
pattern: "^[A-Za-z0-9.,&@*+\\-#\\\\/()'– ]+$"
nullable: true
directoryScope:
type: string
enum: [CUSTOMER, PBX, SITE]
description: "Controls which other users this user can see in any directory features"
example: "PBX"
nullable: true
displayInDirectory:
type: boolean
description: "Controls whether this user is visible to others in any directory features"
example: true
nullable: true
jobTitle:
type: string
description: "Free text field to store the user's job title"
example: "Account Executive"
minLength: 1
maxLength: 254
nullable: true
personalPhoneNumbers:
type: array
description: "List of personal contact numbers from other providers to appear in any directory features"
items:
$ref: '#/components/schemas/ContactPhoneNumber'
nullable: true
ServiceInfo:
type: object
properties:
licenses:
type: array
description: "List of licenses (aka subscriptions) assigned to the user"
items:
$ref: '#/components/schemas/License'
nullable: true
extensions:
type: array
description: "List of the voice extensions belonging to the user"
items:
$ref: '#/components/schemas/Extension'
nullable: true
License:
type: object
properties:
id:
type: string
description: "Unique ID of the license"
example: "02KB7TGTYAG4Rq4jDUhwyQ"
nullable: true
name:
type: string
description: "Name for the type of license"
example: "UC Call Recordings Cold Storage-VOSVC0504-01-GB"
nullable: true
country:
type: string
description: "ISO:3166-2 country code of the license"
example: "US"
nullable: true
AssignmentInfo:
type: object
properties:
profilePolicy:
$ref: '#/components/schemas/ProfilePolicy'
ringGroups:
type: array
description: "List of ring groups the user is a member of"
items:
$ref: '#/components/schemas/RingGroup'
nullable: true
ucCallQueues:
type: array
items:
$ref: '#/components/schemas/UCCallQueue'
nullable: true
userGroups:
type: array
items:
$ref: '#/components/schemas/UserGroup'
nullable: true
ProfilePolicy:
type: object
properties:
name:
type: string
description: "Name of the profile policy assigned ot the user"
example: "8x8 Master User Template"
nullable: true
# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/8x8/refs/heads/main/openapi/8x8-administration-user-api-v1.yaml