openapi: 3.0.0
info:
  title: 8x8 Administration - User Management API
  version: "1.0"
  description: |
    User management API providing endpoints to create, retrieve, list, update, and delete users.

    The current version of the API is v1.0.

    ## Authentication

    All requests to this API require authentication using an API key. Include your API key in the request header:

    ```
    x-api-key: YOUR_API_KEY
    ```

    ## Versioning

    The API version is specified through a vendor-specific media type. Send it in the `Content-Type` header for requests that carry a payload (such as `POST` and `PUT`) and in the `Accept` header for requests that return a payload (`GET`, and asynchronous `DELETE` operations that return an operation resource).

    ```
    Content-Type: application/vnd.users.v1+json   # on POST/PUT (request payload)
    Accept: application/vnd.users.v1+json          # on GET (response payload)
    ```

    ## Base URL

    `https://api.8x8.com/admin-provisioning`

    ## Endpoints

    | Endpoint | Method | Purpose | Async? |
    |----------|--------|---------|--------|
    | `/users` | GET | Retrieve paginated list of users with filtering | No |
    | `/users` | POST | Create a new user account | Yes |
    | `/users/{userId}` | GET | Retrieve a specific user's details | No |
    | `/users/{userId}` | PUT | Update an existing user account | Yes |
    | `/users/{userId}` | DELETE | Remove a user account | Yes |

    ## OpenAPI Specification

    Download the complete OpenAPI specification: [user-api-v1.yaml](/administration/user-api-v1.yaml)
servers:
  - url: https://api.8x8.com/admin-provisioning
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /users:
    get:
      operationId: listUsers
      summary: List users
      description: |
        List users with optional filtering, sorting, and infinite scroll pagination.
        Uses scrollId-based pagination for efficient navigation through large datasets.
      tags:
        - Users
      parameters:
        - name: X-Request-Id
          in: header
          description: Optional request identifier for tracking
          required: false
          schema:
            type: string
            format: uuid
        - name: pageSize
          in: query
          description: 'Number of items per page (default: 100)'
          required: false
          schema:
            type: integer
            example: 100
        - name: scrollId
          in: query
          description: 'Scroll identifier for retrieving the next page of results'
          required: false
          schema:
            type: string
        - name: filter
          in: query
          description: "RSQL filter expression (e.g., 'basicInfo.userName==jane.doe@corp.com', 'basicInfo.status==ACTIVE')"
          required: false
          schema:
            type: string
            example: "basicInfo.status==ACTIVE"
        - name: sort
          in: query
          description: "Sort expression. Use '+' prefix or no prefix for ascending order, '-' prefix for descending order (e.g., 'basicInfo.userName', '+basicInfo.userName', or '-basicInfo.userName')"
          required: false
          schema:
            type: string
            example: "basicInfo.userName"
      responses:
        '200':
          description: Successful response with paginated users
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/UserPage'
        '400':
          description: Bad Request - Invalid query parameters or filter syntax
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidSort:
                  summary: Invalid sort parameter
                  value:
                    status: 400
                    title: "Validation error"
                    errors:
                      - code: "VALIDATION_ERROR"
                        field: "sort"
                        message: "Invalid sort parameter"
                invalidFilter:
                  summary: Invalid filter syntax
                  value:
                    status: 400
                    title: "Validation error"
                    errors:
                      - code: "VALIDATION_ERROR"
                        field: "filter"
                        message: "Invalid filter syntax"
                conflictingParameters:
                  summary: Conflicting query parameters
                  value:
                    status: 400
                    title: "Conflicting query parameters"
                    errors:
                      - code: "CONFLICTING_QUERY_PARAMETER"
                        message: "Cannot use scrollId with other first-page query parameters"
        '503':
          description: Service Unavailable - Service unavailable due to connectivity or network issues
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 503
                title: "Service unavailable"
                errors:
                  - code: "SERVICE_UNAVAILABLE"
                    message: "Service unavailable"
        '500':
          description: Internal Server Error - Unexpected error occurred
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                title: "Internal Server Error"
                errors:
                  - code: "UNKNOWN"
                    message: "An unexpected error occurred"
    post:
      operationId: createUser
      summary: Create user
      description: |
        Create a new user.
        This operation is asynchronous and returns an Operation object to track progress.
      tags:
        - Users
      parameters:
        - name: X-Request-Id
          in: header
          description: Optional request identifier for tracking
          required: false
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/vnd.users.v1+json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '202':
          description: User creation operation initiated successfully
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/Operation'
        '400':
          description: Bad Request - Validation errors
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validationError:
                  summary: Field validation errors
                  value:
                    status: 400
                    title: "Validation error"
                    errors:
                      - code: "VALIDATION_ERROR"
                        field: "basicInfo.userName"
                        message: "must not be blank"
                      - code: "VALIDATION_ERROR"
                        field: "basicInfo.primaryEmail"
                        message: "must be a well-formed email address"
                      - code: "VALIDATION_ERROR"
                        field: "basicInfo.firstName"
                        message: "size must be between 2 and 128"
                duplicateUserName:
                  summary: Duplicate userName
                  value:
                    status: 400
                    title: "Validation error"
                    errors:
                      - code: "VALIDATION_ERROR"
                        message: "userName already in use"
                invalidSite:
                  summary: Invalid site
                  value:
                    status: 400
                    title: "Validation error"
                    errors:
                      - code: "VALIDATION_ERROR"
                        field: "basicInfo.site.id"
                        message: "Either site id or name must be provided"
        '403':
          description: Forbidden - Customer ID mismatch
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 403
                title: "Forbidden"
                detail: "CustomerId mismatch: 0012J00042NkZQIQA3 vs 0012J00042NkZQIQA4"
                errors:
                  - code: "FORBIDDEN"
                    message: "CustomerId mismatch: 0012J00042NkZQIQA3 vs 0012J00042NkZQIQA4"
        '408':
          description: Request Timeout - Downstream service timeout
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 408
                title: "Request Timeout"
                errors:
                  - code: "REQUEST_TIMEOUT"
                    message: "Request to downstream service timed out"
        '503':
          description: Service Unavailable - Service unavailable due to connectivity or network issues
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 503
                title: "Service unavailable"
                errors:
                  - code: "SERVICE_UNAVAILABLE"
                    message: "Service unavailable"
        '429':
          description: Too Many Requests - Rate limit exceeded
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 429
                title: "Too Many Requests"
                errors:
                  - code: "TOO_MANY_REQUESTS"
                    message: "Rate limit exceeded, please try again later"
        '500':
          description: Internal Server Error - Unexpected error occurred
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                title: "Internal Server Error"
                errors:
                  - code: "UNKNOWN"
                    message: "An unexpected error occurred"
  /users/{userId}:
    get:
      operationId: getUser
      summary: Get user by ID
      description: Retrieve a specific user by their ID
      tags:
        - Users
      parameters:
        - name: X-Request-Id
          in: header
          description: Optional request identifier for tracking
          required: false
          schema:
            type: string
            format: uuid
        - name: userId
          in: path
          description: User identifier
          required: true
          schema:
            type: string
            example: "hvOB1l3zDCaDAwp9tNLzZA"
      responses:
        '200':
          description: User retrieved successfully
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 404
                title: "Not Found"
                errors:
                  - code: "NOT_FOUND"
                    message: "Resource not found"
        '503':
          description: Service Unavailable - Service unavailable due to connectivity or network issues
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 503
                title: "Service unavailable"
                errors:
                  - code: "SERVICE_UNAVAILABLE"
                    message: "Service unavailable"
        '500':
          description: Internal Server Error - Unexpected error occurred
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                title: "Internal Server Error"
                errors:
                  - code: "UNKNOWN"
                    message: "An unexpected error occurred"
    put:
      operationId: updateUser
      summary: Update user
      description: |
        Update an existing user by their ID.
        This operation is asynchronous and returns an Operation object to track progress.
      tags:
        - Users
      parameters:
        - name: X-Request-Id
          in: header
          description: Optional request identifier for tracking
          required: false
          schema:
            type: string
            format: uuid
        - name: userId
          in: path
          description: User identifier
          required: true
          schema:
            type: string
            example: "hvOB1l3zDCaDAwp9tNLzZA"
      requestBody:
        required: true
        content:
          application/vnd.users.v1+json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '202':
          description: User update operation initiated successfully
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/Operation'
        '400':
          description: Bad Request - Validation errors
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validationError:
                  summary: Field validation errors
                  value:
                    status: 400
                    title: "Validation error"
                    errors:
                      - code: "VALIDATION_ERROR"
                        field: "basicInfo.userName"
                        message: "must not be blank"
                mismatchedUserId:
                  summary: Mismatched userId in payload
                  value:
                    status: 400
                    title: "Mismatched userId in url vs payload"
                    detail: "Mismatched userId in url vs payload: hvOB1l3zDCaDAwp9tNLzZA vs anotherUserId"
                    errors:
                      - code: "VALIDATION_ERROR"
                        field: "basicInfo.userId"
                        message: "Mismatched userId in url vs payload: hvOB1l3zDCaDAwp9tNLzZA vs anotherUserId"
                duplicateUserName:
                  summary: Duplicate userName
                  value:
                    status: 400
                    title: "Validation error"
                    errors:
                      - code: "VALIDATION_ERROR"
                        message: "userName already in use"
        '403':
          description: Forbidden - Customer ID mismatch
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 403
                title: "Forbidden"
                detail: "CustomerId mismatch: 0012J00042NkZQIQA3 vs 0012J00042NkZQIQA4"
                errors:
                  - code: "FORBIDDEN"
                    message: "CustomerId mismatch: 0012J00042NkZQIQA3 vs 0012J00042NkZQIQA4"
        '404':
          description: User not found
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 404
                title: "Not Found"
                errors:
                  - code: "NOT_FOUND"
                    field: "basicInfo.userId"
                    message: "User not found"
        '408':
          description: Request Timeout - Downstream service timeout
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 408
                title: "Request Timeout"
                errors:
                  - code: "REQUEST_TIMEOUT"
                    message: "Request to downstream service timed out"
        '503':
          description: Service Unavailable - Service unavailable due to connectivity or network issues
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 503
                title: "Service unavailable"
                errors:
                  - code: "SERVICE_UNAVAILABLE"
                    message: "Service unavailable"
        '429':
          description: Too Many Requests - Rate limit exceeded
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 429
                title: "Too Many Requests"
                errors:
                  - code: "TOO_MANY_REQUESTS"
                    message: "Rate limit exceeded, please try again later"
        '500':
          description: Internal Server Error - Unexpected error occurred
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                title: "Internal Server Error"
                errors:
                  - code: "UNKNOWN"
                    message: "An unexpected error occurred"
    delete:
      operationId: deleteUser
      summary: Delete user
      description: |
        Delete a specific user by their ID.
        This operation is asynchronous and returns an Operation object to track progress.
      tags:
        - Users
      parameters:
        - name: X-Request-Id
          in: header
          description: Optional request identifier for tracking
          required: false
          schema:
            type: string
            format: uuid
        - name: userId
          in: path
          description: User identifier
          required: true
          schema:
            type: string
            example: "hvOB1l3zDCaDAwp9tNLzZA"
      responses:
        '202':
          description: User deletion operation initiated successfully
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/Operation'
        '503':
          description: Service Unavailable - Service unavailable due to connectivity or network issues
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 503
                title: "Service unavailable"
                errors:
                  - code: "SERVICE_UNAVAILABLE"
                    message: "Service unavailable"
        '500':
          description: Internal Server Error - Unexpected error occurred
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.users.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                title: "Internal Server Error"
                errors:
                  - code: "UNKNOWN"
                    message: "An unexpected error occurred"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
  schemas:
    User:
      type: object
      properties:
        basicInfo:
          $ref: '#/components/schemas/BasicInfo'
        directoryInfo:
          $ref: '#/components/schemas/DirectoryInfo'
        serviceInfo:
          $ref: '#/components/schemas/ServiceInfo'
        assignmentInfo:
          $ref: '#/components/schemas/AssignmentInfo'
      required:
        - basicInfo
    BasicInfo:
      type: object
      properties:
        userId:
          type: string
          description: "Unique ID of the user"
          example: "hvOB1l3zDCaDAwp9tNLzZA"
          readOnly: true
          nullable: true
        customerId:
          type: string
          description: "Unique ID of the customer account"
          example: "0012J00042NkZQIQA3"
          nullable: true
        createdTime:
          type: string
          format: date-time
          description: "Date/time the user was created"
          example: "2025-01-01T01:02:03Z"
          readOnly: true
          nullable: true
        lastUpdatedTime:
          type: string
          format: date-time
          description: "Date/time the user was last updated"
          example: "2025-01-02T01:02:03Z"
          readOnly: true
          nullable: true
        scimProvider:
          type: string
          description: "The Identity Provider linked to the user for SCIM provisioning"
          example: "okta"
          nullable: true
        userName:
          type: string
          description: "Unique username used for logging into services"
          example: "jane.doe@corp.com"
          minLength: 3
          maxLength: 70
          pattern: '^[A-Za-z0-9.@\-_/]+$'
        firstName:
          type: string
          description: "User first or given name"
          example: "Jane"
          minLength: 2
          maxLength: 128
          pattern: "^[A-Za-z0-9.,\\-_()'  ]+$"
        lastName:
          type: string
          description: "User surname or family name"
          example: "Doe"
          minLength: 2
          maxLength: 30
          pattern: "^[A-Za-z0-9.,\\-_()'  ]+$"
        status:
          type: string
          enum: [ACTIVE, INACTIVE]
          description: "User status controls whether user can log in or use services"
          example: "ACTIVE"
          nullable: true
        locale:
          type: string
          enum: [da-DK, de-DE, en-AU, en-GB, en-US, es-ES, fi-FI, fr-BE, fr-CA, fr-CH, fr-FR, it-IT, ja-JP, nl-BE, nl-NL, no-NO, pl-PL, pt-BR, pt-PT, sv-SE, zh-CN]
          description: "Language for voice prompts, email notifications and device display"
          example: "en-US"
          nullable: true
        timezone:
          type: string
          description: "Time zone used for downloading call recordings and viewing call queues"
          example: "Europe/London"
          nullable: true
        primaryEmail:
          type: string
          description: "Email used for password setup and onboarding information"
          example: "jane.doe@corp.com"
          format: email
          minLength: 5
          maxLength: 128
        ssoProvider:
          type: string
          description: "The Identity provider linked to the user for Single Sign-On"
          example: "Okta"
          nullable: true
        ssoFederationId:
          type: string
          description: "The Identity Provider's ID for the user for Single Sign-On"
          example: "jdoe@corp.com"
          nullable: true
        site:
          $ref: '#/components/schemas/Site'
      required:
        - userName
        - firstName
        - lastName
        - primaryEmail
    Site:
      type: object
      properties:
        id:
          type: string
          description: "Unique ID of the users's site"
          example: "SAH3U8guQaK4WQhpDZi0rQ"
          nullable: true
        name:
          type: string
          description: "The name of the user's site"
          example: "Headquarters"
          nullable: true
        pbxName:
          type: string
          description: "Unique code name of the PBX on which the user's site resides"
          example: "corpco01"
          nullable: true
    DirectoryInfo:
      type: object
      properties:
        department:
          type: string
          description: "Free text field to store the user's department"
          example: "Sales"
          minLength: 1
          maxLength: 100
          pattern: "^[A-Za-z0-9.,&@*+\\-#\\\\/()'– ]+$"
          nullable: true
        directoryScope:
          type: string
          enum: [CUSTOMER, PBX, SITE]
          description: "Controls which other users this user can see in any directory features"
          example: "PBX"
          nullable: true
        displayInDirectory:
          type: boolean
          description: "Controls whether this user is visible to others in any directory features"
          example: true
          nullable: true
        jobTitle:
          type: string
          description: "Free text field to store the user's job title"
          example: "Account Executive"
          minLength: 1
          maxLength: 254
          nullable: true
        personalPhoneNumbers:
          type: array
          description: "List of personal contact numbers from other providers to appear in any directory features"
          items:
            $ref: '#/components/schemas/ContactPhoneNumber'
          nullable: true
    ServiceInfo:
      type: object
      properties:
        licenses:
          type: array
          description: "List of licenses (aka subscriptions) assigned to the user"
          items:
            $ref: '#/components/schemas/License'
          nullable: true
        extensions:
          type: array
          description: "List of the voice extensions belonging to the user"
          items:
            $ref: '#/components/schemas/Extension'
          nullable: true
    License:
      type: object
      properties:
        id:
          type: string
          description: "Unique ID of the license"
          example: "02KB7TGTYAG4Rq4jDUhwyQ"
          nullable: true
        name:
          type: string
          description: "Name for the type of license"
          example: "UC Call Recordings Cold Storage-VOSVC0504-01-GB"
          nullable: true
        country:
          type: string
          description: "ISO:3166-2 country code of the license"
          example: "US"
          nullable: true
    AssignmentInfo:
      type: object
      properties:
        profilePolicy:
          $ref: '#/components/schemas/ProfilePolicy'
        ringGroups:
          type: array
          description: "List of ring groups the user is a member of"
          items:
            $ref: '#/components/schemas/RingGroup'
          nullable: true
        ucCallQueues:
          type: array
          items:
            $ref: '#/components/schemas/UCCallQueue'
          nullable: true
        userGroups:
          type: array
          items:
            $ref: '#/components/schemas/UserGroup'
          nullable: true
    ProfilePolicy:
      type: object
      properties:
        name:
          type: string
          description: "Name of the profile policy assigned ot the user"
          example: "8x8 Master User Template"
          nullable: true
    RingGroup:
      type: object
      properties:
        id:
          type: string
          description: "Unique ID of the ring group"
          example: "aeP9pOoDRbq8_KKiwtsXhQ"
          nullable: true
        name:
          type: string
          description: "Name of the ring group"
          example: "Main Reception"
          nullable: true
    UCCallQueue:
      type: object
      properties:
        id:
          type: string
          description: "Unique ID of the call queue"
          example: "00NKl7r6SjqRmYTxWlGeQQ"
          nullable: true
        name:
          type: string
          description: "Name of the call queue"
          example: "Sales CQ"
          nullable: true
        memberType:
          type: string
          enum: [PRIMARY, SECONDARY]
          description: "Indicates whether primary or secondary member"
          example: "PRIMARY"
          nullable: true
    UserGroup:
      type: object
      properties:
        id:
          type: string
          description: "Unique ID of the user group"
          example: "12345"
          nullable: true
        name:
          type: string
          description: "Name of the user group"
          example: "Supervisors"
          nullable: true
    Extension:
      type: object
      description: User voice extension with phone numbers, devices, and settings
      properties:
        id:
          type: string
          description: "Unique identifier of the extension."
          example: "7yKxifh1SLuDcqQO4501jA"
          nullable: true
        allowInAutoAttendant:
          type: boolean
          description: "Indicates whether the extension can be included in Auto Attendant menus or call routing."
          example: true
          nullable: true
        analogFaxEnabled:
          type: boolean
          description: "Indicates whether the extension is configured as an analog fax line"
          example: false
          nullable: true
        blockOutboundCallerId:
          type: boolean
          description: "Indicates whether the outbound caller ID should be hidden when making external calls."
          example: false
          nullable: true
        callWaitingEnabled:
          type: boolean
          description: "Indicates whether call waiting is enabled for the extension."
          example: true
          nullable: true
        dedicatedAgent:
          type: boolean
          description: "Indicates whether the extension belongs to a dedicated call-center agent"
          example: false
          nullable: true
        devices:
          type: array
          description: "List of physical devices associated with the extension."
          items:
            $ref: '#/components/schemas/Device'
          nullable: true
        dialPlanCallingCountry:
          type: string
          description: "Country code that defines the dialing plan used for outbound and internal call routing."
          example: "NANP"
          nullable: true
        dialPlanRuleset:
          type: string
          enum: [INTERNATIONAL, DOMESTIC, EMERGENCYONLY]
          description: "Dialing plan rule set applied to the extension, determining allowed dialing patterns and call routing"
          example: "INTERNATIONAL"
          nullable: true
        displayInDirectory:
          type: boolean
          description: "Indicates whether the extension appears in the company directory"
          example: true
          nullable: true
        doNotDisturb:
          type: boolean
          description: "Indicates whether Do Not Disturb mode is enabled for the extension, blocking inbound calls"
          example: false
          nullable: true
        emergencyAddress:
          $ref: '#/components/schemas/Address'
        emergencyAddressInheritFromSite:
          type: boolean
          description: "Indicates whether the emergency address is inherited from the site configuration"
          example: true
          nullable: true
        extensionNumber:
          type: string
          description: "Internal short extension number assigned to the user"
          example: "1001"
          nullable: true
        externalCallerIdName:
          type: string
          description: "Name displayed to external recipients on outbound calls"
          example: "Jane Doe"
          nullable: true
        externalCallerIdNumber:
          type: string
          description: "Phone number displayed to external recipients on outbound calls"
          example: "+14085551234"
          nullable: true
        extensionType:
          type: string
          enum: [UC, CC]
          description: "Type of extension (UC or CC)"
          example: "UC"
          nullable: true
        fqExtensionNumber:
          type: string
          description: "Fully qualified extension number including site prefix that is unique across all sites"
          example: "231001"
          nullable: true
        hotDeskEnabled:
          type: boolean
          description: "Indicates whether hot desking is enabled, allowing users to log in to shared devices"
          example: false
          nullable: true
        internalCallerIdFirstName:
          type: string
          description: "First name displayed for the user on internal caller ID."
          example: "Jane"
          nullable: true
        internalCallerIdLastName:
          type: string
          description: "Last name displayed for the user on internal caller ID."
          example: "Doe"
          nullable: true
        licenseId:
          type: string
          description: "Identifier of the license assigned to the extension"
          example: "02KB7TGTYAG4Rq4jDUhwyQ"
          nullable: true
        maxConcurrentCalls:
          type: integer
          description: "Maximum number of simultaneous calls allowed on the extension"
          example: 2
          nullable: true
        msTeamsEnabled:
          type: boolean
          description: "Indicates whether Microsoft Teams integration is enabled for the extension"
          example: false
          nullable: true
        musicOnHold:
          $ref: '#/components/schemas/AudioFile'
        nomadic911Enabled:
          type: boolean
          description: "Indicates whether Nomadic 911 location tracking is enabled for emergency calls"
          example: false
          nullable: true
        overheadPagingEnabled:
          type: boolean
          description: "Indicates whether overhead paging functionality is enabled for the extension"
          example: false
          nullable: true
        phoneNumbers:
          type: array
          description: "List of phone numbers assigned to the extension"
          items:
            $ref: '#/components/schemas/PhoneNumber'
          nullable: true
        primaryPhoneNumber:
          type: string
          description: "Primary phone number for the extension"
          example: "+14085551234"
          nullable: true
        recordingPlayAnnouncementToUser:
          type: boolean
          description: "Indicates whether a recording notification is played to the user when a call is being recorded"
          example: false
          nullable: true
        recordingPlayAnnouncementToOtherParty:
          type: boolean
          description: "Indicates whether a recording notification is played to the remote party when a call is being recorded"
          example: false
          nullable: true
        recordingMode:
          type: string
          enum: [OFF, ALWAYS, ON_DEMAND, ALWAYS_ALLOW_PAUSE]
          description: "Call recording mode configured for the extension"
          example: "ON_DEMAND"
          nullable: true
        showInboundCallerId:
          type: boolean
          description: "Indicates whether inbound caller ID is displayed on the user's device"
          example: true
          nullable: true
        voicemailEmail:
          type: string
          description: "Email address to which voicemail messages or notifications are delivered"
          example: "jane.doe@corp.com"
          format: email
          nullable: true
        voicemailNotification:
          type: string
          description: "Notification preference for new voicemail messages"
          nullable: true
        voicemailZeroOutDestination:
          type: string
          description: 'Destination used when callers press "0" during voicemail greeting (for example, operator extension or external number)'
          example: "1001"
          nullable: true
    Device:
      type: object
      properties:
        id:
          type: string
          description: "Unique ID of the device"
          example: "CyIkhSbwQ9GI1ZYLOXZr7A"
          nullable: true
        activationCode:
          type: string
          description: "Code that can be used to activate the device (associate a MAC address) via an IVR menu from the device itself"
          example: "5525266144968"
          nullable: true
        model:
          type: string
          description: "Display name of the device as shown in the admin interface or on device screens."
          example: "Yealink W56H"
          nullable: true
        macAddress:
          type: string
          description: "MAC address of the device. Allows colon or hyphen punctuation (will be ignored)"
          example: "0a1b2c3d4e5f"
          nullable: true
        status:
          type: string
          enum: [BINDED, AVAILABLE, RETIRED, ACTIVE, RESERVED]
          description: "Current operational state of the device."
          example: "ACTIVE"
          nullable: true
        lastUpdatedTime:
          type: string
          format: date-time
          description: "Date and time when the device record was last updated."
          example: "2025-01-01T00:00:01Z"
          nullable: true
        lines:
          type: integer
          description: "Number of voice lines currently configured on the device."
          example: 1
          nullable: true
        port:
          type: integer
          description: "Identifier of the physical or logical port associated with the device."
          example: 0
          nullable: true
        baseDevice:
          $ref: '#/components/schemas/BaseDevice'
    BaseDevice:
      type: object
      properties:
        id:
          type: string
          description: "Unique ID for the base device this device is linked to"
          example: "CyIkhSbwQ9GI1ZYLOXZr7A"
          nullable: true
        macAddress:
          type: string
          description: "MAC address of the base device"
          example: "0a1b2c3d4e5f"
          nullable: true
        displayName:
          type: string
          description: "Display name of the device as shown in the admin interface"
          example: "Store Room DECT Base"
          nullable: true
    AudioFile:
      type: object
      properties:
        id:
          type: string
          description: "Unique ID of the audio file."
          nullable: true
        name:
          type: string
          description: "The name of the audio file."
          nullable: true
    PhoneNumber:
      type: object
      properties:
        country:
          type: string
          description: "ISO:3166-2 two character country of the phone number"
          example: "US"
          nullable: true
        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 extension"
          example: "+14085551234"
          nullable: true
        portingNumber:
          $ref: '#/components/schemas/PortingNumber'
        primary:
          type: boolean
          description: "Indicates whether this is the primary phone number"
          example: true
          nullable: true
    PortingNumber:
      type: object
      properties:
        phoneNumber:
          type: string
          description: "The number which will replace this extension phone number when the porting process completes"
          example: "+14085556789"
          nullable: true
    ContactPhoneNumber:
      type: object
      properties:
        number:
          type: string
          description: "The personal contact number. Can include punctuation."
          example: "(408) 555-1234"
          nullable: true
        type:
          type: string
          enum: [WORK, MOBILE]
          description: "Type qualifier for the personal contact number"
          example: "WORK"
          nullable: true
    Address:
      type: object
      properties:
        id:
          type: string
          description: "Unique ID of the address"
          example: "b1c4944a-17a0-4b00-8d48-36001df07e22"
          nullable: true
        displayForm:
          type: string
          description: "Formatted, human-readable representation of the emergency address"
          example: "7 W 34TH ST, 613, New York NY, 10001"
          nullable: true
        organization:
          type: string
          description: "Organization name associated with the emergency address"
          example: "8x8"
          nullable: true
        building:
          type: string
          description: "Building name or identifier for the emergency address"
          example: "Bardon Hall"
          nullable: true
        streetNumber:
          type: string
          description: "Street number of the emergency address"
          example: "7"
          nullable: true
        streetNumberSuffix:
          type: string
          description: "Suffix associated with the street number, if applicable"
          example: "bis"
          nullable: true
        preDirectional:
          type: string
          description: "Directional prefix (N, S, E, W) used before the street name"
          example: "W"
          nullable: true
        streetName:
          type: string
          description: "Street name of the emergency address"
          example: "Whitechapel High Street"
          nullable: true
        streetNameSuffix:
          type: string
          description: "Street type or suffix (for example, Dr, Ave, St)"
          example: "Ave"
          nullable: true
        postDirectional:
          type: string
          description: "Directional suffix (N, S, E, W) used after the street name"
          example: "E"
          nullable: true
        dependentStreet:
          type: string
          description: "Secondary or dependent street name, if applicable"
          example: "Gemini Business Park"
          nullable: true
        secondaryLocation:
          type: string
          description: "Additional location information such as floor or suite number"
          example: "UNIT 203"
          nullable: true
        city:
          type: string
          description: "City name of the emergency address."
          example: "New York"
          nullable: true
        dependentCity:
          type: string
          description: "Dependent or alternative city name, if applicable"
          example: "NYC"
          nullable: true
        state:
          type: string
          description: "State or province code for the emergency address"
          example: "Santa Clara"
          nullable: true
        county:
          type: string
          description: "County or region associated with the emergency address"
          example: "NY"
          nullable: true
        postal:
          type: string
          description: "Postal or ZIP code of the emergency address"
          example: "10001"
          nullable: true
        zip4:
          type: string
          description: "Extended ZIP+4 code for U.S. addresses"
          example: "2032"
          nullable: true
        country:
          type: string
          description: "Country of the emergency address"
          example: "US"
          nullable: true
    UserPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
          nullable: true
        pagination:
          $ref: '#/components/schemas/Pagination'
        _links:
          $ref: '#/components/schemas/PaginationLinks'
    Pagination:
      type: object
      properties:
        pageSize:
          type: integer
          description: Number of items per page
          example: 100
          nullable: true
        pageNumber:
          type: integer
          description: Current page number (0-indexed)
          example: 0
          nullable: true
        hasMore:
          type: boolean
          description: Indicates if there are more pages available
          example: false
          nullable: true
        filter:
          type: string
          description: RSQL filter expression used in the request
          example: "basicInfo.status==ACTIVE"
          nullable: true
        sort:
          type: string
          description: Sort expression used in the request
          example: "basicInfo.userName"
          nullable: true
        nextScrollId:
          type: string
          description: Scroll ID for retrieving the next page
          nullable: true
    PaginationLinks:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/Link'
        next:
          $ref: '#/components/schemas/Link'
    Link:
      type: object
      properties:
        href:
          type: string
          description: URL for the link
          example: "https://api.8x8.com/admin-provisioning/users?pageSize=100"
          nullable: true
    Operation:
      type: object
      properties:
        operationId:
          type: string
          description: Unique identifier for the operation
          example: "op_123456789"
          nullable: true
        status:
          type: string
          enum: [PENDING, IN_PROGRESS, COMPLETED, FAILED, UNKNOWN]
          description: Current status of the operation
          example: "PENDING"
          nullable: true
        customerId:
          type: string
          description: Customer ID associated with the operation
          example: "0012J00042NkZQIQA3"
          nullable: true
        resourceType:
          type: string
          enum: [USER, RING_GROUP, SITE]
          description: Type of resource being operated on
          example: "USER"
          nullable: true
        resourceId:
          type: string
          description: ID of the resource being operated on
          example: "hvOB1l3zDCaDAwp9tNLzZA"
          nullable: true
        operationType:
          type: string
          enum: [CREATE, UPDATE, DELETE]
          description: Type of operation being performed
          example: "CREATE"
          nullable: true
        createdTime:
          type: string
          format: date-time
          description: Timestamp when the operation was created
          example: "2025-01-01T01:02:03Z"
          nullable: true
        completedTime:
          type: string
          format: date-time
          description: Timestamp when the operation completed
          example: "2025-01-01T01:05:03Z"
          nullable: true
        error:
          $ref: '#/components/schemas/ErrorResponse'
        _links:
          $ref: '#/components/schemas/OperationLinks'
    OperationLinks:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/Link'
        resource:
          $ref: '#/components/schemas/Link'
    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
          example: 404
          nullable: true
        instance:
          type: string
          description: URI reference that identifies the specific occurrence of the problem
          nullable: true
        time:
          type: string
          format: date-time
          description: Timestamp when the error occurred
          example: "2025-01-01T01:02:03Z"
          nullable: true
        title:
          type: string
          description: Short, human-readable summary of the problem
          example: "User not found"
          nullable: true
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence
          nullable: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          nullable: true
    Error:
      type: object
      properties:
        field:
          type: string
          description: Field name related to the error
          nullable: true
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          description: Detailed error message
          example: "User not found"
          nullable: true
    ErrorCode:
      type: string
      enum:
        - UNKNOWN
        - VALIDATION_ERROR
        - FORBIDDEN
        - CONFLICTING_QUERY_PARAMETER
        - SERVICE_UNAVAILABLE
        - NOT_FOUND
        - BAD_REQUEST
        - REQUEST_TIMEOUT
        - TOO_MANY_REQUESTS
        - CONFLICT
      description: Error code indicating the type of error