openapi: 3.2.0
info:
  title: Users API
  description: Operations for Users
  version: '1'
servers:
- url: https://sandbox-api.integrated.finance/v1/{instanceId}
  description: Sandbox
  variables: {}
- url: https://api.integrated.finance/v1/{instanceId}
  description: Production
  variables: {}
tags:
- name: Users
paths:
  /users:
    get:
      tags:
      - Users
      summary: List Users
      operationId: users.list
      parameters:
      - name: metadata.page.number
        in: query
        description: 0-indexed page number
        schema:
          minimum: 0
          type: integer
          format: int32
          default: 0
      - name: metadata.page.size
        in: query
        description: page size
        schema:
          maximum: 100
          minimum: 1
          type: integer
          format: int32
          default: 20
      - name: metadata.sort
        in: query
        description: default direction is ascending
        schema:
          type: string
        example: data.user.email,desc
      - name: data.user.email
        in: query
        schema:
          type: string
      - name: data.user.category
        in: query
        required: true
        schema:
          type: string
          enum:
          - external
      responses:
        '200':
          description: User list returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListPlatformResponse'
              example:
                workflow: {}
                data:
                  users:
                  - id: a0d58541-6c73-4aed-90ea-1eddc7b7413c
                    email: test.user@integrated.finance
                    givenName: Test
                    familyName: User
                    category: external
                    type: human
                    status: active
                connect: {}
                metadata:
                  page:
                    size: 10
                    number: 0
                    totalElements: 1
                    totalPages: 1
    post:
      tags:
      - Users
      summary: Create a User
      operationId: users.create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreateRequest'
            examples:
              human-external-invitation:
                description: human-external-invitation
                value:
                  workflow:
                    code: human.external.invitation
                  data:
                    user:
                      email: sherlock.holmes@integrated.finance
                      identity:
                        type: individual
                        givenName: Sherlock
                        familyName: Holmes
                    invitations:
                    - clientId: 00000000-0000-0000-0000-000000000000
                      userClientRelation: director
                  connect: {}
                  metadata: {}
              human-external-direct:
                description: human-external-direct
                value: '{  "workflow": {    "code": "human.external.direct"  },  "data": {    "user": {      "email": "sherlock.holmes@integrated.finance",      "identity": {        "type": "individual",        "givenName": "sherlock",        "familyName": "holmes",        "birthDate": "1991-01-14"      },      "profile": {        "phone": "+901234567890",        "residentialAddress": {          "country": "GB",          "region": "England",          "city": "London",          "street": "Baker Street",          "houseNumber": "221B",          "postalCode": "XYZ ABC",          "refinement": ""        }      }    }    "userClientRelations": [      {        "clientId": "00000000-0000-0000-0000-000000000000"      }    ]  },  "connect": {},  "metadata": {}}'
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserCreateResponse'
              examples:
                human-external-invitation:
                  description: human-external-invitation
                  value:
                    workflow:
                      code: human.external.invitation
                    data:
                      user:
                        email: sherlock.holmes@integrated.finance
                        identity:
                          type: individual
                          givenName: Sherlock
                          familyName: Holmes
                      invitations:
                      - id: 00000000-0000-0000-0000-000000000000
                        clientId: 00000000-0000-0000-0000-000000000000
                        status: pending
                        userClientRelation: director
                    connect: {}
                    metadata: {}
                human-external-direct:
                  description: human-external-direct
                  value:
                    workflow:
                      code: human.external.direct
                    data:
                      user:
                        email: sherlock.holmes@integrated.finance
                        identity:
                          type: individual
                          givenName: sherlock
                          familyName: holmes
                          birthDate: '1991-01-14'
                        profile:
                          phone: '+901234567890'
                          residentialAddress:
                            country: GB
                            region: England
                            city: London
                            street: Baker Street
                            houseNumber: 221B
                            postalCode: XYZ ABC
                            refinement: ''
                        category: external
                        type: human
                        status: active
                      userClientRelations:
                      - id: 00000000-0000-0000-0000-000000000000
                        userId: 00000000-0000-0000-0000-000000000000
                        clientId: 00000000-0000-0000-0000-000000000000
                        status: allowed
                    connect: {}
                    metadata: {}
  /users/{id}:
    get:
      tags:
      - Users
      summary: Get a User
      operationId: users.get
      parameters:
      - name: id
        in: path
        description: ID of the user in UUID format
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: User resource returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGetResponse'
              example:
                workflow: {}
                data:
                  user:
                    id: 00000000-0000-0000-0000-000000000000
                    email: test.user@integrated.finance
                    identity:
                      type: individual
                      givenName: sherlock
                      familyName: holmes
                    category: external
                    type: human
                    status: active
                connect: {}
                metadata: {}
    patch:
      tags:
      - Users
      summary: Update a User
      operationId: users.update
      parameters:
      - name: id
        in: path
        description: ID of user in UUID format
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdateRequest'
            examples:
              direct-status-update:
                description: direct-status-update
                value:
                  workflow:
                    code: direct
                  data:
                    user:
                      status: inactive
                  connect: {}
                  metadata: {}
              direct-identity-update:
                description: direct-identity-update
                value:
                  workflow:
                    code: direct
                  data:
                    user:
                      identity:
                        givenName: sherlock
                        familyName: holmes
                        birthDate: '1991-01-14'
                  connect: {}
                  metadata: {}
      responses:
        '202':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserUpdateResponse'
              examples:
                direct-status-update:
                  description: direct-status-update
                  value:
                    workflow:
                      code: direct
                    data:
                      user:
                        id: 00000000-0000-0000-0000-000000000000
                        email: test.user@integrated.finance
                        identity:
                          type: individual
                          givenName: sherlock
                          familyName: holmes
                          birthDate: '1991-01-15'
                        category: external
                        type: human
                        status: inactive
                    connect: {}
                    metadata: {}
                direct-identity-update:
                  description: direct-identity-update
                  value:
                    workflow:
                      code: direct
                    data:
                      user:
                        id: 00000000-0000-0000-0000-000000000000
                        email: test.user@integrated.finance
                        identity:
                          type: individual
                          givenName: sherlock
                          familyName: holmes
                          birthDate: '1991-01-15'
                        category: external
                        type: human
                        status: active
                    connect: {}
                    metadata: {}
components:
  schemas:
    UserCreateWorkflow:
      type: string
      description: unique workflow code
      enum:
      - human.external.invitation
      - human.external.direct
    UserUpdateResponse:
      required:
      - connect
      - data
      - metadata
      - workflow
      type: object
      properties:
        workflow:
          $ref: '#/components/schemas/UserUpdateWorkflowContainer'
        data:
          $ref: '#/components/schemas/UserUpdateDataContainer'
        connect:
          $ref: '#/components/schemas/UserUpdateConnectContainer'
        metadata:
          $ref: '#/components/schemas/UserUpdateMetadataContainer'
    BankingUserProfile:
      type: object
      properties:
        phone:
          type: string
        residentialAddress:
          $ref: '#/components/schemas/Address'
    UserCreateConnectContainer:
      type: object
    UserListPlatformDataContainer:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/UserListPlatformQueryInput'
        users:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/User'
    LegalEntityIdentityIndividual:
      required:
      - familyName
      - givenName
      type: object
      properties:
        type:
          $ref: '#/components/schemas/LegalEntityType'
        country:
          maxLength: 2
          minLength: 2
          pattern: ^[A-Z]{2}$
          type: string
        identifications:
          type: array
          items:
            $ref: '#/components/schemas/LegalEntityIdentification'
        givenName:
          type: string
        familyName:
          type: string
        birthDate:
          type: string
          format: date
    UserCreateRequest:
      required:
      - connect
      - data
      - metadata
      - workflow
      type: object
      properties:
        workflow:
          $ref: '#/components/schemas/UserCreateWorkflowContainer'
        data:
          $ref: '#/components/schemas/UserCreateDataContainer'
        connect:
          $ref: '#/components/schemas/UserCreateConnectContainer'
        metadata:
          $ref: '#/components/schemas/UserCreateMetadataContainer'
    UserClientStatus:
      type: string
      readOnly: true
      enum:
      - allowed
      - revoked
    BankingUserStatus:
      type: string
      readOnly: true
      enum:
      - active
      - inactive
    UserUpdateRequest:
      required:
      - connect
      - data
      - metadata
      - workflow
      type: object
      properties:
        workflow:
          $ref: '#/components/schemas/UserUpdateWorkflowContainer'
        data:
          $ref: '#/components/schemas/UserUpdateDataContainer'
        connect:
          $ref: '#/components/schemas/UserUpdateConnectContainer'
        metadata:
          $ref: '#/components/schemas/UserUpdateMetadataContainer'
    UserGetConnectContainer:
      type: object
    UserListPlatformQueryInput:
      type: object
      properties:
        title:
          type: string
        email:
          type: array
          items:
            type: string
        userCategory:
          $ref: '#/components/schemas/UserCategory'
        category:
          $ref: '#/components/schemas/UserCategory'
      writeOnly: true
    UserCreateMetadataContainer:
      type: object
    UserUpdateDataContainer:
      required:
      - user
      type: object
      properties:
        user:
          $ref: '#/components/schemas/User'
    UserCreateWorkflowContainer:
      required:
      - code
      type: object
      properties:
        code:
          $ref: '#/components/schemas/UserCreateWorkflow'
    UserGetDataContainer:
      required:
      - user
      type: object
      properties:
        user:
          $ref: '#/components/schemas/User'
    UserCreateDataContainer:
      required:
      - user
      type: object
      properties:
        user:
          $ref: '#/components/schemas/User'
        invitations:
          type: array
          items:
            $ref: '#/components/schemas/UserInvitation'
        userClientRelations:
          type: array
          items:
            $ref: '#/components/schemas/UserClientRelation'
    UserListMetadataContainer:
      required:
      - page
      type: object
      properties:
        page:
          $ref: '#/components/schemas/PageMetadata'
    UserCreateResponse:
      required:
      - connect
      - data
      - metadata
      - workflow
      type: object
      properties:
        workflow:
          $ref: '#/components/schemas/UserCreateWorkflowContainer'
        data:
          $ref: '#/components/schemas/UserCreateDataContainer'
        connect:
          $ref: '#/components/schemas/UserCreateConnectContainer'
        metadata:
          $ref: '#/components/schemas/UserCreateMetadataContainer'
    UserUpdateWorkflowContainer:
      required:
      - code
      type: object
      properties:
        code:
          type: string
          description: workflow code
          enum:
          - direct
    UserListPlatformResponse:
      required:
      - connect
      - data
      - metadata
      - workflow
      type: object
      properties:
        workflow:
          $ref: '#/components/schemas/UserListPlatformWorkflowContainer'
        data:
          $ref: '#/components/schemas/UserListPlatformDataContainer'
        connect:
          $ref: '#/components/schemas/UserListConnectContainer'
        metadata:
          $ref: '#/components/schemas/UserListMetadataContainer'
    UserListConnectContainer:
      type: object
    Address:
      required:
      - city
      - country
      - street
      type: object
      properties:
        country:
          maxLength: 2
          minLength: 2
          pattern: ^[A-Z]{2}$
          type: string
        region:
          type: string
        postalCode:
          type: string
        city:
          type: string
        street:
          type: string
        houseNumber:
          type: string
        refinement:
          type: string
    UserInvitationStatus:
      type: string
      description: status of invitation
      readOnly: true
      enum:
      - accepted
      - pending
      - rejected
      - cancelled
    UserListPlatformWorkflowContainer:
      type: object
    LegalEntityType:
      type: string
      enum:
      - corporate
      - individual
    UserCategory:
      type: string
      enum:
      - internal
      - external
    UserClientRelation:
      required:
      - clientId
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        userId:
          type: string
          format: uuid
          readOnly: true
        clientId:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/UserClientStatus'
    UserGetWorkflowContainer:
      type: object
    PageMetadata:
      required:
      - number
      - size
      - totalElements
      - totalPages
      type: object
      properties:
        size:
          minimum: 0
          type: integer
          description: number of elements in this page
          format: int32
        number:
          minimum: 0
          type: integer
          description: index of page starting from 0
          format: int32
        totalElements:
          minimum: 0
          type: integer
          description: total number of elements in all of the pages
          format: int64
          readOnly: true
        totalPages:
          minimum: 0
          type: integer
          description: number of total pages
          format: int32
          readOnly: true
    UserUpdateConnectContainer:
      type: object
    User:
      required:
      - category
      - email
      - identity
      - type
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        email:
          type: string
        givenName:
          type: string
        familyName:
          type: string
        identity:
          $ref: '#/components/schemas/LegalEntityIdentityIndividual'
        category:
          type: string
          readOnly: true
          enum:
          - external
        type:
          type: string
          readOnly: true
          enum:
          - human
        profile:
          $ref: '#/components/schemas/BankingUserProfile'
        status:
          $ref: '#/components/schemas/BankingUserStatus'
      readOnly: true
    UserUpdateMetadataContainer:
      type: object
    LegalEntityIdentification:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/LegalEntityIdentificationType'
        identificationNumber:
          type: string
        issuingCountry:
          maxLength: 2
          minLength: 2
          pattern: ^[A-Z]{2}$
          type: string
        issueDate:
          type: string
          format: date
        expirationDate:
          type: string
          format: date
    UserGetResponse:
      required:
      - connect
      - data
      - metadata
      - workflow
      type: object
      properties:
        workflow:
          $ref: '#/components/schemas/UserGetWorkflowContainer'
        data:
          $ref: '#/components/schemas/UserGetDataContainer'
        connect:
          $ref: '#/components/schemas/UserGetConnectContainer'
        metadata:
          $ref: '#/components/schemas/UserGetMetadataContainerModel'
    LegalEntityIdentificationType:
      type: string
      enum:
      - registration-number
      - passport
      - identity-card
      - driving-licence
      - foreign-identity-card
      - tax-number
    UserInvitation:
      required:
      - clientId
      - id
      - status
      - userClientRelation
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        clientId:
          type: string
          format: uuid
        userClientRelation:
          $ref: '#/components/schemas/UserClientRelationType'
        status:
          $ref: '#/components/schemas/UserInvitationStatus'
    UserGetMetadataContainerModel:
      type: object
    UserClientRelationType:
      type: string
      description: user's relation with client
      enum:
      - director
      - shareholder
      - director-and-shareholder
      - authorized-person
x-provenance:
  method: searched
  source: https://developer.integrated.finance/reference
  harvested: '2026-10-14'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://developer.integrated.finance/reference/user-client-relationscreate.md
  - https://developer.integrated.finance/reference/user-client-relationsget.md
  - https://developer.integrated.finance/reference/user-client-relationslist.md
  - https://developer.integrated.finance/reference/user-client-relationsupdate.md
  - https://developer.integrated.finance/reference/user-invitationsget.md
  - https://developer.integrated.finance/reference/user-invitationsupdate.md
  - https://developer.integrated.finance/reference/userscreate.md
  - https://developer.integrated.finance/reference/usersget.md
  - https://developer.integrated.finance/reference/userslist.md
  - https://developer.integrated.finance/reference/userslist_1.md
  - https://developer.integrated.finance/reference/usersupdate.md
  merge:
    pages: 11
    deduped: 43
    conflicts_kept_first: 0