8x8 Ring Groups API

openapi: 3.2.0
info:
  title: 8x8 Administration - Ring Group Management Ring Groups 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: []
tags:
- name: RingGroups
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:
  schemas:
    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
    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
          - 'null'
          description: RSQL filter expression applied to the search
          example: name==*Reception*
        sort:
          type:
          - string
          - 'null'
          description: Sort expression applied to the search
          example: -name
        nextScrollId:
          type:
          - string
          - 'null'
          description: Scroll ID for fetching the next page. Null if no more pages available.
    Error:
      type: object
      properties:
        field:
          type:
          - string
          - 'null'
          description: Field name that caused the error (for validation errors)
          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
          - 'null'
          description: Human-readable error message
          example: must not be blank
    Link:
      type: object
      properties:
        href:
          type: string
          description: URI reference for the linked resource
          example: /ring-groups/aeP9pOoDRbq8_KKiwtsXhQ
    Site:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Unique ID of the ring group's site
          example: SAH3U8guQaK4WQhpDZi0rQ
        name:
          type:
          - string
          - 'null'
          description: The name of the ring group's site
          example: Headquarters
        pbxId:
          type:
          - string
          - 'null'
          description: Unique ID of the PBX on which the ring group's site resides
          example: vhaxJhIvR6Ge9kweXeGfBA
        pbxName:
          type:
          - string
          - 'null'
          description: Unique code name of the PBX on which the ring group's site resides
          example: corpco01
    PhoneNumber:
      type: object
      properties:
        origin:
          type:
          - string
          - 'null'
          description: Origin or source system of the phone number
          example: CLAIMED
        phoneNumber:
          type:
          - string
          - 'null'
          description: E.164-formatted phone number assigned to the ring group
          example: '+14085551234'
        portingNumber:
          $ref: '#/components/schemas/PortingNumber'
        primary:
          type:
          - boolean
          - 'null'
          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
    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+
        logged

# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/8x8/refs/heads/main/openapi/8x8-ringgroups-api-openapi.yml