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'