openapi: 3.2.0
info:
  title: 8x8 Users API
  version: '1.0'
  description: 'Operations tagged Users across 2 of this provider''s published API definitions: 8x8-administration-user-api-v1.yaml, 8x8-analytics-quality-management-and-speech-analytics-api.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.8x8.com/admin-provisioning
  description: Production
- url: https://api.8x8.com/qm/{region}/{apiversion}
  description: The QM/SA API Gateway Endpoint
  variables:
    region:
      enum:
      - us-west
      - us-east
      - uk
      - ap
      - ca
      default: us-west
    apiversion:
      default: v1
tags:
- name: Users
paths:
  /users:
    servers:
    - url: https://api.8x8.com/admin-provisioning
      description: Production
    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
      security:
      - ApiKeyAuth: []
    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
      security:
      - ApiKeyAuth: []
  /users/{userId}:
    servers:
    - url: https://api.8x8.com/admin-provisioning
      description: Production
    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
      security:
      - ApiKeyAuth: []
    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
      security:
      - ApiKeyAuth: []
    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
      security:
      - ApiKeyAuth: []
  /users/count:
    servers:
    - url: https://api.8x8.com/qm/{region}/{apiversion}
      description: The QM/SA API Gateway Endpoint
      variables:
        region:
          enum:
          - us-west
          - us-east
          - uk
          - ap
          - ca
          default: us-west
        apiversion:
          default: v1
    get:
      tags:
      - Users
      summary: Query user count
      description: Retrieve the total number of users registered in the system. You can also count only the active users.
      operationId: users count
      parameters:
      - name: Content-Type
        in: header
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: application/json
      - name: activeUsers
        in: query
        description: Whether the user is active or not.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
          example: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
                example: '10'
              example: 10
        default:
          description: Unexpected error
      deprecated: false
      security:
      - bearerAuth: []
  /users/{userReference}/supervisors:
    servers:
    - url: https://api.8x8.com/qm/{region}/{apiversion}
      description: The QM/SA API Gateway Endpoint
      variables:
        region:
          enum:
          - us-west
          - us-east
          - uk
          - ap
          - ca
          default: us-west
        apiversion:
          default: v1
    get:
      tags:
      - Users
      summary: Query supervisor values
      description: Retrieves the user's supervisor collection
      operationId: supervisors
      parameters:
      - name: userReference
        in: path
        description: The user's unique identifier for their supervisors collection
        required: true
        style: simple
        explode: false
        schema:
          type: number
          format: double
          example: 283
      - name: Content-Type
        in: header
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/basicUser'
              example:
              - userReference: 285
                name: Johana Doe
        default:
          description: Unexpected error
      deprecated: false
      security:
      - bearerAuth: []
  /users/{userReference}/trainers:
    servers:
    - url: https://api.8x8.com/qm/{region}/{apiversion}
      description: The QM/SA API Gateway Endpoint
      variables:
        region:
          enum:
          - us-west
          - us-east
          - uk
          - ap
          - ca
          default: us-west
        apiversion:
          default: v1
    get:
      tags:
      - Users
      summary: Trainer values.
      description: Retrieves the user's trainer collection
      operationId: trainers
      parameters:
      - name: userReference
        in: path
        description: The user's unique identifier for the trainer collection
        required: true
        style: simple
        explode: false
        schema:
          type: number
          format: double
          example: 283
      - name: Content-Type
        in: header
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/basicUser'
              example:
              - userReference: 285
                name: Johana Doe
        default:
          description: Unexpected error
      deprecated: false
      security:
      - bearerAuth: []
  /users/{userReference}/details:
    servers:
    - url: https://api.8x8.com/qm/{region}/{apiversion}
      description: The QM/SA API Gateway Endpoint
      variables:
        region:
          enum:
          - us-west
          - us-east
          - uk
          - ap
          - ca
          default: us-west
        apiversion:
          default: v1
    get:
      tags:
      - Users
      summary: User details.
      description: Retrieve user details
      operationId: user details
      parameters:
      - name: userReference
        in: path
        description: The unique identifier for the requested user details
        required: true
        style: simple
        explode: false
        schema:
          type: number
          format: double
          example: 283
      - name: Content-Type
        in: header
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/userResponse'
              example:
                userReference: 283
                agentId: agent123
                name: John Doe
                mainGroup: Agent
                phone: 1234554321
                email: user@company.com
                hireDate: 2019
                locked: false
                active: true
                links:
                - rel: interactions
                  href: https://api.8x8.com/qm/us-west/v1/interactions?userReference=283
                  type: GET
                - rel: supervisors
                  href: https://api.8x8.com/qm/us-west/v1/users/854/supervisors
                  type: GET
                - rel: trainers
                  href: https://api.8x8.com/qm/us-west/v1/users/854/trainers
                  type: GET
        default:
          description: Unexpected error
      deprecated: false
      security:
      - bearerAuth: []
components:
  schemas:
    UserGroup:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Unique ID of the user group
          example: '12345'
        name:
          type:
          - string
          - 'null'
          description: Name of the user group
          example: Supervisors
    ProfilePolicy:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: Name of the profile policy assigned ot the user
          example: 8x8 Master User Template
    Address:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Unique ID of the address
          example: b1c4944a-17a0-4b00-8d48-36001df07e22
        displayForm:
          type:
          - string
          - 'null'
          description: Formatted, human-readable representation of the emergency address
          example: 7 W 34TH ST, 613, New York NY, 10001
        organization:
          type:
          - string
          - 'null'
          description: Organization name associated with the emergency address
          example: 8x8
        building:
          type:
          - string
          - 'null'
          description: Building name or identifier for the emergency address
          example: Bardon Hall
        streetNumber:
          type:
          - string
          - 'null'
          description: Street number of the emergency address
          example: '7'
        streetNumberSuffix:
          type:
          - string
          - 'null'
          description: Suffix associated with the street number, if applicable
          example: bis
        preDirectional:
          type:
          - string
          - 'null'
          description: Directional prefix (N, S, E, W) used before the street name
          example: W
        streetName:
          type:
          - string
          - 'null'
          description: Street name of the emergency address
          example: Whitechapel High Street
        streetNameSuffix:
          type:
          - string
          - 'null'
          description: Street type or suffix (for example, Dr, Ave, St)
          example: Ave
        postDirectional:
          type:
          - string
          - 'null'
          description: Directional suffix (N, S, E, W) used after the street name
          example: E
        dependentStreet:
          type:
          - string
          - 'null'
          description: Secondary or dependent street name, if applicable
          example: Gemini Business Park
        secondaryLocation:
          type:
          - string
          - 'null'
          description: Additional location information such as floor or suite number
          example: UNIT 203
        city:
          type:
          - string
          - 'null'
          description: City name of the emergency address.
          example: New York
        dependentCity:
          type:
          - string
          - 'null'
          description: Dependent or alternative city name, if applicable
          example: NYC
        state:
          type:
          - string
          - 'null'
          description: State or province code for the emergency address
          example: Santa Clara
        county:
          type:
          - string
          - 'null'
          description: County or region associated with the emergency address
          example: NY
        postal:
          type:
          - string
          - 'null'
          description: Postal or ZIP code of the emergency address
          example: '10001'
        zip4:
          type:
          - string
          - 'null'
          description: Extended ZIP+4 code for U.S. addresses
          example: '2032'
        country:
          type:
          - string
          - 'null'
          description: Country of the emergency address
          example: US
    UCCallQueue:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Unique ID of the call queue
          example: 00NKl7r6SjqRmYTxWlGeQQ
        name:
          type:
          - string
          - 'null'
          description: Name of the call queue
          example: Sales CQ
        memberType:
          type:
          - string
          - 'null'
          enum:
          - PRIMARY
          - SECONDARY
          description: Indicates whether primary or secondary member
          example: PRIMARY
    Pagination:
      type: object
      properties:
        pageSize:
          type:
          - integer
          - 'null'
          description: Number of items per page
          example: 100
        pageNumber:
          type:
          - integer
          - 'null'
          description: Current page number (0-indexed)
          example: 0
        hasMore:
          type:
          - boolean
          - 'null'
          description: Indicates if there are more pages available
          example: false
        filter:
          type:
          - string
          - 'null'
          description: RSQL filter expression used in the request
          example: basicInfo.status==ACTIVE
        sort:
          type:
          - string
          - 'null'
          description: Sort expression used in the request
          example: basicInfo.userName
        nextScrollId:
          type:
          - string
          - 'null'
          description: Scroll ID for retrieving the next page
    Error:
      type: object
      properties:
        field:
          type:
          - string
          - 'null'
          description: Field name related to the error
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type:
          - string
          - 'null'
          description: Detailed error message
          example: User not found
    License:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Unique ID of the license
          example: 02KB7TGTYAG4Rq4jDUhwyQ
        name:
          type:
          - string
          - 'null'
          description: Name for the type of license
          example: UC Call Recordings Cold Storage-VOSVC0504-01-GB
        country:
          type:
          - string
          - 'null'
          description: ISO:3166-2 country code of the license
          example: US
    Extension:
      type: object
      description: User voice extension with phone numbers, devices, and settings
      properties:
        id:
          type:
          - string
          - 'null'
          description: Unique identifier of the extension.
          example: 7yKxifh1SLuDcqQO4501jA
        allowInAutoAttendant:
          type:
          - boolean
          - 'null'
          description: Indicates whether the extension can be included in Auto Attendant menus or call routing.
          example: true
        analogFaxEnabled:
          type:
          - boolean
          - 'null'
          description: Indicates whether the extension is configured as an analog fax line
          example: false
        blockOutboundCallerId:
          type:
          - boolean
          - 'null'
          description: Indicates whether the outbound caller ID should be hidden when making external calls.
          example: false
        callWaitingEnabled:
          type:
          - boolean
          - 'null'
          description: Indicates whether call waiting is enabled for the extension.
          example: true
        dedicatedAgent:
          type:
          - boolean
          - 'null'
          description: Indicates whether the extension belongs to a dedicated call-center agent
          example: false
        devices:
          type:
          - array
          - 'null'
          description: List of physical devices associated with the extension.
          items:
            $ref: '#/components/schemas/Device'
        dialPlanCallingCountry:
          type:
          - string
          - 'null'
          description: Country code that defines the dialing plan used for outbound and internal call routing.
          example: NANP
        dialPlanRuleset:
          type:
          - string
          - 'null'
          enum:
          - INTERNATIONAL
          - DOMESTIC
          - EMERGENCYONLY
          description: Dialing plan rule set applied to the extension, determining allowed dialing patterns and call routing
          example: INTERNATIONAL
        displayInDirectory:
          type:
          - boolean
          - 'null'
          description: Indicates whether the extension appears in the company directory
          example: true
        doNotDisturb:
          type:
          - boolean
          - 'null'
          description: Indicates whether Do Not Disturb mode is enabled for the extension, blocking inbound calls
          example: false
        emergencyAddress:
          $ref: '#/components/schemas/Address'
        emergencyAddressInheritFromSite:
          type:
          - boolean
          - 'null'
          description: Indicates whether the emergency address is inherited from the site configuration
          example: true
        extensionNumber:
          type:
          - string
          - 'null'
          description: Internal short extension number assigned to the user
          example: '1001'
        externalCallerIdName:
          type:
          - string
          - 'null'
          description: Name displayed to external recipients on outbound calls
          example: Jane Doe
        externalCallerIdNumber:
          type:
          - string
          - 'null'
          description: Phone number displayed to external recipients on outbound calls
          example: '+14085551234'
        extensionType:
          type:
          - string
          - 'null'
          enum:
          - UC
          - CC
          description: Type of extension (UC or CC)
          example: UC
        fqExtensionNumber:
          type:
          - string
          - 'null'
          description: Fully qualified extension number including site prefix that is unique across all sites
          example: '231001'
        hotDeskEnabled:
          type:
          - boolean
          - 'null'
          description: Indicates whether hot desking is enabled, allowing users to log in to shared devices
          example: false
        internalCallerIdFirstName:
          type:
          - string
          - 'null'
          description: First name displayed for the user on internal caller ID.
          example: Jane
        internalCallerIdLastName:
          type:
          - string
          - 'null'
          description: Last name displayed for the user on internal caller ID.
          example: Doe
        licenseId:
          type:
          - string
          - 'null'
          description: Identifier of the license assigned to the extension
          example: 02KB7TGTYAG4Rq4jDUhwyQ
        maxConcurrentCalls:
          type:
          - integer
          - 'null'
          description: Maximum number of simultaneous calls allowed on the extension
          example: 2
        msTeamsEnabled:
          type:
          - boolean
          - 'null'
          description: Indicates whether Microsoft Teams integration is enabled for the extension
          example: false
        musicOnHold:
          $ref: '#/components/schemas/AudioFile'
        nomadic911Enabled:
          type:
          - boolean
          - 'null'
          description: Indicates whether Nomadic 911 location tracking is enabled for emergency calls
          example: false
        overheadPagingEnabled:
          type:
          - boolean
          - 'null'
          description: Indicates whether overhead paging functionality is enabled for the extension
          example: false
        phoneNumbers:
          type:
          - array
          - 'null'
          description: List of phone numbers assigned to the extension
          items:
            $ref: '#/components/schemas/PhoneNumber'
        primaryPhoneNumber:
          type:
          - string
          - 'null'
          description: Primary phone number for the extension
          example: '+14085551234'
        recordingPlayAnnouncementToUser:
          type:
          - boolean
          - 'null'
          description: Indicates whether a recording notification is played to the user when a call is being recorded
          example: false
        recordingPlayAnnouncementToOtherParty:
          type:
          - boolean
          - 'null'
          description: Indicates whether a recording notification is played to the remote party when a call is being recorded
          example: false
        recordingMode:
          type:
          - string
          - 'null'
          enum:
          - false
          - ALWAYS
          - ON_DEMAND
          - ALWAYS_ALLOW_PAUSE
          description: Call recording mode configured for the extension
          example: ON_DEMAND
        showInboundCallerId:
          type:
          - boolean
          - 'null'
          description: Indicates whether inbound caller ID is displayed on the user's device
          example: true
        voicemailEmail:
          type:
          - string
          - 'null'
          description: Email address to which voicemail messages or notifications are delivered
          example: jane.doe@corp.com
          format: email
        voicemailNotification:
          type:
          - string
          - 'null'
          description: Notification preference for new voicemail messages
        voicemailZeroOutDestination:
          type:
          - string
          - 'null'
          description: Destination used when callers press "0" during voicemail greeting (for example, operator extension or external number)
          example: '1001'
    Link:
      type: object
      properties:
        href:
          type:
          - string
          - 'null'
          description: URL for the link
          example: https://api.8x8.com/admin-provisioning/users?pageSize=100
    Site:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Unique ID of the users's site
          example: SAH3U8guQaK4WQhpDZi0rQ
        name:
          type:
          - string
          - 'null'
          description: The name of the user's site
          example: Headquarters
        pbxName:
          type:
          - string
          - 'null'
          description: Unique code name of the PBX on which the user's site resides
          example: corpco01
    PhoneNumber:
      type: object
      properties:
        country:
          type:
          - string
          - 'null'
          description: ISO:3166-2 two character country of the phone number
          example: US
        origin:
          type:
          - string
          - 'null'
          description: Origin or source system of the phone number
          example: CLAIMED
        phoneNumber:
          type:
          - string
          - 'null'
          description: E.164-formatted phone number assigned to the extension
          example: '+14085551234'
        portingNumber:
          $ref: '#/components/schemas/PortingNumber'
        primary:
          type:
          - boolean
          - 'null'
          description: Indicates whether this is the primary phone number
          example: true
    PortingNumber:
      type: object
      properties:
        phoneNumber:
          type:
          - string
          - 'null'
          description: The number which will replace this extension phone number when the porting process completes
          example: '+14085556789'
    DirectoryInfo:
      type: object
      properties:
        department:
          type:
          - string
          - 'null'
          description: Free text field to store the user's department
          example: Sales
          minLength: 1
          maxLength: 100
          pattern: ^[A-Za-z0-9.,&@*+\-#\\/()'– ]+$
        directoryScope:
          type:
          - string
          - 'null'
          enum:
          - CUSTOMER
          - PBX
          - SITE
          description: Controls which other users this user can see in any directory features
          example: PBX
        displayInDirectory:
          type:
          - boolean
          - 'null'
          description: Controls whether this user is visible to others in any directory features
          example: true
        jobTitle:
          type:
          - string
          - 'null'
          description: Free text field to store the user's job title
          example: Account Executive
          minLength: 1
          maxLength: 254
        personalPhoneNumbers:
          type:
          - array
          - 'null'
          description: List of personal contact numbers from other providers to appear in any directory features
          items:
            $ref: '#/components/schemas/ContactPhoneNumber'
    AudioFile:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Unique ID of the audio file.
        name:
          type:
          - string
          - 'null'
          description: The name of the audio file.
    basicUser:
      description: The object model for user identification in linked user objects
      title: Basic User Information
      type: object
      properties:
        userReference:
          type: number
          description: The unique identifier for the user
          example: 285
        name:
          type: string
          description: The user's full name
          example: Johana Doe
      example:
        userReference: 285
        name: Johana Doe
    BasicInfo:
      type: object
      properties:
        userId:
          type:
          - string
          - 'null'
          description: Unique ID of the user
          example: hvOB1l3zDCaDAwp9tNLzZA
          readOnly: true
        customerId:
          type:
          - string
          - 'null'
          description: Unique ID of the customer account
          example: 0012J00042NkZQIQA3
        createdTime:
          type:
          - string
          - 'null'
          format: date-time
          description: Date/time the user was created
          example: '2025-01-01T01:02:03Z'
          readOnly: true
        lastUpdatedTime:
          type:
          - string
          - 'null'
          format: date-time
          description: Date/time the user was last updated
          example: '2025-01-02T01:02:03Z'
          readOnly: true
        scimProvider:
          type:
          - string
          - 'null'
          description: The Identity Provider linked to the user for SCIM provisioning
          example: okta
        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
          - 'null'
          enum:
          - ACTIVE
          - INACTIVE
          description: User status controls whether user can log in or use services
          example: ACTIVE
        locale:
          type:
          - string
          - 'null'
          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
        timezone:
          type:
          - string
          - 'null'
          description: Time zone used for downloading call recordings and viewing call queues
          example: Europe/London
        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
          - 'null'
          description: The Identity provider linked to the user for Single Sign-On
          example: Okta
        ssoFederationId:
          type:
          - string
          - 'null'
          description: The Identity Provider's ID for the user for Single Sign-On
          example: jdoe@corp.com
        site:
          $ref: '#/components/schemas/Site'
      required:
      - userName
      - firstName
      - lastName
      - primaryEmail
    userResponse:
      description: The object model for user information
      title: User Response
      type: object
      properties:
        userReference:
          type: number
          description: The user unique identifier
          example: 283
        agentId:
          type: string
          description: The agent identifier associated with the user.
          example: agent123
        name:
          type: string
          description: The user's name.
          example: John Doe
        mainGroup:
          type: string
          description: The main group to which the user belongs.
          example: Agent
        phone:
          type: string
          description: The user's phone number
          example: '1234554321'
        email:
          type: string
          description: The user's email address
          example: user@company.com
        hireDate:
          type: string
          description: The date that the user was hired.
          example: '2019'
        locked:
          type: boolean
          description: Identifies whether user access to the application is permitted
          example: false
        active:
          type: boolean
          description: Identifies whether the user is active within the company
          example: true
        links:
          type: array
          items:
            $ref: '#/components/schemas/userInteractionsLink'
      example:
        userReference: 283
        agentId: agent123
        name: John Doe
        mainGroup: Agent
        phone: 1234554321
        email: user@company.com
        hireDate: 2019
        locked: false
        active: true
        links:
        - rel: interactions
          href: https://api.8x8.com/qm/us-west/v1/interactions?userReference=283
          type: GET
        - rel: supervisors
          href: https://api.8x8.com/qm/us-west/v1/users/854/supervisors
          type: GET
        - rel: trainers
          href: https://api.8x8.com/qm/us-west/v1/users/854/trainers
          type: GET
    userInteractionsLink:
      description: The preformatted query URL for user interactions
      title: User Interaction Link
      type: object
      properties:
        rel:
          type: string
          description: Relation
          example: interactions
        href:
          type: string
          description: The URL for the user interactions
          example: https://api.8x8.com/qm/us-west/v1/interactions?userReference=283
        type:
          type: string
          description: The HTTP verb
          example: GET
    AssignmentInfo:
      type: object
      properties:
        profilePolicy:
          $ref: '#/components/schemas/ProfilePolicy'
        ringGroups:
          type:
          - array
          - 'null'
          description: List of ring groups the user is a member of
          items:
            $ref: '#/components/schemas/RingGroup'
        ucCallQueues:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/UCCallQueue'
        userGroups:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/UserGroup'
    PaginationLinks:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/Link'
        next:
          $ref: '#/components/schemas/Link'
    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
    Device:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Unique ID of the device
          example: CyIkhSbwQ9GI1ZYLOXZr7A
        activationCode:
          type:
          - string
          - 'null'
          description: Code that can be used to activate the device (associate a MAC address) via an IVR menu from the device itself
          example: '5525266144968'
        model:
          type:
          - string
          - 'null'
          description: Display name of the device as shown in the admin interface or on device screens.
          example: Yealink W56H
        macAddress:
          type:
          - string
          - 'null'
          description: MAC address of the device. Allows colon or hyphen punctuation (will be ignored)
          example: 0a1b2c3d4e5f
        status:
          type:
          - string
          - 'null'
          enum:
          - BINDED
          - AVAILABLE
          - RETIRED
          - ACTIVE
          - RESERVED
          description: Current operational state of the device.
          example: ACTIVE
        lastUpdatedTime:
          type:
          - string
          - 'null'
          format: date-time
          description: Date and time when the device record was last updated.
          example: '2025-01-01T00:00:01Z'
        lines:
          type:
          - integer
          - 'null'
          description: Number of voice lines currently configured on the device.
          example: 1
        port:
          type:
          - integer
          - 'null'
          description: Identifier of the physical or logical port associated with the device.
          example: 0
        baseDevice:
          $ref: '#/components/schemas/BaseDevice'
    BaseDevice:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Unique ID for the base device this device is linked to
          example: CyIkhSbwQ9GI1ZYLOXZr7A
        macAddress:
          type:
          - string
          - 'null'
          description: MAC address of the base device
          example: 0a1b2c3d4e5f
        displayName:
          type:
          - string
          - 'null'
          description: Display name of the device as shown in the admin interface
          example: Store Room DECT Base
    OperationLinks:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/Link'
        resource:
          $ref: '#/components/schemas/Link'
    ContactPhoneNumber:
      type: object
      properties:
        number:
          type:
          - string
          - 'null'
          description: The personal contact number. Can include punctuation.
          example: (408) 555-1234
        type:
          type:
          - string
          - 'null'
          enum:
          - WORK
          - MOBILE
          description: Type qualifier for the personal contact number
          example: WORK
    RingGroup:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Unique ID of the ring group
          example: aeP9pOoDRbq8_KKiwtsXhQ
        name:
          type:
          - string
          - 'null'
          description: Name of the ring group
          example: Main Reception
    ErrorResponse:
      type: object
      properties:
        status:
          type:
          - integer
          - 'null'
          description: HTTP status code
          example: 404
        instance:
          type:
          - string
          - 'null'
          description: URI reference that identifies the specific occurrence of the problem
        time:
          type:
          - string
          - 'null'
          format: date-time
          description: Timestamp when the error occurred
          example: '2025-01-01T01:02:03Z'
        title:
          type:
          - string
          - 'null'
          description: Short, human-readable summary of the problem
          example: User not found
        detail:
          type:
          - string
          - 'null'
          description: Human-readable explanation specific to this occurrence
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Error'
    Operation:
      type: object
      properties:
        operationId:
          type:
          - string
          - 'null'
          description: Unique identifier for the operation
          example: op_123456789
        status:
          type:
          - string
          - 'null'
          enum:
          - PENDING
          - IN_PROGRESS
          - COMPLETED
          - FAILED
          - UNKNOWN
          description: Current status of the operation
          example: PENDING
        customerId:
          type:
          - string
          - 'null'
          description: Customer ID associated with the operation
          example: 0012J00042NkZQIQA3
        resourceType:
          type:
          - string
          - 'null'
          enum:
          - USER
          - RING_GROUP
          - SITE
          description: Type of resource being operated on
          example: USER
        resourceId:
          type:
          - string
          - 'null'
          description: ID of the resource being operated on
          example: hvOB1l3zDCaDAwp9tNLzZA
        operationType:
          type:
          - string
          - 'null'
          enum:
          - CREATE
          - UPDATE
          - DELETE
          description: Type of operation being performed
          example: CREATE
        createdTime:
          type:
          - string
          - 'null'
          format: date-time
          description: Timestamp when the operation was created
          example: '2025-01-01T01:02:03Z'
        completedTime:
          type:
          - string
          - 'null'
          format: date-time
          description: Timestamp when the operation completed
          example: '2025-01-01T01:05:03Z'
        error:
          $ref: '#/components/schemas/ErrorResponse'
        _links:
          $ref: '#/components/schemas/OperationLinks'
    ServiceInfo:
      type: object
      properties:
        licenses:
          type:
          - array
          - 'null'
          description: List of licenses (aka subscriptions) assigned to the user
          items:
            $ref: '#/components/schemas/License'
        extensions:
          type:
          - array
          - 'null'
          description: List of the voice extensions belonging to the user
          items:
            $ref: '#/components/schemas/Extension'
    UserPage:
      type: object
      properties:
        data:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/User'
        pagination:
          $ref: '#/components/schemas/Pagination'
        _links:
          $ref: '#/components/schemas/PaginationLinks'
    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
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: access_token
x-refined-from:
- 8x8-administration-user-api-v1.yaml
- 8x8-analytics-quality-management-and-speech-analytics-api.json
x-readme:
  explorer-enabled: true
  proxy-enabled: false
  samples-enabled: true