openapi: 3.0.1
info:
  title: Users
  version: 2.10.0
  description: REST API for users management.
  contact:
    name: Tradevest GmbH
    url: https://tradevest.ai
    email: hello@tradevest.ai
servers:
  - url: https://tvda-api.platform-test.tradevest.ai
    description: Test
security:
  - Bearer: []
tags:
  - name: Users
    description: Users domain
paths:
  /users:
    post:
      summary: Create User
      operationId: create-user
      x-operation-group: users-command
      x-required-permissions: rs/users/write
      description: |-
        Create a user. Provided email needs to be unique.

        Data provided will be used to create credentials to access Partner Panel. Specifically, provided
        email will be used to identify created account. This means that email needs to be unique.
      tags:
        - Users
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateUserResult'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserData'
    get:
      summary: Get Users
      operationId: get-users
      x-operation-group: users-query
      x-required-permissions: rs/query/read
      description: Get list of users
      tags:
        - Users
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Users'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      parameters:
        - schema:
            type: string
          in: query
          name: cursor
          description: String value used for pagination
        - schema:
            type: integer
            minimum: 1
            default: 20
          in: query
          name: limit
          description: Maximum number of items to return
          required: true
        - schema:
            $ref: '#/components/schemas/UserTypeEnum'
          in: query
          name: userType
          description: User type filter
        - schema:
            $ref: '#/components/schemas/UserStatusEnum'
          in: query
          name: userStatus
          description: User status filter
        - schema:
            type: string
          in: query
          name: firstName
          description: String value used for firstName
          required: false
        - schema:
            type: string
          in: query
          name: lasttName
          description: String value used for lastName
          required: false
        - schema:
            type: string
          in: query
          name: email
          description: String value used for email
          required: false
        - schema:
            type: string
          in: query
          name: userId
          description: Uuid value used for userId
          required: false
        - schema:
            type: string
          in: query
          name: globalId
          description: String value used for globalId
          required: false
  /users/{userId}:
    parameters:
      - schema:
          type: string
          format: uuid
        name: userId
        in: path
        required: true
        description: User ID
    get:
      summary: Get User
      operationId: get-user
      x-operation-group: users-query
      x-required-permissions: rs/query/read
      description: Get user
      tags:
        - Users
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserExtended'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
    patch:
      summary: Update User
      operationId: update-user
      x-operation-group: users-command
      x-required-permissions: rs/users/write
      description: Update user
      tags:
        - Users
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdate'
  /users/{userId}/reset-password:
    parameters:
      - schema:
          type: string
          format: uuid
        name: userId
        in: path
        required: true
        description: User ID
    get:
      summary: Reset user password
      operationId: reset-user-password
      x-operation-group: users-command
      x-required-permissions: rs/users/write
      description: Resend email with initial password if it is expired.
      tags:
        - Users
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
  /v2/users/reset-password:
    post:
      summary: Reset user password
      x-with-authentication: false
      operationId: reset-user-password-v2
      x-operation-group: users-command
      description: Resend email with initial password if it is expired.
      tags:
        - Users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetPasswordRequest'
        required: true
      responses:
        '202':
          description: Accepted
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
  /user-onboardings:
    post:
      summary: Start User Onboarding
      operationId: start-user-onboarding
      x-operation-group: users-command
      x-required-permissions: rs/users/write
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartUserOnboardingResult'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserOnboardingData'
      tags:
        - Users
    get:
      summary: Get User Onboardings
      operationId: get-user-onboardings
      x-operation-group: users-query
      x-required-permissions: rs/query/read
      parameters:
        - schema:
            type: string
            format: uuid
          name: userId
          in: query
          required: true
          description: Unique identification number of onboarded user type in UUID format.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserOnboarding'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      tags:
        - Users
  /user-onboardings/{onboardingId}:
    parameters:
      - schema:
          type: string
          format: uuid
        name: onboardingId
        in: path
        required: true
        description: Unique onboarding identification number in UUID format
    get:
      summary: Get User Onboarding
      operationId: get-user-onboarding
      x-operation-group: users-query
      x-required-permissions: rs/query/read
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserOnboarding'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      tags:
        - Users
components:
  schemas:
    UserData:
      title: UserData
      type: object
      properties:
        gender:
          $ref: '#/components/schemas/GenderEnum'
        firstName:
          type: string
          maxLength: 255
          pattern: ^\S+( \S+)*$
          description: All first names of the person according to the identification document
        lastName:
          type: string
          maxLength: 255
        birthDay:
          type: string
          format: date
        birthPlace:
          type: string
          maxLength: 255
        birthCountry:
          $ref: '#/components/schemas/CountryEnum'
        nationalities:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/CountryEnum'
        mainAddress:
          $ref: '#/components/schemas/Address'
        contact:
          $ref: '#/components/schemas/Contact'
        type:
          $ref: '#/components/schemas/UserTypeEnum'
      required:
        - gender
        - firstName
        - lastName
        - birthDay
        - birthPlace
        - birthCountry
        - nationalities
        - mainAddress
        - contact
        - type
    UserUpdate:
      title: UserUpdate
      type: object
      properties:
        lastName:
          type: string
          maxLength: 255
        nationalities:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/CountryEnum'
        mainAddress:
          $ref: '#/components/schemas/Address'
        contact:
          $ref: '#/components/schemas/ContactUpdate'
        status:
          $ref: '#/components/schemas/UserStatusUpdateEnum'
        mfaType:
          $ref: '#/components/schemas/UserMFATypeUpdateEnum'
    CreateUserResult:
      title: CreateUserResult
      type: object
      properties:
        userId:
          type: string
          format: uuid
          description: Unique user identification number in UUID format
          readOnly: true
      required:
        - userId
    UserExtended:
      type: object
      properties:
        mfaType:
          $ref: '#/components/schemas/UserMfaTypeEnum'
        userId:
          type: string
          format: uuid
          description: Unique identification number in UUID format
          readOnly: true
        globalId:
          type: string
          minLength: 12
          maxLength: 12
          description: Global ID of the user
        status:
          $ref: '#/components/schemas/UserStatusEnum'
        createdOn:
          type: string
          format: date-time
          description: The date of creation
          readOnly: true
        modifiedOn:
          type: string
          format: date-time
          description: The date of last modification
          readOnly: true
        gender:
          $ref: '#/components/schemas/GenderEnum'
        firstName:
          type: string
          maxLength: 255
          pattern: ^\S+( \S+)*$
          description: All first names of the person according to the identification document
        lastName:
          type: string
          maxLength: 255
        birthDay:
          type: string
          format: date
        birthPlace:
          type: string
          maxLength: 255
        birthCountry:
          $ref: '#/components/schemas/CountryEnum'
        nationalities:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/CountryEnum'
        mainAddress:
          $ref: '#/components/schemas/Address'
        contact:
          $ref: '#/components/schemas/Contact'
        type:
          $ref: '#/components/schemas/UserTypeEnum'
      required:
        - birthCountry
        - birthDay
        - birthPlace
        - contact
        - createdOn
        - firstName
        - gender
        - globalId
        - lastName
        - mainAddress
        - mfaType
        - modifiedOn
        - nationalities
        - status
        - type
        - userId
      title: UserExtended
    User:
      type: object
      properties:
        userId:
          type: string
          format: uuid
          description: Unique identification number in UUID format
          readOnly: true
        globalId:
          type: string
          minLength: 12
          maxLength: 12
          description: Global ID of the user
        status:
          $ref: '#/components/schemas/UserStatusEnum'
        createdOn:
          type: string
          format: date-time
          description: The date of creation
          readOnly: true
        modifiedOn:
          type: string
          format: date-time
          description: The date of last modification
          readOnly: true
        gender:
          $ref: '#/components/schemas/GenderEnum'
        firstName:
          type: string
          maxLength: 255
          pattern: ^\S+( \S+)*$
          description: All first names of the person according to the identification document
        lastName:
          type: string
          maxLength: 255
        birthDay:
          type: string
          format: date
        birthPlace:
          type: string
          maxLength: 255
        birthCountry:
          $ref: '#/components/schemas/CountryEnum'
        nationalities:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/CountryEnum'
        mainAddress:
          $ref: '#/components/schemas/Address'
        contact:
          $ref: '#/components/schemas/Contact'
        type:
          $ref: '#/components/schemas/UserTypeEnum'
      required:
        - birthCountry
        - birthDay
        - birthPlace
        - contact
        - createdOn
        - firstName
        - gender
        - globalId
        - lastName
        - mainAddress
        - modifiedOn
        - nationalities
        - status
        - type
        - userId
      title: User
    Users:
      title: Users
      type: object
      properties:
        data:
          type: array
          description: Array of users
          items:
            $ref: '#/components/schemas/User'
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
        - data
        - pagination
    GenderEnum:
      title: GenderEnum
      type: string
      description: Gender
      enum:
        - MALE
        - FEMALE
        - DIVERSE
    Contact:
      title: Contact
      type: object
      description: ⚠️ **Important Note on Partial Updates:** Although update endpoints use the `PATCH` method, the `contact` object requires a **full representation** of the data. If optional fields (such as `fax` or `website`) are omitted from the request, they will be overwritten with `null` in the database. To preserve existing data, ensure all current contact values are included in your request payload.
      x-examples:
        Example 1:
          phone: +49 30 087324980
          email: mila_schoenherr@hotmail.com
          fax: +49 30 108612836
          website: string.string
      properties:
        phone:
          type: string
          description: Mobile telephone number
          pattern: ^\+[1-9][0-9]{0,24}$
        email:
          type: string
          description: E-mail address
          maxLength: 255
          pattern: ^[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$
        fax:
          type: string
          description: Fax number
          minLength: 3
          maxLength: 20
          pattern: ^[\+\-\(\)\d ]{3,20}$
        website:
          type: string
          description: website address
          maxLength: 320
      required:
        - phone
        - email
    ContactUpdate:
      title: ContactUpdate
      type: object
      description: ⚠️ **Important Note on Partial Updates:** Although this endpoint uses the `PATCH` method, the `contact` object requires a **full representation** of the data. If optional fields (such as `fax` or `website`) are omitted from the request, they will be overwritten with `null` in the database. To preserve existing data, ensure all current contact values are included in your request payload.
      x-examples:
        Example 1:
          phone: +49 30 087324980
          fax: +49 30 108612836
          website: string.string
      properties:
        phone:
          type: string
          description: Mobile telephone number
          pattern: ^\+[1-9][0-9]{0,24}$
        fax:
          type: string
          description: Fax number
          minLength: 3
          maxLength: 20
          pattern: ^[\+\-\(\)\d ]{3,20}$
        website:
          type: string
          description: website address
          maxLength: 320
      required:
        - phone
    ResetPasswordRequest:
      title: ResetPasswordRequest
      type: object
      properties:
        email:
          type: string
          description: E-mail address
          maxLength: 255
          pattern: ^[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$
      required:
        - email
    Address:
      title: Address
      type: object
      description: Address
      x-examples:
        Example 1:
          street: Papenhuder Strasse
          streetNumber: '24'
          city: Hamburg
          zip: '22087'
          country: DE
          additionalInfo: address additional info
      properties:
        street:
          type: string
          maxLength: 255
        streetNumber:
          type: string
          maxLength: 20
        city:
          type: string
          maxLength: 255
        zip:
          type: string
          minLength: 3
          maxLength: 12
        state:
          type: string
          minLength: 1
          maxLength: 35
        country:
          $ref: '#/components/schemas/CountryEnum'
        additionalInfo:
          type: string
      required:
        - street
        - streetNumber
        - city
        - zip
        - country
    UserTypeEnum:
      title: UserTypeEnum
      type: string
      enum:
        - ADMIN
    UserMfaTypeEnum:
      title: UserMfaTypeEnum
      type: string
      enum:
        - SMS
        - TOKEN
    UserMFATypeUpdateEnum:
      title: UserMFATypeUpdateEnum
      description: Sending request with `SMS` will switch MFA to SMS until the next time user login. After that method will be switched to TOTP again.
      type: string
      enum:
        - SMS
    UserStatusEnum:
      title: UserStatusEnum
      type: string
      enum:
        - RECEIVED
        - INVALID
        - CREATED
        - ACTIVE
        - REJECTED
        - SUSPENDED
        - INACTIVE
      description: Current customer status
      readOnly: true
    UserStatusUpdateEnum:
      title: UserStatusUpdateEnum
      description: Update to INACTIVE or SUSPENDED is possible only from ACTIVE status. It will disable user access to API. Update to ACTIVE is possible only from SUSPENDED. It will enable user access to API.
      type: string
      enum:
        - INACTIVE
        - SUSPENDED
        - ACTIVE
    StartUserOnboardingResult:
      title: StartUserOnboardingResult
      type: object
      properties:
        onboardingId:
          type: string
          format: uuid
          readOnly: true
      required:
        - onboardingId
    UserOnboardingData:
      title: UserOnboardingData
      type: object
      properties:
        userId:
          type: string
          format: uuid
      required:
        - userId
    UserOnboarding:
      title: UserOnboarding
      properties:
        onboardingId:
          type: string
          format: uuid
          readOnly: true
        status:
          $ref: '#/components/schemas/UserOnboardingStatusEnum'
        userId:
          type: string
          format: uuid
        createdOn:
          type: string
          format: date-time
          readOnly: true
        modifiedOn:
          type: string
          format: date-time
          readOnly: true
      required:
        - onboardingId
        - status
        - userId
        - createdOn
        - modifiedOn
    UserOnboardingStatusEnum:
      title: UserOnboardingStatusEnum
      type: string
      enum:
        - CREATED
        - PENDING
        - APPROVED
        - REJECTED
        - RECEIVED
        - INVALID
      readOnly: true
    CountryEnum:
      title: CountryEnum
      type: string
      description: Country code in **ISO 3166-1 alpha-2** standard
      enum:
        - AF
        - AX
        - AL
        - DZ
        - AS
        - AD
        - AO
        - AI
        - AQ
        - AG
        - AR
        - AM
        - AW
        - AU
        - AT
        - AZ
        - BS
        - BH
        - BD
        - BB
        - BY
        - BE
        - BZ
        - BJ
        - BM
        - BT
        - BO
        - BQ
        - BA
        - BW
        - BV
        - BR
        - VG
        - IO
        - BN
        - BG
        - BF
        - BI
        - KH
        - CM
        - CA
        - CV
        - KY
        - CF
        - TD
        - CL
        - CN
        - HK
        - MO
        - CX
        - CC
        - CO
        - KM
        - CG
        - CD
        - CK
        - CR
        - CI
        - HR
        - CU
        - CW
        - CY
        - CZ
        - DK
        - DJ
        - DM
        - DO
        - EC
        - EG
        - SV
        - GQ
        - ER
        - EE
        - ET
        - FK
        - FO
        - FJ
        - FI
        - FR
        - GF
        - PF
        - TF
        - GA
        - GM
        - GE
        - DE
        - GH
        - GI
        - GR
        - GL
        - GD
        - GP
        - GU
        - GT
        - GG
        - GN
        - GW
        - GY
        - HT
        - HM
        - VA
        - HN
        - HU
        - IS
        - IN
        - ID
        - IR
        - IQ
        - IE
        - IM
        - IL
        - IT
        - JM
        - JP
        - JE
        - JO
        - KZ
        - KE
        - KI
        - KP
        - KR
        - KW
        - KG
        - LA
        - LV
        - LB
        - LS
        - LR
        - LY
        - LI
        - LT
        - LU
        - MK
        - MG
        - MW
        - MY
        - MV
        - ML
        - MT
        - MH
        - MQ
        - MR
        - MU
        - YT
        - MX
        - FM
        - MD
        - MC
        - MN
        - ME
        - MS
        - MA
        - MZ
        - MM
        - NA
        - NR
        - NP
        - NL
        - AN
        - NC
        - NZ
        - NI
        - NE
        - NG
        - NU
        - NF
        - MP
        - 'NO'
        - OM
        - PK
        - PW
        - PS
        - PA
        - PG
        - PY
        - PE
        - PH
        - PN
        - PL
        - PT
        - PR
        - QA
        - RE
        - RO
        - RU
        - RW
        - BL
        - SH
        - KN
        - LC
        - MF
        - PM
        - VC
        - WS
        - SM
        - ST
        - SA
        - SN
        - RS
        - SC
        - SL
        - SG
        - SX
        - SK
        - SI
        - SB
        - SO
        - ZA
        - GS
        - SS
        - ES
        - LK
        - SD
        - SR
        - SJ
        - SZ
        - SE
        - CH
        - SY
        - TW
        - TJ
        - TZ
        - TH
        - TL
        - TG
        - TK
        - TO
        - TT
        - TN
        - TR
        - TM
        - TC
        - TV
        - UG
        - UA
        - AE
        - GB
        - US
        - UM
        - UY
        - UZ
        - VU
        - VE
        - VN
        - VI
        - WF
        - EH
        - YE
        - ZM
        - ZW
        - XK
    Pagination:
      title: Pagination
      type: object
      properties:
        cursor:
          type: string
          description: String value used for pagination, which should be set in next page request.
        limit:
          type: integer
          description: Maximum number of returned items
      required:
        - cursor
        - limit
    ErrorDetailsExplanation:
      title: ErrorDetailsExplanation
      type: object
      properties:
        code:
          type: string
          maxLength: 255
        parameter:
          type: string
        message:
          type: string
      required:
        - code
        - message
    ErrorDetails:
      title: ErrorDetails
      type: object
      properties:
        field:
          type: string
          maxLength: 255
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetailsExplanation'
      required:
        - field
    ErrorMessage:
      title: ErrorMessage
      type: object
      properties:
        message:
          type: string
        responseType:
          type: string
        validationString:
          minLength: 1
          type: string
        requestId:
          type: string
        errorCode:
          type: string
          maxLength: 255
        errorDetails:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetails'
      required:
        - message
        - responseType
        - requestId
  securitySchemes:
    Bearer:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth2/token
          scopes: {}
x-tagGroups:
  - name: User Management
    tags:
      - Users
