openapi: 3.0.1
info:
  title: User API
  description: >
    ## Purpose
    

    This API exists to make it possible to create, get, update and delete users
    and user images.

    
    ## Key Concepts
    

    **User** - Represents the actual user that was originally created by the
    company admin with meta information.
    

    **CompanyRole** - A user can have one or more roles. A role decides what a
    user can see and do.
    

    **Image** - Represents an image / avatar of a user. That image will be
    displayed in various places across the web. 

    Users in the same company can see the avatar image of a user, but it will
    not be available for users without access to the company or company group.
  version: 1.0.0

servers:
  - url: 'https://api.pageroonline.com/user/v1'
    description: Production server. Will use `europe1` region by default.
    x-internal: false
  - url: 'https://api.{region}.pageroonline.com/user/v1'
    description: Regional API URL for production server.
    x-internal: false
    variables:
      region:
        default: europe1
        description: The geographic region for data residency.
tags:
  - name: User
    description: Handle users
  - name: CompanyRole
    description: Handle company roles
  - name: Image
    description: Handle user images (avatars)

paths:
  # *** User ***
  /me:
    get:
      tags:
        - User
      summary: Get currently authenticated User.
      description: Get currently authenticated `User` details.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              example:
                id: 123e4567-e89b-12d3-a456-426614174000
                username: john.doe@example.com
                fullName: John Doe
                email: john.doe@example.com
                phone: '+123456789'
                locale: en-US
                confirmed: true
                active: true
                userType: Standard
                region:
                  id: europe1
                  baseUrl: 'https://api.europe1.pageroonline.com'
        '401':
          description: The user is not authenticated
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnAuthorizedErrorResponse'
        '404':
          description: The user can not be found in region
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotFoundErrorResponse'
              example:
                - errorCode: NOT_AVAILABLE_IN_REGION
                  description: Not available in current region.
                  technicalDescription: User does not exist in this region.
                  resourceUrl: 'https://api.europe1.pageroonline.com/user/v1/me'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InternalServerError'

  /users:
    get:
      tags:
        - User
      summary: Get all users with access to company.
      description: >
        Get users that have access to the specified company. The response body
        will vary based on the currently authenticated user's access level.
          - Company Group Admin : Returns full user details.
          - Company Admin : Returns full user details.
          - Company User : Returns the base user details including id, username, fullName, active.
      parameters:
        - name: companyId
          in: query
          description: Get users that have access to this company
          required: true
          schema:
            type: string
        - name: searchTerm
          in: query
          description: Return users where searchTerm is part of username, fullName or email
          schema:
            type: string
        - name: sort
          in: query
          description: >
            Sort result, Possible sort values username, fullName or email. 
            Default order is ascending. To get descending order add a minus (-)
            before sort value e.g -fullName
          schema:
            type: string
        - name: offset
          in: query
          description: >
            The number of items to skip before starting to collect the result
            set.
          schema:
            minimum: 0
            type: integer
        - name: limit
          in: query
          description: The maximum number of items in the collection resource response.
          schema:
            minimum: 0
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Users'
              example:
                meta:
                  offset: 0
                  limit: 2
                  total: 42
                users:
                  - id: b7e2a1c4-3f2b-4e7a-9c8d-2f6e8a1b5c3d
                    username: alice.smith@example.com
                    fullName: Alice Smith
                    email: alice.smith@example.com
                    phone: '+1234567890'
                    locale: en-US
                    confirmed: true
                    active: true
                    userType: Standard
                    region:
                      id: europe1
                      baseUrl: 'https://api.europe1.pageroonline.com'
                  - id: c1e7b2a9-4d5f-4e2a-8b3c-9f7d2e6a1c5b
                    username: bob.jones@example.com
                    fullName: Bob Jones
                    email: bob.jones@example.com
                    phone: '+1987654321'
                    locale: sv-SE
                    confirmed: true
                    active: true
                    userType: Standard
                    region:
                      id: europe1
                      baseUrl: 'https://api.europe1.pageroonline.com'
        '401':
          description: The user is not authenticated
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnAuthorizedErrorResponse'
        '404':
          description: The item can not be found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotFoundErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InternalServerError'

    post:
      tags:
        - User
      summary: Create a new User.
      description: Create a user is allowed for CompanyAdmin of the same company.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserForCreation'
            example:
              username: emma.wilson@example.com
              fullName: Emma Wilson
              email: emma.wilson@example.com
              phone: '+1122334455'
              companyId: f3b2e1c7-8d4a-4e6b-9c2d-1a7e5b3c4d8f
              locale: en-GB
              userType: Standard
        required: true
      responses:
        '201':
          description: User successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              example:
                id: e2a4c7b1-5d3e-4f8a-9b2c-7e6d1a2f3c4b
                username: emma.wilson@example.com
                fullName: Emma Wilson
                email: emma.wilson@example.com
                phone: '+1122334455'
                locale: en-GB
                confirmed: false
                active: false
                userType: Standard
                region:
                  id: europe1
                  baseUrl: 'https://api.europe1.pageroonline.com'
        '400':
          description: The User cannot be created due to incorrect input.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    errorCode:
                      type: string
                      description: |
                        Error code. Currently possible values:
                         - **USERNAME_NOT_UNIQUE** There is already a user with the same username
                         - **INVALID_USERNAME_LENGTH** Username must be 6-80 characters long.
                         - **INVALID_USERNAME_CHARACTER**
                         - **INVALID_FULL_NAME_CHARACTER**
                         - **INVALID_EMAIL_CHARACTER**
                         - **INVALID_PHONE_NUMBER**
                         - **USER_LIMIT_EXCEEDED** 
                         - **COMPANY_GROUP_USER_LIMIT_EXCEEDED** 
                         - **BAD_REQUEST**
                         - **FORBIDDEN**
                         - **NOT_FOUND**
                        -  **NOT_AVAILABLE_IN_REGION**                        
                         - **INTERNAL_SERVER_ERROR**
                      example: USERNAME_NOT_UNIQUE
                    description:
                      type: string
                      description: The translated errormessage.
                    technicalDescription:
                      type: string
                      description: A more detailed description of the error in English.
        '401':
          description: The user is not authenticated
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnAuthorizedErrorResponse'
        '403':
          description: Not authorized to perform action.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ForbiddenErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InternalServerError'
      x-codegen-request-body-name: user

  /users/{id}:
    get:
      tags:
        - User
      summary: Get a User.
      description: >
        Get a user. The response body will vary based on the currently
        authenticated user's access level.
          - Company Group Admin : Returns full user details.
          - Company Admin : Returns full user details.
          - Company User : Returns the base user details including id, username, fullName, active.
      parameters:
        - name: id
          in: path
          description: Id of `User`
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              example:
                id: b7e2a1c4-3f2b-4e7a-9c8d-2f6e8a1b5c3d
                username: alice.smith@example.com
                fullName: Alice Smith
                email: alice.smith@example.com
                phone: '+1234567890'
                locale: en-US
                confirmed: true
                active: true
                userType: Standard
                region:
                  id: europe1
                  baseUrl: 'https://api.europe1.pageroonline.com'
        '401':
          description: The user is not authenticated
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnAuthorizedErrorResponse'
        '404':
          description: The user can not be found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotFoundErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InternalServerError'

    put:
      tags:
        - User
      summary: Update a User.
      description: Update a `User` is allowed for CompanyAdmin of the same company.
      parameters:
        - name: id
          in: path
          description: '`User` id'
          required: true
          schema:
            type: string
      requestBody:
        description: The `User`
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserForUpdating'
            example:
              id: e2a4c7b1-5d3e-4f8a-9b2c-7e6d1a2f3c4b
              username: emma.wilson@example.com
              fullName: Emma Wilson
              email: emma.wilson@example.com
              phone: '+1122334455'
              locale: en-GB
              active: true
              userType: Standard
        required: true
      responses:
        '200':
          description: User successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              example:
                id: e2a4c7b1-5d3e-4f8a-9b2c-7e6d1a2f3c4b
                username: emma.wilson@example.com
                fullName: Emma Wilson
                email: emma.wilson@example.com
                phone: '+1122334455'
                locale: en-GB
                confirmed: true
                active: true
                userType: Standard
                region:
                  id: europe1
                  baseUrl: 'https://api.europe1.pageroonline.com'
        '400':
          description: The User could not be updated due to incorrect input.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    errorCode:
                      type: string
                      description: |
                        Error code. Currently possible values:
                         - **USERNAME_NOT_UNIQUE** There is already a user with the same username
                         - **INVALID_USERNAME_LENGTH** Username must be 6-80 characters long.
                         - **INVALID_USERNAME_CHARACTER**
                         - **INVALID_FULL_NAME_CHARACTER**
                         - **INVALID_EMAIL_CHARACTER**
                         - **INVALID_PHONE_NUMBER**                        
                         - **BAD_REQUEST**
                         - **FORBIDDEN**
                         - **NOT_FOUND**
                         - **NOT_AVAILABLE_IN_REGION** 
                         - **INTERNAL_SERVER_ERROR**
                      example: INVALID_EMAIL_CHARACTER
                    description:
                      type: string
                      description: The translated errormessage.
                    technicalDescription:
                      type: string
                      description: A more detailed description of the error in English.
        '401':
          description: The user is not authenticated
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnAuthorizedErrorResponse'
        '403':
          description: Not authorized to perform action.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ForbiddenErrorResponse'
        '404':
          description: The user can not be found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotFoundErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InternalServerError'
      x-codegen-request-body-name: user

    delete:
      tags:
        - User
      summary: Delete a User.
      description: Delete a User is allowed for CompanyAdmin of the same company.
      parameters:
        - name: id
          in: path
          description: '`User` id'
          required: true
          schema:
            type: string
      responses:
        '204':
          description: User successfully deleted
          content: { }
        '401':
          description: The user is not authenticated
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnAuthorizedErrorResponse'
        '403':
          description: Not authorized to perform action.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ForbiddenErrorResponse'
        '404':
          description: The user does not exist in region.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotFoundErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InternalServerError'


  # *** CompanyRole ***
  /users/{id}/companyroles:
    get:
      tags:
        - CompanyRole
      summary: Get the user's company roles.
      description: |
        Company admin can get the company roles the `User` has.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: companyId
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Role'
              example:
                - roleId: companyRoleOne
                  description: Administrator of the company
                - roleId: companyRoleTwo
                  description: Standard user of the company
        '401':
          description: The user is not authenticated
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnAuthorizedErrorResponse'
        '403':
          description: Not authorized to perform action.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ForbiddenErrorResponse'
        '404':
          description: The user can not be found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotFoundErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InternalServerError'

    put:
      tags:
        - CompanyRole
      summary: Update company roles.
      description: Company admin can update the company role of any `User`.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: companyId
          in: query
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/RoleId'
            example:
              - roleId: companyRoleOne
              - roleId: companyRoleTwo
              - roleId: companyRoleThree
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Role'
              example:
                - roleId: companyRoleOne
                  description: Administrator of the company
                - roleId: companyRoleTwo
                  description: Standard user of the company
                - roleId: companyRoleThree
                  description: Sending documents for the company
        '400':
          description: The User roles could not be updated due to incorrect input.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    errorCode:
                      type: string
                      description: |
                        Error code. Currently possible values:
                         - **BAD_REQUEST**
                         - **INVALID_ROLE_ID**
                      example: INVALID_ROLE_ID
                    description:
                      type: string
                      description: The translated errormessage.
                    technicalDescription:
                      type: string
                      description: A more detailed description of the error in English.
        '401':
          description: The user is not authenticated
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnAuthorizedErrorResponse'
        '403':
          description: Not authorized to perform action.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ForbiddenErrorResponse'
        '404':
          description: The user can not be found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotFoundErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InternalServerError'
      x-codegen-request-body-name: companyRoles

    post:
      tags:
        - CompanyRole
      summary: Add company role.
      description: Company admin can Add a `CompanyRole` to a `User`.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: companyId
          in: query
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoleId'
            example:
              roleId: companyRoleTen
        required: true
      responses:
        '200':
          description: Role successfully added to user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
              example:
                roleId: companyRoleTen
        '400':
          description: The User could not be updated due to incorrect input.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    errorCode:
                      type: string
                      description: |
                        Error code. Currently possible values:
                         - **BAD_REQUEST**
                         - **INVALID_ROLE_ID**
                      example: INVALID_ROLE_ID
                    description:
                      type: string
                      description: The translated errormessage.
                    technicalDescription:
                      type: string
                      description: A more detailed description of the error in English.
        '401':
          description: The user is not authenticated
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnAuthorizedErrorResponse'
        '403':
          description: Not authorized to perform action.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ForbiddenErrorResponse'
        '404':
          description: The user can not be found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotFoundErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InternalServerError'
      x-codegen-request-body-name: companyRole

    delete:
      tags:
        - CompanyRole
      summary: Delete a company role.
      description: Company admin can delete a `CompanyRole`
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: companyId
          in: query
          required: true
          schema:
            type: string
        - name: roleId
          in: query
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Successfully deleted
          content: { }
        '401':
          description: The user is not authenticated
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnAuthorizedErrorResponse'
        '403':
          description: Not authorized to perform action.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ForbiddenErrorResponse'
        '404':
          description: The user can not be found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotFoundErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InternalServerError'

  /users/{id}/password:
    put:
      tags:
        - User
      summary: Update a user's password.
      description: Update a user's password. It's allowed to update your own password.
      parameters:
        - name: id
          in: path
          description: '`User` id'
          required: true
          schema:
            type: string
      requestBody:
        description: The new password
        content:
          application/json:
            schema:
              required:
                - currentPassword
                - newPassword
              type: object
              properties:
                currentPassword:
                  type: string
                newPassword:
                  type: string
            example:
              currentPassword: 'G4234D42gw3#v23'
              newPassword: '88D!dfATsds09&mn'
        required: true
      responses:
        '200':
          description: Password successfully updated
          content: { }
        '400':
          description: The password could not be updated due to incorrect input.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    errorCode:
                      type: string
                      description: |
                        Error code. Currently possible values:
                         - **BAD_REQUEST** The provided request is invalid
                         - **INVALID_CURRENT_PASSWORD** The wrong current password was provided
                         - **INVALID_NEW_PASSWORD_COMPLEXITY** The provided new password did not fulfill the password complexity rules
                      example: INVALID_NEW_PASSWORD_COMPLEXITY
                    description:
                      type: string
                      description: The translated errormessage.
                    technicalDescription:
                      type: string
                      description: A more detailed description of the error in English.
        '401':
          description: The user is not authenticated
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnAuthorizedErrorResponse'
        '403':
          description: Not authorized to perform action.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ForbiddenErrorResponse'
        '404':
          description: The item can not be found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotFoundErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InternalServerError'

  # *** Image ***
  /users/{id}/image:
    get:
      tags:
        - Image
      summary: Get a user's image.
      description: >-
        Get the image of a user identified by their ID. The requesting user
        must share access to a company with the target user.
      parameters:
        - name: id
          in: path
          description: The unique identifier of the user.
          required: true
          schema:
            type: string
        - name: width
          in: query
          description: >-
            Specifies the width in pixels for the image where it will be used.
            This helps select the most optimized size for the response.
          required: false
          schema:
            type: integer
        - name: imageType
          in: query
          description: >-
            Defines the type of image. Defaults to `WebAvatar`, which is
            currently the only supported value.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Image successfully retrieved.
          content:
            image/*:
              schema:
                type: string
                format: binary
        '204':
          description: No image is set for the user.
        '401':
          description: User is not authenticated.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnAuthorizedErrorResponse'
        '404':
          description: User not found.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotFoundErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InternalServerError'

  /me/image:
    get:
      tags:
        - Image
      summary: Get the user's image.
      description: Get the image of the currently authenticated user.
      parameters:
        - name: width
          in: query
          description: >-
            Specifies the width in pixels for the image where it will be used.
            This helps select the most optimized size for the response.
          required: false
          schema:
            type: integer
        - name: imageType
          in: query
          description: >-
            Specifies the type of image. Defaults to `WebAvatar`, which is
            currently the only supported value.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Image successfully retrieved.
          content:
            image/*:
              schema:
                type: string
                format: binary
        '204':
          description: No image is set for the user.
        '401':
          description: User is not authenticated.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnAuthorizedErrorResponse'
        '404':
          description: User not found in this region.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotFoundErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InternalServerError'

    put:
      tags:
        - Image
      summary: Update a user image.
      description: Update the image for the currently authenticated user.
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - image
                - mimeType
              properties:
                image:
                  type: string
                  description: >-
                    The image to be set as the user's avatar. Supported formats
                    include JPEG and PNG.
                  format: binary
                imageType:
                  type: string
                  description: >-
                    Specifies the type of image. Defaults to `WebAvatar`, which
                    is currently the only supported value.
                  example: WebAvatar
                mimeType:
                  type: string
                  description: >-
                    The MIME type of the image, e.g., `image/jpeg` or
                    `image/png`.
                  example: image/jpeg
      responses:
        '202':
          description: The request has been accepted for processing.
        '400':
          description: Invalid input provided.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BadRequestErrorResponse'
        '401':
          description: User is not authenticated.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnAuthorizedErrorResponse'
        '404':
          description: User not found in this region.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotFoundErrorResponse'
        '500':
          description: An unexpected error occurred.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InternalServerError'

    delete:
      tags:
        - Image
      summary: Delete the user's image.
      description: Delete the image of the currently authenticated user.
      parameters:
        - name: imageType
          in: query
          description: >-
            Specifies the type of image to delete. Defaults to `WebAvatar`,
            which is currently the only supported value.
          required: false
          schema:
            type: string
      responses:
        '204':
          description: The image was successfully deleted.
        '401':
          description: User is not authenticated.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnAuthorizedErrorResponse'
        '404':
          description: User not found in this region.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotFoundErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InternalServerError'


components:
  schemas:
    BadRequestErrorResponse:
      type: object
      properties:
        errorCode:
          type: string
          description: |
            Error code. Currently possible values:
             - **BAD_REQUEST** The provided request is invalid
             - **USERNAME_NOT_UNIQUE** There is already a user with the same username
          example: BAD_REQUEST
        description:
          type: string
          description: The translated errormessage.
        technicalDescription:
          type: string
          description: A more detailed description of the error in English.

    ForbiddenErrorResponse:
      type: object
      properties:
        errorCode:
          type: string
          description: |
            Error code. Currently possible values:
             - **FORBIDDEN** Not authorized to perform action
          example: FORBIDDEN
        description:
          type: string
          description: The translated errormessage.
        technicalDescription:
          type: string
          description: A more detailed description of the error in English.

    InternalServerError:
      type: object
      properties:
        errorCode:
          type: string
          description: |
            Error code. Possible values:
             - **INTERNAL_SERVER_ERROR** Unknown error
          example: INTERNAL_SERVER_ERROR
        description:
          type: string
          description: The translated errormessage.
        technicalDescription:
          type: string
          description: A more detailed description of the error in English.

    Metadata:
      type: object
      properties:
        offset:
          type: number
          description: >-
            The number of items to skip before starting to collect the result
            set.
        limit:
          type: number
          description: >-
            The maximum number of items in the collection resource response.
            Please note that there is always an upper bound to this property
            which may vary between different APIs and resources.
        total:
          type: number
          description: The total number of items in the collection.

    NotFoundErrorResponse:
      type: object
      properties:
        errorCode:
          type: string
          description: |
            Error code. Possible values:
             - **NOT_FOUND** The object can not be found
             - **NOT_AVAILABLE_IN_REGION** The object is not in current region
          example: NOT_FOUND
        description:
          type: string
          description: The translated errormessage.
        technicalDescription:
          type: string
          description: A more detailed description of the error in English.
        resourceUrl:
          type: string
          description: The URL to the resource if errorCode is NOT_AVAILABLE_IN_REGION.

    Region:
      type: object
      properties:
        id:
          type: string
          description: The name of the region
        baseUrl:
          type: string
          description: The base URL to the region where the user exists.

    Role:
      type: object
      properties:
        roleId:
          type: string
          description: Role id
        description:
          type: string
          description: The description of the role.

    RoleId:
      type: object
      properties:
        roleId:
          type: string
          description: Role id

    UnAuthorizedErrorResponse:
      type: object
      properties:
        errorCode:
          type: string
          description: |
            Error code. Possible values:
             - **UNAUTHORIZED** The authorization code is not active
          example: UNAUTHORIZED
        description:
          type: string
          description: The translated errormessage.
        technicalDescription:
          type: string
          description: A more detailed description of the error in English.

    User:
      type: object
      properties:
        id:
          type: string
        username:
          type: string
          description: The user's username
        fullName:
          type: string
          description: The user's full name
        email:
          type: string
          description: The user's email address
        phone:
          type: string
          description: The user's phone number
        locale:
          type: string
          description: 'The user''s locale, BCP 47 standard.'
        confirmed:
          type: boolean
          description: True if user has activated the account.
        active:
          type: boolean
          description: >-
            To become active a user must confirm its account. An active user
            may use Pagero's services. A user can be inactivated by its company
            admin. If not activated again the user will be removed after two
            years.
        userType:
          type: string
          description: The type of user. Can be for example Standard, CompanyIntegration or Temporary
          example: Standard
        region:
          $ref: '#/components/schemas/Region'

    UserForCreation:
      required:
        - companyId
        - email
        - fullName
        - username
      type: object
      properties:
        username:
          type: string
          description: The user's username
        fullName:
          type: string
          description: The user's full name
        email:
          type: string
          description: The user's email address
        phone:
          type: string
          description: The user's phone number
        companyId:
          type: string
          description: Id of a company the user should have access to
        locale:
          type: string
          description: 'The user''s locale, BCP 47 standard.'
        userType:
          type: string
          description: The type of user.

    UserForUpdating:
      required:
        - active
        - email
        - fullName
        - locale
        - username
      type: object
      properties:
        username:
          type: string
          description: The user's username
        fullName:
          type: string
          description: The user's full name
        email:
          type: string
          description: The user's email address
        phone:
          type: string
          description: The user's phone number
        locale:
          type: string
          description: 'The user''s locale, BCP 47 standard.'
        active:
          type: boolean
          description: If the user is active.
        userType:
          type: string
          description: The type of user.

    Users:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Metadata'
        users:
          type: array
          items:
            $ref: '#/components/schemas/User'