8x8 Administration - Ring Group Management API
8x8 Administration Ring Group Management API for creating and managing ring groups and their members.
OpenAPI Specification
openapi: 3.0.0
info:
title: 8x8 Administration - Ring Group Management API
version: "1.0"
description: |
Ring group management API providing endpoints to create, retrieve, list, update, and delete ring groups.
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.ringgroups.v1+json # on POST/PUT (request payload)
Accept: application/vnd.ringgroups.v1+json # on GET (response payload)
```
## Base URL
`https://api.8x8.com/admin-provisioning`
## Endpoints
| Endpoint | Method | Purpose | Async? |
|----------|--------|---------|--------|
| `/ring-groups` | GET | Retrieve paginated list of ring groups with filtering | No |
| `/ring-groups` | POST | Create a new ring group | Yes |
| `/ring-groups/{ringGroupId}` | GET | Retrieve a specific ring group's details | No |
| `/ring-groups/{ringGroupId}` | PUT | Update an existing ring group | Yes |
| `/ring-groups/{ringGroupId}` | DELETE | Remove a ring group | Yes |
| `/ring-groups/{ringGroupId}/update-members` | POST | Atomically add, update, or remove ring group members | Yes |
## OpenAPI Specification
Download the complete OpenAPI specification: [ringgroup-api-v1.yaml](/administration/ringgroup-api-v1.yaml)
servers:
- url: https://api.8x8.com/admin-provisioning
description: Production server
security:
- ApiKeyAuth: []
paths:
/ring-groups:
get:
operationId: listRingGroups
summary: List ring groups
description: |
List ring groups with optional filtering, sorting, and pagination.
Uses infinite scroll pagination with scrollId for efficient navigation.
tags:
- RingGroups
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, max 1000)
required: false
schema:
type: integer
minimum: 1
maximum: 1000
default: 100
- name: filter
in: query
description: "RSQL filter expression for filtering results. Supports operators: == (equals), != (not equals), > (greater than), < (less than), >= (greater or equal), <= (less or equal). Use ; for AND, , for OR. Wildcard matching with * is supported for string fields only. Example: name==*Reception*"
required: false
schema:
type: string
maxLength: 2000
- name: sort
in: query
description: "Sort expression. Use '+' prefix or no prefix for ascending order, '-' prefix for descending order (e.g., 'name', '+name', or '-name')"
required: false
schema:
type: string
maxLength: 200
- name: scrollId
in: query
description: Scroll ID for fetching the next page of results. Obtained from the previous page response.
required: false
schema:
type: string
responses:
'200':
description: Successful response
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.ringgroups.v1+json:
schema:
$ref: '#/components/schemas/RingGroupPage'
'400':
description: Bad Request - Invalid query parameters or validation errors
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 400
title: "Validation error"
errors:
- code: "VALIDATION_ERROR"
field: "filter"
message: "Invalid filter syntax"
'403':
description: Forbidden - Customer ID mismatch or insufficient permissions
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 403
title: "Forbidden"
errors:
- code: "FORBIDDEN"
message: "Access denied to this resource"
'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/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/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 500
title: "Internal Server Error"
errors:
- code: "UNKNOWN"
message: "An unexpected error occurred"
post:
summary: Create a ring group
description: Creates a new ring group asynchronously. Returns an operation object to track the creation progress.
operationId: createRingGroup
tags:
- RingGroups
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.ringgroups.v1+json:
schema:
$ref: '#/components/schemas/RingGroup'
responses:
'202':
description: Accepted - Ring group creation initiated
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.ringgroups.v1+json:
schema:
$ref: '#/components/schemas/Operation'
'400':
description: Bad Request - Validation errors or invalid request
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 400
title: "Failed to create ring group"
errors:
- code: "VALIDATION_ERROR"
field: "name"
message: "must not be blank"
'403':
description: Forbidden - Customer ID mismatch or insufficient permissions
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 403
title: "Forbidden"
errors:
- code: "FORBIDDEN"
message: "Access denied to this resource"
'404':
description: Not Found - Related resource not found
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 404
title: "Failed to create ring group"
errors:
- code: "NOT_FOUND"
message: "Site for ring group 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/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 503
title: "Failed to create ring group"
errors:
- code: "UNKNOWN"
message: "Unable to complete request due to downstream service failure"
'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/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 500
title: "Internal Server Error"
errors:
- code: "UNKNOWN"
message: "An unexpected error occurred"
/ring-groups/{ringGroupId}:
get:
summary: Get ring group by ID
description: Retrieves a specific ring group by its unique identifier.
operationId: getRingGroup
tags:
- RingGroups
parameters:
- name: X-Request-Id
in: header
description: Optional request identifier for tracking
required: false
schema:
type: string
format: uuid
- name: ringGroupId
in: path
description: Unique identifier of the ring group
required: true
schema:
type: string
responses:
'200':
description: Successful response
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.ringgroups.v1+json:
schema:
$ref: '#/components/schemas/RingGroup'
'403':
description: Forbidden - Customer ID mismatch or insufficient permissions
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 403
title: "Forbidden"
errors:
- code: "FORBIDDEN"
message: "Access denied to this resource"
'404':
description: Not Found - Ring group does not exist
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 404
title: "Not Found"
errors:
- code: "NOT_FOUND"
message: "Ring group not found"
'503':
description: Service Unavailable - Service unavailable due to connectivity or network issues or partial data
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/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/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 500
title: "Internal Server Error"
errors:
- code: "UNKNOWN"
message: "An unexpected error occurred"
put:
summary: Update a ring group
description: Updates an existing ring group asynchronously. Returns an operation object to track the update progress.
operationId: updateRingGroup
tags:
- RingGroups
parameters:
- name: X-Request-Id
in: header
description: Optional request identifier for tracking
required: false
schema:
type: string
format: uuid
- name: ringGroupId
in: path
description: Unique identifier of the ring group to update
required: true
schema:
type: string
requestBody:
required: true
content:
application/vnd.ringgroups.v1+json:
schema:
$ref: '#/components/schemas/RingGroup'
responses:
'202':
description: Accepted - Ring group update initiated
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.ringgroups.v1+json:
schema:
$ref: '#/components/schemas/Operation'
'400':
description: Bad Request - Validation errors or invalid request
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 400
title: "Failed to update ring group"
errors:
- code: "VALIDATION_ERROR"
field: "name"
message: "must not be blank"
'403':
description: Forbidden - Customer ID mismatch or insufficient permissions
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 403
title: "Forbidden"
errors:
- code: "FORBIDDEN"
message: "Access denied to this resource"
'404':
description: Not Found - Ring group does not exist
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 404
title: "Failed to update ring group"
errors:
- code: "NOT_FOUND"
message: "Ring group 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/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/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 500
title: "Internal Server Error"
errors:
- code: "UNKNOWN"
message: "An unexpected error occurred"
delete:
summary: Delete a ring group
description: Deletes an existing ring group asynchronously. Returns an operation object to track the deletion progress.
operationId: deleteRingGroup
tags:
- RingGroups
parameters:
- name: X-Request-Id
in: header
description: Optional request identifier for tracking
required: false
schema:
type: string
format: uuid
- name: ringGroupId
in: path
description: Unique identifier of the ring group to delete
required: true
schema:
type: string
responses:
'202':
description: Accepted - Ring group deletion initiated or already completed
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.ringgroups.v1+json:
schema:
$ref: '#/components/schemas/Operation'
'403':
description: Forbidden - Customer ID mismatch or insufficient permissions
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 403
title: "Forbidden"
errors:
- code: "FORBIDDEN"
message: "Access denied to this resource"
'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/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/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 500
title: "Internal Server Error"
errors:
- code: "UNKNOWN"
message: "An unexpected error occurred"
/ring-groups/{ringGroupId}/update-members:
post:
summary: Update ring group members
description: |
Atomically applies an add/update/remove delta to a ring group's member list.
Returns an operation object to track progress; poll the operation to completion.
Only the members supplied are changed. At least one of `add`, `update`, or `remove`
must be non-empty, each accepts up to 200 members, and an `extensionId` or
`extensionNumber` must not appear in more than one array within a single request.
operationId: updateRingGroupMembers
tags:
- RingGroups
parameters:
- name: X-Request-Id
in: header
description: Optional request identifier for tracking
required: false
schema:
type: string
format: uuid
- name: ringGroupId
in: path
description: Unique identifier of the ring group whose members are being updated
required: true
schema:
type: string
requestBody:
required: true
content:
application/vnd.ringgroups.update-members.v1+json:
schema:
$ref: '#/components/schemas/RingGroupMembershipModifications'
responses:
'202':
description: Accepted - Member update initiated
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/vnd.ringgroups.v1+json:
schema:
$ref: '#/components/schemas/Operation'
'400':
description: Bad Request - Validation errors or invalid request
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 400
title: "Invalid update-members request"
errors:
- code: "BAD_REQUEST"
message: "At least one of 'add', 'update', or 'remove' must be non-empty"
'403':
description: Forbidden - Customer ID mismatch or insufficient permissions
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 403
title: "Forbidden"
errors:
- code: "FORBIDDEN"
message: "Access denied to this resource"
'404':
description: Not Found - Ring group does not exist
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 404
title: "Failed to update ring group members"
errors:
- code: "NOT_FOUND"
message: "Ring group not found"
'409':
description: Conflict - Concurrent modification or downstream conflict detected while applying the delta
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 409
title: "Conflicting update-members request"
errors:
- code: "CONFLICT"
message: "The ring group was modified concurrently; retry with the current member list"
'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/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 503
title: "Failed to update ring group members"
errors:
- code: "UNKNOWN"
message: "Unable to complete request due to downstream service failure"
'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/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
description: API Key authentication for accessing the 8x8 Admin Provisioning API
schemas:
RingGroupMembershipModifications:
type: object
description: |
Atomic delta applied to a ring group's member list. All three arrays are optional;
at least one must be non-empty. An extensionId or extensionNumber cannot appear in
more than one array within the same request. Each item must carry either extensionId
or extensionNumber as identifier.
properties:
add:
type: array
description: "List of new members to be added to the ring group"
maxItems: 200
items:
$ref: '#/components/schemas/MemberAdd'
update:
type: array
description: "List of existing members to be modified in the ring group"
maxItems: 200
items:
$ref: '#/components/schemas/MemberUpdate'
remove:
type: array
description: "List of existing members to be removed from the ring group"
maxItems: 200
items:
$ref: '#/components/schemas/MemberRemove'
MemberAdd:
type: object
properties:
extensionId:
type: string
description: "Unique ID of the member user's extension. Must provide either extensionNumber or extensionId"
example: "7yKxifh1SLuDcqQO4501jA"
extensionNumber:
type: string
description: "The internal extension number of the member user. Must provide either extensionNumber or extensionId"
example: "1001"
pattern: '\d+'
loggedIn:
type: boolean
description: "Indicates whether the member is currently logged in"
example: true
sequenceNumber:
type: integer
description: "Determines the order that members are alerted in for ROUND_ROBIN and SEQUENTIAL ring patterns. If omitted on an add, the member is appended to the end of the sequence"
example: 1
minimum: 1
maximum: 214748367
voicemailAccessEnabled:
type: boolean
description: "Controls whether the member can access the ring group's voicemail"
example: false
MemberUpdate:
type: object
properties:
extensionId:
type: string
description: "Unique ID of the member user's extension. Must provide either extensionNumber or extensionId"
example: "7yKxifh1SLuDcqQO4501jA"
extensionNumber:
type: string
description: "The internal extension number of the member user. Must provide either extensionNumber or extensionId"
example: "1001"
pattern: '\d+'
loggedIn:
type: boolean
description: "Indicates whether the member is currently logged in. If omitted the current value remains"
example: true
sequenceNumber:
type: integer
description: "Determines the order that members are alerted in for ROUND_ROBIN and SEQUENTIAL ring patterns"
example: 1
minimum: 1
maximum: 214748367
voicemailAccessEnabled:
type: boolean
description: "Controls whether the member can access the ring group's voicemail"
example: false
MemberRemove:
type: object
properties:
extensionId:
type: string
description: "Unique ID of the member user's extension. Must provide either extensionNumber or extensionId"
example: "7yKxifh1SLuDcqQO4501jA"
extensionNumber:
type: string
description: "The internal extension number of the member user. Must provide either extensionNumber or extensionId"
example: "1001"
pattern: '\d+'
RingGroup:
type: object
properties:
id:
type: string
description: "Unique ID of the ring group"
example: "aeP9pOoDRbq8_KKiwtsXhQ"
readOnly: true
nullable: true
allowLogInLogOut:
type: boolean
description: "Controls whether members are permitted to log in and out of the ring group. If false members are logged in by default"
example: true
nullable: true
callerIdEnabled:
type: boolean
description: "Controls whether members are permitted to use the ring group's phone number as their external caller ID number"
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/8x8/refs/heads/main/openapi/8x8-administration-ringgroup-api-v1.yaml