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" example: true nullable: true customerId: type: string description: "Unique ID of the customer account" example: "0012J00042NkZQIQA3" nullable: true extensionNumber: type: string description: "Internal short extension number assigned to the ring group" example: "1001" nullable: true forwardingRules: type: array description: "List of forwarding rules for the ring group. Ring groups support only basic type rules" items: $ref: '#/components/schemas/ForwardingRule' nullable: true inboundCallerIdFormat: type: string enum: [RGNAME_CALLERNUMBER, CALLERNAME_CALLERNUMBER, RGNAME_RGEXTENSION, RGNAME_DIALEDNUMBER] description: "Determines what caller ID information is shown when inbound calls are received through this ring group" example: "RGNAME_CALLERNUMBER" members: type: array description: "List of members in the ring group" items: $ref: '#/components/schemas/Member' nullable: true name: type: string description: "Ring group name" example: "Main Reception" minLength: 2 maxLength: 64 notifyIfBusy: type: boolean description: "Controls whether the ring group should alert members even if they are on another call" example: true nullable: true numberOfCycles: type: integer description: "The number of times the system cycles through all queue members before the call forwarding rule is applied. Applicable only to ROUND_ROBIN and SEQUENTIAL ring patterns." example: 1 nullable: true phoneNumbers: type: array description: "List of phone numbers assigned to the ring group" items: $ref: '#/components/schemas/PhoneNumber' nullable: true ringPattern: type: string enum: [ROUND_ROBIN, SEQUENTIAL, SIMULTANEOUS] description: "Determines how the ring group attempts to alert members. ROUND_ROBIN starts with the member who was alerted last on the previous call to ensure even distribution of calls. SEQUENTIAL starts with the same member on each new call. SIMULTANEOUS alerts all members at the same time" example: "ROUND_ROBIN" ringTimeout: type: integer description: "Duration, in seconds, that each queue member's device rings before the system advances to the next member or triggers the call forwarding rule." example: 15 site: $ref: '#/components/schemas/Site' voicemailSettings: $ref: '#/components/schemas/VoicemailSettings' required: - inboundCallerIdFormat - name - ringPattern - ringTimeout ForwardingRule: type: object properties: condition: type: string enum: [UNCONDITIONALLY, BUSY, NO_ANSWER, OUTAGE] description: "The condition in which this rule should be applied" example: "UNCONDITIONALLY" enabled: type: boolean description: "Controls whether the rule is active or not" example: true destinations: type: array description: "List of forwarding destinations. BASIC type rules can only have on destination" items: $ref: '#/components/schemas/ForwardingRuleDestination' nullable: true required: - condition - enabled ForwardingRuleDestination: type: object properties: destination: type: string description: "Number the forwarding rule should forward the call to. Can be either an internal extension number whcy type = EXTENSION_NUMBER or an external number in E.164 format with leading + when type = EXTERNAL_NUMBER" example: "1001, +14085551234" nullable: true type: type: string enum: [AUTO_ATTENDANT, EXTENSION_NUMBER, EXTERNAL_NUMBER, VOICEMAIL, DROP_CALL] description: "Determines the type of destination" example: "EXTENSION_NUMBER" nullable: true Member: type: object properties: extensionId: type: string description: "Unique ID of the member user's extension" example: "7yKxifh1SLuDcqQO4501jA" nullable: true extensionNumber: type: string description: "The internal extension number of the member user" example: "1001" nullable: true loggedIn: type: boolean description: "Indicates whether the member is currently logged in" example: true nullable: true firstName: type: string description: "The first name of the member user" example: "Jane" nullable: true lastName: type: string description: "The last name of the member user" example: "Doe" nullable: true sequenceNumber: type: integer description: "Determines the order that members are alerted in for ROUND_ROBIN and SEQUENTIAL ring patterns" example: 1 nullable: true userId: type: string description: "Unique ID of the member user" example: "hvOB1l3zDCaDAwp9tNLzZA" nullable: true voicemailAccessEnabled: type: boolean description: "Controls whether the member can access the ring group's voicemail" example: false nullable: true PhoneNumber: type: object properties: origin: type: string description: "Origin or source system of the phone number" example: "CLAIMED" nullable: true phoneNumber: type: string description: "E.164-formatted phone number assigned to the ring group" example: "+14085551234" nullable: true portingNumber: $ref: '#/components/schemas/PortingNumber' primary: type: boolean description: "Indicates whether the number is the primary phone number for the ring group. The primary number will the originator of any calls forwarded to external numbers" example: true nullable: true PortingNumber: type: object properties: phoneNumber: type: string description: "The number which will replace this ring group phone number when the porting process completes" example: "+14085556789" nullable: true Site: type: object properties: id: type: string description: "Unique ID of the ring group's site" example: "SAH3U8guQaK4WQhpDZi0rQ" nullable: true name: type: string description: "The name of the ring group's site" example: "Headquarters" nullable: true pbxId: type: string description: "Unique ID of the PBX on which the ring group's site resides" example: "vhaxJhIvR6Ge9kweXeGfBA" nullable: true pbxName: type: string description: "Unique code name of the PBX on which the ring group's site resides" example: "corpco01" nullable: true VoicemailSettings: type: object properties: accessPin: type: string description: "The PIN that protects access to the ring group's voicemail. For security reasons can be set/reset but not retrieved" minLength: 6 maxLength: 15 example: "779643634" nullable: true notificationEmail: type: string description: "Email address to send voicemail notifications to depending on notificationType setting. Must be provided if notificationType is anything other than DISABLE" example: "jane.doe@corp.com" nullable: true notificationAction: type: string enum: [ATTACH_DELETE_ORIG, DISABLE, ATTACH_ONLY, NOTIFY_ONLY] description: "Determines whether and how voicemail notifications are sent." example: "NOTIFY_ONLY" nullable: true RingGroupPage: type: object properties: data: type: array description: List of ring groups in the current page items: $ref: '#/components/schemas/RingGroup' pagination: $ref: '#/components/schemas/Pagination' _links: $ref: '#/components/schemas/PaginationLinks' Pagination: type: object properties: pageSize: type: integer description: Number of items in the current page example: 100 pageNumber: type: integer description: Current page number (zero-indexed) example: 0 hasMore: type: boolean description: Indicates whether more pages are available example: true filter: type: string description: RSQL filter expression applied to the search nullable: true example: "name==*Reception*" sort: type: string description: Sort expression applied to the search nullable: true example: "-name" nextScrollId: type: string description: Scroll ID for fetching the next page. Null if no more pages available. nullable: true PaginationLinks: type: object properties: self: $ref: '#/components/schemas/Link' next: $ref: '#/components/schemas/Link' Link: type: object properties: href: type: string description: URI reference for the linked resource example: "/ring-groups/aeP9pOoDRbq8_KKiwtsXhQ" ErrorResponse: type: object properties: status: type: integer description: HTTP status code example: 400 instance: type: string description: URI reference that identifies the specific occurrence of the problem nullable: true example: "/ring-groups" time: type: string format: date-time description: Timestamp when the error occurred nullable: true example: "2024-12-18T10:30:00Z" title: type: string description: Short, human-readable summary of the problem nullable: true example: "Validation error" detail: type: string description: Human-readable explanation specific to this occurrence of the problem nullable: true example: "The request contains invalid parameters" errors: type: array description: List of specific error details items: $ref: '#/components/schemas/Error' Error: type: object properties: field: type: string description: Field name that caused the error (for validation errors) nullable: true example: "name" code: type: string description: Machine-readable error code enum: - UNKNOWN - VALIDATION_ERROR - FORBIDDEN - CONFLICTING_QUERY_PARAMETER - SERVICE_UNAVAILABLE - NOT_FOUND - BAD_REQUEST - REQUEST_TIMEOUT - TOO_MANY_REQUESTS - CONFLICT example: VALIDATION_ERROR message: type: string description: Human-readable error message nullable: true example: "must not be blank" Operation: type: object properties: operationId: type: string description: Unique identifier for the operation example: "op-123e4567-e89b-12d3-a456-426614174000" status: type: string description: Current status of the operation enum: - PENDING - IN_PROGRESS - COMPLETED - FAILED - UNKNOWN example: PENDING customerId: type: string description: Customer ID associated with the operation example: "0012J00042NkZQIQA3" resourceType: type: string description: Type of resource being operated on enum: - USER - RING_GROUP - SITE example: RING_GROUP resourceId: type: string description: Unique identifier of the resource (available after creation completes) nullable: true example: "aeP9pOoDRbq8_KKiwtsXhQ" operationType: type: string description: Type of operation being performed enum: - CREATE - UPDATE - DELETE example: CREATE createdTime: type: string format: date-time description: Timestamp when the operation was created example: "2024-12-18T10:30:00Z" completedTime: type: string format: date-time description: Timestamp when the operation completed (success or failure) nullable: true example: "2024-12-18T10:30:15Z" error: $ref: '#/components/schemas/ErrorResponse' _links: $ref: '#/components/schemas/OperationLinks' OperationLinks: type: object properties: self: $ref: '#/components/schemas/Link' resource: $ref: '#/components/schemas/Link'