openapi: 3.0.0
info:
  title: Users management
  description: >-
    This web service exposes a set of utilities to manage the IAS users
  version: 2025.Winter.1
servers:
  - url: 'https://{host}/fw/Apps/ApplicationSuite/WebAPI/UsersManagement'
    description: IAS server
    variables:
      host:
        default: localhost
        description: The IAS server hostname or IP address
security:
  - UserSecurity: []
paths:
  '/Users':
    get:
      summary: Get IAS users
      tags:
        - Users
      parameters:
        - name: pbxUsername
          description: The username of the user into the PBX
          in: query
          schema:
            type: string
            example: "pbx.john_doe"
        - name: adUsername
          description: The username of the user into the Active Directory
          in: query
          schema:
            type: string
            example: "ad.john_doe"
        - name: tenantId
          description: The id of the tenant of the user (available to users complete managers only)
          in: query
          schema:
            type: string
            example: "ACME"
      security: 
        - UserSecurity: []
      responses:
        '200':
          description: Returning a list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  description: Users list
                  properties:
                    username:
                      type: string
                      description: Username
                      example: "john_doe"
                    firstName:
                      type: string
                      description: User's first name
                      example: "John"
                    lastName:
                      type: string
                      description: User's last name
                      example: "Doe"
                    telephoneAddress:
                      type: string
                      description: User's primary extension number
                      example: "123456"
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
  '/Users/{identifier}/Picture':
    get:
      summary: Returns user's picture
      description: ''
      tags:
        - Users
      parameters:
        - name: identifier
          description: >
            Identifier of the user you want to get the picture of.


            The value of `pov` parameter determines which user field to use:
            
            * *jabber*: use `pbxUsername`
          example: johndoe123
          in: path
          required: true
          schema:
            type: string
        - name: pov
          description: The application point of view
          example: jabber
          in: query
          required: true
          schema:
            type: string
            enum:
              - jabber
      security: 
        - UserSecurity: []
      responses:
        '200':
          description: Returning user's picture
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
                example: <image>
        '400':
          description: The request is missing some required parameters or specifying some invalid values
        '401':
          description: Wrong user credentials
        '404':
          description: No such single user found using given identifier or the user has no picture associated
        '500':
          $ref: '#/components/responses/500'
        '503':
          description: Pictures repository is disabled
  '/Sync/Start':
    post:
      summary: Starts users synchronization
      tags:
        - Users synchronization
      security: 
        - UserSecurity: []
      responses:
        '202':
          description: Synchronization has started and will run asynchronously using sync sources manually configured and enabled in Imagicle Application Suite Web interface
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '409':
          description: Users synchronization is disabled
        '500':
          $ref: '#/components/responses/500'
        '503':
          description: User synchronization is already in progress
        '504':
          description: Synchronization service is down
components:
  securitySchemes:
    UserSecurity:
      type: http
      scheme: basic
  responses:
    '401':
      description: No authentication provided or wrong user credentials
    '403':
      description: Authenticated user is not authorized to perform this operation
    '500':
      description: An error occurred while processing the request