BanQu User Profile API

openapi: 3.2.0
info:
  title: BanQu User Profile API
  version: 3.3.4
  description: The BanQu API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP verbs, which can be understood by off-the-shelf HTTP clients, and [JSON](http://www.json.org) for input and output.
servers:
- url: https://banqu.app:443/api/v1
security:
- Bearer: []
tags:
- name: User Profile
paths:
  /profile:
    get:
      description: Get logged in user profile
      tags:
      - User Profile
      responses:
        '200':
          description: User profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExistentProfile'
        '401':
          $ref: '#/components/responses/401'
    patch:
      description: Modify logged in user profile
      tags:
      - User Profile
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExistentProfile'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExistentProfile'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
  /profile/password:
    post:
      description: Update logged in user password
      tags:
      - User Profile
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                oldPassword:
                  type: string
                password:
                  type: string
      responses:
        '200':
          description: Password changed successfully
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
  /profile/photo:
    get:
      description: Get logged in user photo
      tags:
      - User Profile
      responses:
        '302':
          description: Redirect to the Photo url
          headers:
            Location:
              schema:
                type: string
              description: Photo URL
        '404':
          $ref: '#/components/responses/404'
    post:
      description: Update logged in user photo
      tags:
      - User Profile
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: string
              format: binary
      responses:
        '201':
          $ref: '#/components/responses/201'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
  /profile/sections:
    get:
      description: List logged in user profile sections
      tags:
      - User Profile
      responses:
        '200':
          description: List of profile sections
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileSectionsList'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
  /profile/standard:
    get:
      description: List standard profile sections
      tags:
      - User Profile
      responses:
        '200':
          description: List of profile sections
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileSectionsList'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
  /profile/forms:
    get:
      description: List profile section forms
      tags:
      - User Profile
      responses:
        '200':
          description: List of profile forms
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Form'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
  /profile/forms/{formId}:
    get:
      description: Get profile section form details
      parameters:
      - name: formId
        description: FormId from profile section
        in: path
        schema:
          type: string
        required: true
      tags:
      - User Profile
      responses:
        '200':
          description: Profile form template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Form'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
components:
  schemas:
    FormFieldWithItems:
      title: Form Field with Items
      type: object
      properties:
        $entityId:
          type: string
          description: Internal unique identifier for the field
        name:
          $ref: '#/components/schemas/JsonNestedIdentifier'
        type:
          type: string
          enum:
          - select
          - multiSelect
          - radio
        displayAs:
          type: string
          enum:
          - dropdown
          - list
        title:
          $ref: '#/components/schemas/LocalizedString'
        description:
          $ref: '#/components/schemas/OptionalLocalizedString'
        descriptionVariant:
          $ref: '#/components/schemas/DescriptionVariant'
        required:
          type: boolean
        validation:
          type: string
        parentFieldName:
          $ref: '#/components/schemas/ParentFieldName'
        items:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Internal unique identifier for the item
              title:
                $ref: '#/components/schemas/OptionalLocalizedString'
              value:
                type: string
              weight:
                type: number
                minimum: -1
                description: A numerical value representing the importance of this item in the overall score calculation. Higher values indicate greater importance.
              frozen:
                type: boolean
                description: Indicates if the item is frozen and cannot be modified
              parentValue:
                type: string
                description: Value of a parent field that this item belongs to. Used to filter items in a select field based on the parent field value
            required:
            - value
            additionalProperties: false
        allowOther:
          type: boolean
        visibility:
          $ref: '#/components/schemas/FormElementVisibility'
        primary:
          type: boolean
          description: Whether field is a primary key or part of a primary key. Primary key values should be unique across multiple form data entries of a same user
        globalPrimary:
          type: boolean
          description: Whether field is a primary key or part of a primary key. Primary key values should be unique across multiple form data entries of a same user
        uniqueAcrossInstances:
          type: boolean
          description: Unique across section instances when form section is repeatable
        size:
          type: integer
          description: The number of slots preserved for the field in a table column
          minimum: 1
          maximum: 12
        displayTotals:
          type: boolean
          description: When enabled, the sum of all field values is displayed in the totals row on the UI
        weight:
          type: number
          description: A numerical value representing the importance of this field in the overall score calculation. Higher values indicate greater importance.
        isParent:
          type: boolean
          description: Mark the selected connection as a parent of the data entry
        importanceArea:
          $ref: '#/components/schemas/FormFieldImportance'
        frozen:
          type: boolean
          readOnly: true
      required:
      - name
      - type
      - title
      - required
    FormGroup:
      type: object
      properties:
        id:
          type: string
        title:
          $ref: '#/components/schemas/OptionalLocalizedString'
        parentId:
          type: string
          description: Identifier of the group this sub-group belongs to
        weight:
          type: number
          minimum: 0
          description: A numerical value representing the importance of this field in the overall score calculation. Higher values indicate greater importance.
        threshold:
          type: number
          minimum: 0
          description: A specific value that the score must meet or exceed for a particular action or decision to be triggered.
      additionalProperties: false
      required:
      - id
    FormMarkupElement:
      title: Form Markup Element
      type: object
      required:
      - title
      - type
      properties:
        type:
          type: string
          enum:
          - legend
          - static
        url:
          type: string
          format: url
        title:
          $ref: '#/components/schemas/LocalizedString'
        description:
          $ref: '#/components/schemas/OptionalLocalizedString'
        visibility:
          $ref: '#/components/schemas/FormElementVisibility'
        $entityId:
          type: string
        requiredIf:
          type: string
        visibleIf:
          type: string
      additionalProperties: false
    FormSection:
      title: Form Section
      type: object
      properties:
        $entityId:
          type: string
          description: Internal unique identifier for the section
        title:
          $ref: '#/components/schemas/OptionalLocalizedString'
        description:
          $ref: '#/components/schemas/OptionalLocalizedString'
        name:
          $ref: '#/components/schemas/JsonIdentifier'
        multiple:
          type: boolean
          description: If multiple instances of the section are allowed
        required:
          type: boolean
          description: If at least one of the section instances is required
        requiredIf:
          type: string
        visibleIf:
          type: string
        weight:
          type: number
          description: A numerical value representing the importance of this field in the overall score calculation. Higher values indicate greater importance.
        threshold:
          type: number
          minimum: 0
          description: A specific value that the score must meet or exceed for a particular action or decision to be triggered.
        layout:
          type: string
          description: Section markup layout
          enum:
          - horizontal
          - vertical
          - table
        fields:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/FormField'
            - $ref: '#/components/schemas/CheckboxField'
            - $ref: '#/components/schemas/FormFieldWithItems'
            - $ref: '#/components/schemas/FormMarkupElement'
            - $ref: '#/components/schemas/FragmentField'
        groupId:
          type: string
          description: Identifier of the group this section belongs to
        frozen:
          type: boolean
          readOnly: true
      required:
      - fields
    JsonIdentifier:
      type: string
      description: JSON field name
      pattern: ^[$a-zA-Z_][\da-zA-Z_]*$
    ParentFieldName:
      type: string
      pattern: ^[a-zA-Z_][\da-zA-Z_]*(\[\]\.([a-zA-Z_][\da-zA-Z_]*))?(\.([a-zA-Z_][\da-zA-Z_]*|\d+))*$
      description: Name of a parent field whose selected value filters options in this field. E.g., selecting a connection filters related data entries
    ProfilePhoto:
      allOf:
      - $ref: '#/components/schemas/ProfileProperty'
      - properties:
          etag:
            type: string
            minLength: 32
            maxLength: 32
            example: '00000000000000000000000000000000'
          value:
            type: string
            format: url
            example: https://example.com/avatar.jpg
    JsonNestedIdentifier:
      type: string
      description: JSON field name, optionally nested, e.g., 'field1.subfield2'
      pattern: ^[a-zA-Z_][\da-zA-Z_]*(\.([a-zA-Z_][\da-zA-Z_]*|\d+))*$
    ProfileEmail:
      oneOf:
      - allOf:
        - $ref: '#/components/schemas/ProfileProperty'
        - properties:
            value:
              type: string
              format: email
              example: user@example.com
      - type: string
        format: email
        minLength: 1
        example: user@example.com
    Profile:
      title: User Profile
      type: object
      properties:
        displayName:
          type: string
          description: The name of the user, suitable for displaying to other parties
          readOnly: true
        name:
          title: Structured User Name
          allOf:
          - type: object
            additionalProperties: false
            properties:
              formatted:
                type: string
                description: The full name, including all middle names, titles, and suffixes as appropriate, formatted for display
                example: Ms. Barbara Jane Jensen, III
              honorificPrefix:
                type: string
                description: The honorific prefix(es) of the User, or title in most Western languages.
                example: Ms.
              givenName:
                type: string
                description: The given name of the User, or first name in most Western languages.
                example: Barbara
              middleName:
                type: string
                description: The middle name(s) of the User.
                example: Jane
              familyName:
                type: string
                description: The family name of the User, or last name in most Western languages.
                example: Jensen
              honorificSuffix:
                type: string
                description: The honorific suffix(es) of the User, or suffix in most Western languages.
                example: III
          - anyOf:
            - title: formatted name not empty
              required:
              - formatted
            - title: givenName and familyName not empty
              required:
              - givenName
              - familyName
        userName:
          type: string
          minLength: 5
          maxLength: 50
          pattern: ^[a-zA-Z]{2}\w+$
          description: A unique, manually-set identifier for the user in BanQu system (requires additional account permissions to be used)
        emails:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/ProfileEmail'
        phoneNumbers:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/ProfilePhoneNumber'
        ims:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/ProfileProperty'
        photos:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/ProfilePhoto'
        addresses:
          type: array
          uniqueItems: true
          items:
            type: object
            description: A physical mailing address for this user
            additionalProperties: false
            properties:
              type:
                type: string
                description: Canonical type values of "work", "home", and "other"
                example: home
              formatted:
                type: string
                description: The full mailing address, formatted for display or use with a mailing label
              streetAddress:
                type: string
                description: The full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information.
              locality:
                type: string
                description: The city or locality component
              region:
                type: string
                description: The state or region component
              postalCode:
                type: string
                description: The zipcode or postal code component
              country:
                type: string
                description: The country name component. When specified the value MUST be in ISO 3166-1 alpha 2 "short" code format [ISO3166]
                example: US
        preferredLanguage:
          type: string
          description: Indicates the user's preferred written or spoken languages and is generally used for selecting a localized User interface. The value indicates the set of natural languages that are preferred.
          example: en
        locale:
          type: string
          enum:
          - en-us
          - en-gb
          - en-za
          - uk-ua
          description: Used to indicate the User's default location for purposes of localizing such items as currency, date time format, or numerical representations. A valid value is a language tag as defined in [RFC5646](https://tools.ietf.org/html/rfc5646). Computer languages are explicitly excluded.
        urn:banqu:schemas:scim:User:social:
          title: User social profile
          type: object
          properties:
            gender:
              type: string
              enum:
              - ''
              - O
              - M
              - F
              example: M
              description: 'Letter of a gender: "M" for male, "F" for female, "O" for other, or empty value not to specify it'
            birthday:
              type: string
              format: date
              example: '1985-04-17'
        urn:banqu:schemas:scim:User:identification:
          title: User identification documents
          type: array
          uniqueItems: true
          items:
            type: object
            additionalProperties: false
            properties:
              type:
                type: string
                minLength: 1
              $entityId:
                type: string
                minLength: 1
              country:
                type: string
                description: The country name component. When specified the value MUST be in ISO 3166-1 alpha 2 "short" code format [ISO3166]
                example: US
                minLength: 2
                maxLength: 2
              expiresOn:
                type: string
                format: date
              issuedBy:
                type: string
              issuedOn:
                type: string
                format: date
              id:
                type: string
                minLength: 1
              attachments:
                $ref: '#/components/schemas/Attachment'
            required:
            - type
            - id
      patternProperties:
        ^urn:banqu:schemas:([a-f\d]{32}|scim):User:[a-zA-Z_][\da-zA-Z_]*$:
          anyOf:
          - type: object
          - type: array
    CheckboxField:
      title: Checkbox Field
      type: object
      properties:
        $entityId:
          type: string
          description: Internal unique identifier for the field
        name:
          $ref: '#/components/schemas/JsonNestedIdentifier'
        type:
          type: string
          enum:
          - checkbox
        title:
          $ref: '#/components/schemas/OptionalLocalizedString'
        placeholder:
          $ref: '#/components/schemas/OptionalLocalizedString'
        description:
          $ref: '#/components/schemas/OptionalLocalizedString'
        descriptionVariant:
          $ref: '#/components/schemas/DescriptionVariant'
        required:
          type: boolean
        visibility:
          $ref: '#/components/schemas/FormElementVisibility'
        size:
          type: integer
          description: The number of slots preserved for the field in a table column
          minimum: 1
          maximum: 12
        weight:
          type: number
          description: A numerical value representing the importance of this field in the overall score calculation. Higher values indicate greater importance.
        importanceArea:
          $ref: '#/components/schemas/FormFieldImportance'
        frozen:
          type: boolean
          readOnly: true
        uniqueAcrossInstances:
          enum:
          - false
        defaultValue:
          type: boolean
          description: Default value for this checkbox field
      required:
      - name
      - type
    FragmentField:
      title: Fragment Field
      type: object
      required:
      - fragmentId
      - type
      properties:
        type:
          type: string
          enum:
          - fragment
        fragmentId:
          type: string
          minLength: 16
        title:
          $ref: '#/components/schemas/LocalizedString'
        placeholder:
          $ref: '#/components/schemas/OptionalLocalizedString'
        description:
          $ref: '#/components/schemas/OptionalLocalizedString'
        descriptionVariant:
          $ref: '#/components/schemas/DescriptionVariant'
        visibility:
          $ref: '#/components/schemas/FormElementVisibility'
        $entityId:
          type: string
        requiredIf:
          type: string
        visibleIf:
          type: string
        required:
          type: boolean
        importanceArea:
          $ref: '#/components/schemas/FormFieldImportance'
        frozen:
          type: boolean
          readOnly: true
        primary:
          type: boolean
          description: Whether field is a primary key or part of a primary key. Primary key values should be unique across multiple form data entries of a same user
        globalPrimary:
          type: boolean
          description: Whether field is a primary key or part of a primary key. Primary key values should be unique across multiple form data entries of a same user
        uniqueAcrossInstances:
          type: boolean
          description: Unique across section instances when form section is repeatable
        formula:
          type: string
          description: Formula for calculated mode of the field
      additionalProperties: false
    ProfileSectionsList:
      type: array
      items:
        $ref: '#/components/schemas/ProfileSection'
    FormField:
      title: Form Field
      type: object
      properties:
        $entityId:
          type: string
          description: Internal unique identifier for the field
        name:
          $ref: '#/components/schemas/JsonNestedIdentifier'
        type:
          type: string
          enum:
          - text
          - textarea
          - connectionSelect
          - assetSelect
          - countrySelect
          - currencySelect
          - dataEntrySelect
          - datetime
          - file
          - geoPosition
          - polygon
          - barcode
        title:
          $ref: '#/components/schemas/LocalizedString'
        placeholder:
          $ref: '#/components/schemas/OptionalLocalizedString'
        description:
          $ref: '#/components/schemas/OptionalLocalizedString'
        descriptionVariant:
          $ref: '#/components/schemas/DescriptionVariant'
        required:
          type: boolean
        validation:
          type: string
        parentFieldName:
          $ref: '#/components/schemas/ParentFieldName'
        visibility:
          $ref: '#/components/schemas/FormElementVisibility'
        format:
          type: string
          description: Format of 'datetime' field type
          enum:
          - date
          - time
          - date-time
        primary:
          type: boolean
          description: Whether field is a primary key or part of a primary key. Primary key values should be unique across multiple form data entries of a same user
        globalPrimary:
          type: boolean
          description: Whether field is a primary key or part of a primary key. Primary key values should be unique across multiple form data entries of a same user
        uniqueAcrossInstances:
          type: boolean
          description: Unique across section instances when form section is repeatable
        size:
          type: integer
          description: The number of slots preserved for the field in a table column
          minimum: 1
          maximum: 12
        displayTotals:
          type: boolean
          description: When enabled, the sum of all field values is displayed in the totals row on the UI
        weight:
          type: number
          description: A numerical value representing the importance of this field in the overall score calculation. Higher values indicate greater importance.
        isParent:
          type: boolean
          description: Mark the selected connection as a parent of the data entry
        connectionType:
          type: string
          description: Connection type to filter connections in the connection select field
          enum:
          - org
          - user
        importanceArea:
          $ref: '#/components/schemas/FormFieldImportance'
        frozen:
          type: boolean
          readOnly: true
        formula:
          type: string
          description: Formula for calculated mode of the field
      required:
      - name
      - type
      - title
    LocalizedString:
      type: object
      required:
      - en
      additionalProperties:
        type: string
        description: Strings in different languages
      properties:
        en:
          type: string
          description: Default English localization string
    ProfilePhoneNumber:
      oneOf:
      - allOf:
        - $ref: '#/components/schemas/ProfileProperty'
        - properties:
            value:
              $ref: '#/components/schemas/PhoneNumber'
      - $ref: '#/components/schemas/PhoneNumber'
    FormElementVisibility:
      oneOf:
      - type: object
        description: Data-entry or profile form field visibility
        required:
        - approver
        - reviewer
        - responder
        properties:
          approver:
            $ref: '#/components/schemas/ReadWriteVisibility'
          reviewer:
            $ref: '#/components/schemas/ReadWriteHideVisibility'
          responder:
            $ref: '#/components/schemas/ReadWriteHideVisibility'
        additionalProperties: false
      - type: object
        description: Transaction form field visibility
        required:
        - initiator
        - update-by-initiator
        - participant
        properties:
          update-by-initiator:
            $ref: '#/components/schemas/ReadWriteHideVisibility'
          participant:
            $ref: '#/components/schemas/ReadWriteHideVisibility'
          initiator:
            $ref: '#/components/schemas/ReadWriteHideVisibility'
        additionalProperties: false
    Id:
      title: Id
      type: string
      minLength: 32
      maxLength: 32
      example: '00000000000000000000000000000000'
    DescriptionVariant:
      type: string
      enum:
      - text
      - tooltip
      - long-text
    ReadWriteHideVisibility:
      type: string
      enum:
      - hidden
      - readonly
      - edit
    ReadWriteVisibility:
      type: string
      enum:
      - readonly
      - edit
    ProfileProperty:
      title: Profile Property
      type: object
      properties:
        type:
          type: string
        value:
          type: string
          minLength: 1
        primary:
          type: boolean
      required:
      - value
    FormFieldImportance:
      type: object
      properties:
        ui:
          type: boolean
          description: Field is important for UI
        reporting:
          type: boolean
          description: Field is important for reporting
        coc:
          type: boolean
          description: Field is important for CoC
      additionalProperties: false
    ExistentProfile:
      allOf:
      - type: object
        properties:
          id:
            $ref: '#/components/schemas/ImmutableId'
      - $ref: '#/components/schemas/Profile'
      unevaluatedProperties: false
    Form:
      type: object
      title: Form
      properties:
        id:
          $ref: '#/components/schemas/ImmutableId'
        title:
          $ref: '#/components/schemas/LocalizedString'
        version:
          type: number
          readOnly: true
          description: Form template age. It is increased on server side with every modification
        sharing:
          title: Form Type
          oneOf:
          - title: Transaction Properties Form
            type: object
            properties:
              level:
                type: string
                enum:
                - batch
              txTypes:
                description: The transaction types the form can be used for
                type: array
                items:
                  type: string
                  enum:
                  - batch
                  - transformation
                minItems: 1
                uniqueItems: true
            additionalProperties: false
          - title: Private Data Entry Form
            type: object
            properties:
              level:
                type: string
                enum:
                - private
            additionalProperties: false
          - title: Fragment Form
            type: object
            properties:
              level:
                type: string
                enum:
                - fragment
            additionalProperties: false
          - title: Shared Data Entry Form
            type: object
            properties:
              level:
                type: string
                enum:
                - shared
            additionalProperties: false
          - title: User Profile Form
            type: object
            properties:
              level:
                type: string
                enum:
                - replace
              profileSectionName:
                type: string
                pattern: ^(urn:banqu:schemas:[a-f\d]{32}:User:)?[a-zA-Z][\da-zA-Z]*$
                minLength: 1
              reportingSectionName:
                type: string
                pattern: ^(urn:banqu:schemas:[a-f\d]{32}:User:[a-zA-Z][\da-zA-Z]*)?$
              priority:
                type: number
                minimum: 0
              replaceProfileSections:
                type: array
                items:
                  type: string
              profileSectionNamePrefix:
                description: Used as a backdoor in API to be able to change a client form into a standard form
                type: string
                enum:
                - 'urn:banqu:schemas:scim:User:'
            additionalProperties: false
            required:
            - level
            - profileSectionName
          - title: Org Profile Form
            type: object
            properties:
              level:
                type: string
                enum:
                - org-profile
              profileSectionName:
                type: string
                pattern: ^(urn:banqu:schemas:[a-f\d]{32}:Org:)?[a-zA-Z][\da-zA-Z]*$
                minLength: 1
              profileSectionNamePrefix:
                description: Used as a backdoor in API to be able to change a client form into a standard form
                type: string
                enum:
                - 'urn:banqu:schemas:scim:Org:'
              priority:
                type: number
                minimum: 0
            additionalProperties: false
            required:
            - level
            - profileSectionName
          required:
          - level
        appearance:
          title: Form Appearance Settings
          type: object
          properties:
            collapsingType:
              type: string
              enum:
              - accordion
              - collapsed
              - expanded
            showScore:
              type: boolean
          additionalProperties: false
        usagePreferences:
          title: Data Entry Form Usage Preferences
          type: object
          properties:
            assign:
              type: boolean
              description: If true, the form can be assigned to connected identities
        

# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/banqu/refs/heads/main/openapi/banqu-user-profile-api-openapi.yml