openapi: 3.1.1
info:
  title: Groups Management
  description: API for managing user groups (Team Views) within an account
  version: 1.0.0
  contact:
    name: Avaya API Team
    email: api-team@avaya.com
    url: https://developers.avayacloud.com/avaya-infinity/
  license:
    name: Avaya Software Development Kit (SDK) Software License Terms
    url: https://support.avaya.com/css/P8/documents/101038288
servers:
- url: https://core.{customerId}.ec.avayacloud.com/api/config/v1
  description: Production
  variables:
    customerId:
      description: Your organization identifier
      default: your-org-id
security:
- BearerAuth: []
tags:
- name: Groups
  description: Group management operations
- name: Group Users
  description: Group membership operations
paths:
  /groups:
    get:
      summary: List all active groups
      description: Returns all active groups for the account.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/pageNumber'
      - $ref: '#/components/parameters/pageSize'
      - name: updatedSince
        in: query
        description: 'Filter groups updated on or after this UTC timestamp.

          Must be in ISO 8601 format (e.g., 2026-01-22T00:00:00Z or 2026-01-22T00:00:00).

          Timezone is optional. When used with updatedUntil, updatedUntil must be greater than updatedSince.

          Note: Groups are considered updated when their properties change OR when members are added, removed, or modified.

          Newly created groups have lastUpdated set to their creation time.

          '
        required: false
        schema:
          type: string
          format: date-time
      - name: updatedUntil
        in: query
        description: 'Filter groups updated on or before this UTC timestamp.

          Must be in ISO 8601 format (e.g., 2026-01-22T23:59:59Z or 2026-01-22T23:59:59).

          Timezone is optional. When used with updatedSince, must be greater than updatedSince.

          Note: Groups are considered updated when their properties change OR when members are added, removed, or modified.

          '
        required: false
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Groups retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupListPage'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ConstraintViolation'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      summary: Create a new group
      description: 'Creates a new group (Team View) with optional members.


        **Note:** If no `members` are specified, the authenticated user is automatically

        added as the first member of the group.

        '
      tags:
      - Groups
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGroupRequest'
      responses:
        '201':
          description: Group created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupData'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ConstraintViolation'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /groups/{groupId}:
    get:
      summary: Get a group by ID
      description: Returns a specific group with its users
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/groupId'
      - name: includeInDashboard
        in: query
        description: 'Filter users by includeInDashboard flag.


          If included, only group users with a matching includeInDashboard value will be included.

          If omitted, all group users will be included.

          '
        schema:
          type: boolean
      responses:
        '200':
          description: Group retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupData'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ConstraintViolation'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      summary: Update a group
      description: Updates group properties and/or membership
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/groupId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGroupRequest'
      responses:
        '200':
          description: Group updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupData'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ConstraintViolation'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /groups/{groupId}/users:
    patch:
      summary: Bulk add users to group
      description: Adds multiple users to a group
      tags:
      - Group Users
      parameters:
      - $ref: '#/components/parameters/groupId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddUsersToGroupRequest'
      responses:
        '200':
          description: Users added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddUsersToGroupResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ConstraintViolation'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'OAuth 2.0 Bearer Token with scoped permissions.

        Required scopes documented per endpoint.

        '
  parameters:
    groupId:
      name: groupId
      description: ID of the group in question
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/GroupId'
    pageNumber:
      name: pageNumber
      in: query
      description: The page number of the records to retrieve.
      required: false
      schema:
        type: integer
        format: int32
        default: 1
        minimum: 1
    pageSize:
      name: pageSize
      in: query
      description: The max number of records to retrieve per page.
      required: false
      schema:
        type: integer
        format: int32
        default: 10
        minimum: 1
        maximum: 50
  schemas:
    GroupName:
      description: The name of a group.
      type: string
      minLength: 1
      maxLength: 50
      pattern: ^[a-zA-Z0-9][a-zA-Z0-9 _-]*$
      example: Sales Team
    GroupType:
      description: Group type
      type: string
      enum:
      - team
    Member:
      description: Group user object with userId and includeInDashboard flag. Used in members property.
      type: object
      required:
      - userId
      properties:
        userId:
          description: ID of the user to include as a member of the group.
          $ref: '#/components/schemas/UserId'
        includeInDashboard:
          description: Include in team dashboard (for team type groups)
          type: boolean
          default: true
      example:
        userId: 002507f1e1c8e3e9a8b7c5d4e3f2
        includeInDashboard: true
    ChatChannelId:
      description: Associated chat channel ID (for team type)
      type:
      - 'null'
      - string
    CreateGroupRequest:
      description: Request payload for creating a new group.
      type: object
      required:
      - name
      properties:
        name:
          description: Name for the new group.
          $ref: '#/components/schemas/GroupName'
        members:
          description: Specifies the users to be included as members of the new group.
          type: array
          items:
            $ref: '#/components/schemas/Member'
        type:
          $ref: '#/components/schemas/GroupType'
        folderId:
          description: Optional ID of folder to organize the new group under.
          $ref: '#/components/schemas/FolderId'
        accountIdOverride:
          description: Master account override (requires special permissions)
          $ref: '#/components/schemas/AccountId'
        accountId:
          description: Target account ID (requires accountIdOverride)
          $ref: '#/components/schemas/AccountId'
    UpdateGroupRequest:
      description: 'Request payload for updating an existing group.


        All of the properties are optional, however at least one must be provided.

        '
      type: object
      properties:
        name:
          description: 'New name of the group.


            Note that group names must be unique.

            '
          $ref: '#/components/schemas/GroupName'
        isActive:
          description: Group active status
          type: boolean
        members:
          description: 'Specifies the users to be set as members of the new group.


            Notes this replaces all existing members.

            '
          type: array
          items:
            $ref: '#/components/schemas/Member'
        folderId:
          description: 'ID of the folder to put the group in.


            To remove a group from being in a folder, set this to null.

            '
          oneOf:
          - $ref: '#/components/schemas/FolderId'
          - type: 'null'
    AddUsersToGroupRequest:
      description: Payload object for adding multiple users to a group in a single operation.
      type: object
      required:
      - users
      properties:
        users:
          description: Array of users to add to the group.
          type: array
          items:
            $ref: '#/components/schemas/Member'
        addUsersToChannel:
          description: Whether to add users to associated channels (default true)
          type: boolean
          default: true
        accountIdOverride:
          description: Master account override
          $ref: '#/components/schemas/AccountId'
        accountId:
          description: Target account ID
          $ref: '#/components/schemas/AccountId'
    AddUsersToGroupResponse:
      description: Brief list of the group's members after the update.
      type: array
      items:
        type: object
        required:
        - userId
        properties:
          userId:
            description: ID of the user to include as a member of the group.
            $ref: '#/components/schemas/UserId'
            readOnly: true
          includeInDashboard:
            description: Is this user to be included in team dashboard (for team type groups)
            type: boolean
            readOnly: true
    GroupListPage:
      description: A page of results from querying groups.
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
          readOnly: true
        groups:
          type: array
          items:
            $ref: '#/components/schemas/GroupData'
          readOnly: true
        links:
          $ref: '#/components/schemas/Links'
          readOnly: true
      required:
      - pagination
      - groups
      - links
    GroupData:
      description: Returned data about a group.
      type: object
      required:
      - groupId
      - name
      - accountId
      - isActive
      - createdAt
      - createdBy
      - users
      properties:
        groupId:
          description: Unique identifier of the group.
          $ref: '#/components/schemas/GroupId'
          readOnly: true
        name:
          description: Name of the group.
          $ref: '#/components/schemas/GroupName'
          readOnly: true
        type:
          $ref: '#/components/schemas/GroupType'
          description: Group type
          readOnly: true
        accountId:
          description: ID of the account that owns the group.
          $ref: '#/components/schemas/AccountId'
          readOnly: true
        folderId:
          description: ID of the folder that the group was filed in, if any.
          $ref: '#/components/schemas/FolderId'
          readOnly: true
        parentGroupId:
          description: ID of the parent group. Only present for nested groups.
          $ref: '#/components/schemas/GroupId'
          readOnly: true
        isActive:
          type: boolean
          description: Whether the group is active
          readOnly: true
        createdAt:
          $ref: '#/components/schemas/CreatedAt'
          readOnly: true
        createdBy:
          $ref: '#/components/schemas/CreatedBy'
          readOnly: true
        updatedAt:
          $ref: '#/components/schemas/UpdatedAt'
          readOnly: true
        updatedBy:
          $ref: '#/components/schemas/UpdatedBy'
          description: Only present if the group has been updated by a different user than the creator.
          readOnly: true
        chatChannelId:
          $ref: '#/components/schemas/ChatChannelId'
          description: Only present for groups with an associated chat channel.
          readOnly: true
        users:
          description: List of users that are members of the group.
          type: array
          items:
            $ref: '#/components/schemas/GroupUser'
          readOnly: true
    GroupUser:
      description: Data about an individual user in a group.
      type: object
      required:
      - userId
      - details
      - email
      properties:
        userId:
          $ref: '#/components/schemas/UserId'
          readOnly: true
        details:
          $ref: '#/components/schemas/GroupUserDetails'
          readOnly: true
        fullName:
          $ref: '#/components/schemas/FullName'
          readOnly: true
        firstName:
          $ref: '#/components/schemas/FirstName'
          readOnly: true
        lastName:
          $ref: '#/components/schemas/LastName'
          readOnly: true
        namePrefix:
          $ref: '#/components/schemas/NamePrefix'
          readOnly: true
        nameSuffix:
          $ref: '#/components/schemas/NameSuffix'
          readOnly: true
        extension:
          $ref: '#/components/schemas/Extension'
          readOnly: true
        email:
          $ref: '#/components/schemas/Email'
          readOnly: true
        title:
          $ref: '#/components/schemas/UserTitle'
          readOnly: true
        statusType:
          $ref: '#/components/schemas/UserStatusType'
          readOnly: true
        status:
          $ref: '#/components/schemas/UserStatus'
          readOnly: true
        statusLastUpdated:
          description: Last status update time
          type: string
          format: date-time
          readOnly: true
        isAID:
          $ref: '#/components/schemas/IsAID'
          readOnly: true
        voipStatus:
          description: VoIP status
          type: string
          readOnly: true
        queues:
          $ref: '#/components/schemas/UserQueues'
          readOnly: true
        cxLogoutReason:
          description: Reason for agent logout
          type: string
          readOnly: true
    GroupUserDetails:
      type: object
      properties:
        teamView:
          $ref: '#/components/schemas/GroupUserTeamView'
          readOnly: true
    GroupUserTeamView:
      type: object
      properties:
        includeInDashboard:
          description: Whether to include user in team dashboard
          type: boolean
          readOnly: true
    Pagination:
      description: Pagination metadata
      type: object
      required:
      - pageNumber
      - pageSize
      - total
      properties:
        pageNumber:
          description: The current page number
          type: integer
          minimum: 1
          readOnly: true
          example: 1
        pageSize:
          description: The maximum number of items per page
          type: integer
          minimum: 1
          readOnly: true
          example: 10
        total:
          description: The total number of items
          type: integer
          minimum: 0
          readOnly: true
          example: 2
    GroupId:
      description: Unique identifier for a group.
      type: string
      pattern: ^007[0-9a-f]{23}$
      example: 007a1b2c3d4e5f67890abcdef12
    AccountId:
      description: Unique identifier for an account.
      type: string
      pattern: ^001[0-9a-f]{23}$
      example: 001f8e7d6c5b4a39281706f5e4d
    FolderId:
      description: Unique identifier for a folder.
      type: string
      pattern: ^073[0-9a-f]{23}$
      example: 073d010813b941cf7da111d147
    CreatedAt:
      description: Timestamp of when the resource was created.
      type: string
      format: date-time
      example: '2025-09-08T06:19:21.561Z'
    UserId:
      description: Unique identifier for a user.
      type: string
      pattern: ^002[0-9a-f]{23}$
      example: 002507f1e1c8e3e9a8b7c5d4e3f2
    CreatedBy:
      description: ID of the user who created the resource.
      allOf:
      - $ref: '#/components/schemas/UserId'
      example: 002d010826307dd6630992437b
    UpdatedAt:
      description: 'Timestamp of when the resource was last updated.


        This may not be included if the resource has not been updated since it was created.

        '
      type: string
      format: date-time
      example: '2025-09-08T06:19:21.561Z'
    UpdatedBy:
      description: 'ID of the user who last updated the resource.


        This may not be included if the resource has not been updated since it was created.

        '
      allOf:
      - $ref: '#/components/schemas/UserId'
      example: 002d010826307dd6630992437b
    FullName:
      description: The full name of the user (firstName + lastName).
      type: string
      example: John Smith
    FirstName:
      description: The first name of a user.
      type: string
      minLength: 2
      maxLength: 255
      pattern: ^[^<>\^@#]*$
      example: John
    LastName:
      description: The last name of a user.
      type: string
      minLength: 2
      maxLength: 255
      pattern: ^[^<>\^@#]*$
      example: Smith
    NamePrefix:
      description: The name prefix of a user.
      type: string
    NameSuffix:
      description: The name suffix of a user.
      type: string
      enum:
      - Jr
      - Sr
      - I
      - II
      - III
      - IV
      - V
      - CLU
      - CO
      - CPA
      - DDS
      - ESQ
      - MD
      - PhD
      - RN
    Extension:
      description: The extension of an agent user.
      type: string
      example: '1001'
    Email:
      description: A user's email address
      type: string
      format: email
    UserTitle:
      description: The user's job title.
      type: string
      minLength: 1
      maxLength: 510
      example: Supervisor
    UserStatusType:
      description: User status type
      type: string
      example: offline
    UserStatus:
      description: Current user status
      type: string
      example: Offline
    IsAID:
      description: Whether user is using AID
      type: boolean
      example: false
    QueueId:
      description: Unique identifier for a queue.
      type: string
      minLength: 23
      maxLength: 26
      pattern: ^003[0-9a-f]{20,23}$
      example: 00301090301ad8db0f0d4c370
    UserQueues:
      description: Queues configuration for a user or profile.
      type: object
      properties:
        access:
          type: array
          items:
            $ref: '#/components/schemas/QueueId'
        performance:
          type: array
          items:
            $ref: '#/components/schemas/QueueId'
        autoLogin:
          type: array
          items:
            $ref: '#/components/schemas/QueueId'
        proficiency:
          type: array
          items:
            $ref: '#/components/schemas/QueueId'
        logins:
          type: array
          items:
            $ref: '#/components/schemas/QueueId'
        defaultOutboundQueue:
          anyOf:
          - $ref: '#/components/schemas/QueueId'
          - type: 'null'
        outboundQueueId:
          anyOf:
          - $ref: '#/components/schemas/QueueId'
          - type: 'null'
    Links:
      description: Pagination navigation links
      type: object
      required:
      - prev
      - next
      properties:
        prev:
          description: URL of the previous page. Blank if currently on the first page.
          type: string
          readOnly: true
          example: ''
        next:
          description: URL of the next page. Blank if currently on the last page.
          type: string
          readOnly: true
          example: ''
    Violation:
      type: object
      properties:
        field:
          description: 'The name of the field in the request that caused the violation.


            This can be the name of a path parameter, query parameter, or a field within the request body.

            '
          type: string
          readOnly: true
          example: jobName
        message:
          description: 'A human-readable explanation specific to this occurrence of the violation.

            '
          type: string
          readOnly: true
          example: must match "^[a-zA-Z]{6}$"
        code:
          description: 'The violation code generated by the server for this occurrence of the violation.


            Use this code when implementing any error handling logic instead of the message, as the message can change.

            '
          type: integer
          format: int32
          readOnly: true
          example: 20006
      required:
      - field
      - message
      - code
      example:
      - field: emailAddress
        message: must not be null
        code: 20002
    Problem:
      type: object
      description: '<b>Problem Detail</b> is a way to carry machine-readable details of errors in an HTTP

        response to avoid the need to define new error response formats for HTTP APIs


        <a href="https://tools.ietf.org/html/rfc7807">RFC 7807</a>

        '
      properties:
        type:
          description: 'An absolute URI that identifies the problem type.


            When dereferenced, it SHOULD provide human-readable documentation for the problem type (e.g., using HTML).

            '
          type: string
          format: uri
          readOnly: true
          example: https://developers.avayacloud.com/avaya-infinity/docs/group-management#error-reference
        title:
          description: 'A short, summary of the problem type.


            Written in English and readable for engineers (usually not suited for non technical stakeholders and not localized).

            '
          type: string
          readOnly: true
          example: Service Unavailable
        status:
          description: 'The HTTP status code generated by the origin server for this occurrence of the problem.

            '
          type: integer
          format: int32
          minimum: 300
          exclusiveMaximum: 600
          readOnly: true
          example: 503
        detail:
          description: 'A human-readable explanation specific to this occurrence of the problem.

            '
          type: string
          readOnly: true
          example: Connection to database timed out
        instance:
          description: 'An absolute URI that identifies the specific occurrence of the problem.


            It may or may not yield further information if dereferenced.

            '
          type: string
          format: uri
          readOnly: true
        violations:
          description: 'A list of violations that occurred as a result of invalid data provided as part of a request.

            '
          type: array
          items:
            $ref: '#/components/schemas/Violation'
          readOnly: true
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://developers.avayacloud.com/errors/constraint-violation
            title: Constraint Violation
            status: 400
            detail: Request contains invalid or missing fields
            violations:
            - field: accountId
              message: must match "^[a-zA-Z]{6}$"
              code: 20006
    Unauthorized:
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://developers.avayacloud.com/errors/unauthorized
            title: Unauthorized
            status: 401
            detail: Bearer token expired at 2025-12-08T10:15:00Z. Request a new token.
            requestId: req_xyz789
            timestamp: '2025-12-08T10:30:05Z'
    Forbidden:
      description: Forbidden
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://developers.avayacloud.com/errors/forbidden
            title: Forbidden
            status: 403
            detail: 'Missing required scope: ''workflows:execute''. Your token has: ''workflows:read'''
            requestId: req_xyz789
            timestamp: '2025-12-08T10:30:05Z'
    ConstraintViolation:
      description: Constraint Violation
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    InternalServerError:
      description: Internal Server Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://developers.avayacloud.com/errors/internal-error
            title: Internal Server Error
            status: 500
            detail: An unexpected error occurred while processing your request
            requestId: req_xyz789
            timestamp: '2025-12-08T10:30:05Z'
    Conflict:
      description: Conflict
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://developers.avayacloud.com/errors/conflict
            title: Conflict
            status: 409
            detail: A resource with the same unique constraint values already exists
            violations:
            - field: name
              message: A category with this name already exists
    NotFound:
      description: Not Found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://developers.avayacloud.com/errors/resource-not-found
            title: Resource Not Found
            status: 404
            detail: workflowId 'wf_123abc' does not exist
            requestId: req_xyz789
            timestamp: '2025-12-08T10:30:05Z'