BanQu Connections API

openapi: 3.2.0
info:
  title: BanQu Connections 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: Connections
  description: Connected organizations and identitites
paths:
  /connections:
    get:
      description: List connections/invites
      tags:
      - Connections
      parameters:
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/SortBy'
      - $ref: '#/components/parameters/Search'
      - name: status
        in: query
        schema:
          type: string
          enum:
          - connected
          - pending-incoming
        description: Filter by connection status
        required: false
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Connection'
          headers:
            X-Total-Count:
              schema:
                type: number
              description: Total number of connections available for paging purposes
        '401':
          $ref: '#/components/responses/401'
    post:
      description: Create identity or send connection invite
      tags:
      - Connections
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectionCreatePayload'
      responses:
        '201':
          description: Connection invite or identity profile is created
        '202':
          description: User invited to BanQu
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
  /connections/filter:
    post:
      description: Search connections and filter them by specific form fields
      tags:
      - Connections
      requestBody:
        content:
          application/json:
            schema:
              properties:
                filter:
                  $ref: '#/components/schemas/ConnectionFilter'
      parameters:
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/SortBy'
      - $ref: '#/components/parameters/Search'
      - name: status
        in: query
        schema:
          type: string
          enum:
          - connected
          - pending-incoming
        description: Filter by connection status
        required: false
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Connection'
          headers:
            X-Total-Count:
              schema:
                type: number
              description: Total number of found connections available for paging purposes
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
  /connections/csv:
    get:
      description: Export connections to CSV
      tags:
      - Connections
      parameters:
      - name: method
        in: query
        schema:
          type: string
          enum:
          - pretty
          - simple
        description: Sets output format. "simple" is default. "pretty" provides field titles in header, formatted dates, list items, hides system information. "simple" gives JSON names in header and all available unformatted data
        required: false
      - name: excludeColumns
        in: query
        schema:
          type: string
        description: Comma-separated list of JSON names of fields to be omitted
        required: false
      responses:
        '200':
          description: Ok
          content:
            text/csv;:
              schema:
                type: string
          headers:
            content-type:
              schema:
                type: string
              description: text/csv;charset=utf-8
            content-disposition:
              schema:
                type: string
              description: Proposed file name
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
  /connections/{connectionId}:
    get:
      description: Get connection details
      tags:
      - Connections
      parameters:
      - $ref: '#/components/parameters/connectionId'
      responses:
        '200':
          description: Connection details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
    patch:
      description: Change connection details
      tags:
      - Connections
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Resource'
              - $ref: '#/components/schemas/ConnectionExtension'
              - type: object
                properties:
                  lastModified:
                    type: number
      parameters:
      - $ref: '#/components/parameters/connectionId'
      responses:
        '200':
          $ref: '#/components/responses/NewProfileTimestamp'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
    delete:
      description: Delete connection/invite
      tags:
      - Connections
      parameters:
      - $ref: '#/components/parameters/connectionId'
      responses:
        '200':
          description: Connection deleted
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
    put:
      description: Create connection
      tags:
      - Connections
      parameters:
      - name: newConnectionId
        description: New Connection ID (UUID without dashes)
        in: path
        schema:
          type: string
          pattern: ^[0-9a-f]{32}$
        required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectionCreatePayload'
      responses:
        '201':
          description: Connection profile is created
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '409':
          $ref: '#/components/responses/409'
        '422':
          $ref: '#/components/responses/422'
  /connections/{connectionId}/resend:
    post:
      description: Resend connection invite
      tags:
      - Connections
      parameters:
      - $ref: '#/components/parameters/connectionId'
      responses:
        '200':
          description: Connection invite resent
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
  /connections/{connectionId}/accept:
    post:
      description: Accept connection invite
      tags:
      - Connections
      parameters:
      - $ref: '#/components/parameters/connectionId'
      responses:
        '200':
          description: Connection invite accepted
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
  /connections/{connectionId}/roles:
    post:
      description: Grant roles to connected identity
      tags:
      - Connections
      requestBody:
        content:
          application/json:
            schema:
              properties:
                roles:
                  type: array
                  items:
                    type: string
              required:
              - roles
      parameters:
      - $ref: '#/components/parameters/connectionId'
      responses:
        '200':
          $ref: '#/components/responses/NewProfileTimestamp'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
    delete:
      description: Revoke roles from connected identity
      tags:
      - Connections
      requestBody:
        content:
          application/json:
            schema:
              properties:
                roles:
                  type: array
                  items:
                    type: string
              required:
              - roles
      parameters:
      - $ref: '#/components/parameters/connectionId'
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
  /connections/{connectionId}/features:
    post:
      description: Assign features to connected identity
      tags:
      - Connections
      requestBody:
        content:
          application/json:
            schema:
              properties:
                features:
                  description: Values are limited to keys returned by `/orgs/current/features` endpoint
                  type: array
                  items:
                    type: string
              required:
              - features
      parameters:
      - $ref: '#/components/parameters/connectionId'
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
    delete:
      description: Delete features from connected identity
      tags:
      - Connections
      requestBody:
        content:
          application/json:
            schema:
              properties:
                features:
                  description: Values are limited to keys returned by `/orgs/current/features` endpoint
                  type: array
                  items:
                    type: string
              required:
              - features
      parameters:
      - $ref: '#/components/parameters/connectionId'
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
  /connections/{connectionId}/profile:
    patch:
      description: Modify connected identity profile
      tags:
      - Connections
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectionProfileUpdatePayload'
      parameters:
      - $ref: '#/components/parameters/connectionId'
      responses:
        '200':
          description: HTTP 200 - Profile modification successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  lastModified:
                    type: number
                    description: If profile was modified, contains new `lastModifed` timestamp
                required:
                - id
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
  /connections/{connectionId}/assets:
    get:
      description: List connected identity assets
      tags:
      - Connections
      parameters:
      - $ref: '#/components/parameters/connectionId'
      responses:
        '200':
          description: A list of connection assets
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                  - $ref: '#/components/schemas/Asset'
                  - $ref: '#/components/schemas/ScimResourceMetadata'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
  /connections/{connectionId}/dependents:
    post:
      description: Add connected identity household member. This effectively creates a connection between two users and sets "parent" role to the head
      tags:
      - Connections
      requestBody:
        content:
          application/json:
            schema:
              properties:
                memberId:
                  type: string
                  description: userId (UUID) or verified email or verified phone number of household member candidate
              required:
              - memberId
      parameters:
      - $ref: '#/components/parameters/connectionId'
      responses:
        '201':
          description: "HTTP 201 - Created \nHousehold member successfully added"
          headers:
            Location:
              schema:
                type: string
              description: Url of the created entity
        '204':
          description: "HTTP 204 - No Content \nNo action taken. Identity is already a member of given household "
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '422':
          description: "HTTP 422 - Unprocessable Request \nOne of given identities already has membership in a different household"
    delete:
      description: Remove connected identity household member. Revokes "parent" role on member's connection to the head
      tags:
      - Connections
      requestBody:
        content:
          application/json:
            schema:
              properties:
                memberId:
                  type: string
                  description: userId (UUID) or verified email or verified phone number of household member candidate
              required:
              - memberId
      parameters:
      - $ref: '#/components/parameters/connectionId'
      responses:
        '200':
          description: "HTTP 200 - OK \nHousehold member successfully removed"
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          description: "HTTP 404 - Not Found \nIdentity is not a member of given household"
        '422':
          description: "HTTP 422 - Unprocessable Request \nOne of given identities already has membership in a different household"
  /connections/{connectionId}/destinations:
    get:
      description: List available payment destinations for the connection
      tags:
      - Connections
      parameters:
      - $ref: '#/components/parameters/connectionId'
      - in: query
        name: claimableAsset
        schema:
          type: string
        description: a true/false flag to indicate if claimable asset providers is returned
      - in: query
        name: monetaryAsset
        schema:
          type: string
        description: a true/false flag to indicate if monetary providers is returned
      responses:
        '200':
          description: A list of connection available payment destinations for the connection
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                    provider:
                      type: string
                      enum:
                      - banqu-agency
                  required:
                  - id
                  - name
                  - provider
                - type: object
                  properties:
                    name:
                      type: string
                    id:
                      type: string
                    fees:
                      type: array
                      items:
                        type: object
                        properties:
                          max:
                            type: number
                          add:
                            type: number
                    error:
                      type: string
                    type:
                      type: string
                      enum:
                      - mobile
                    currency:
                      type: string
                    provider:
                      type: string
                      enum:
                      - mtn-uganda
                      - 6dot50pay-zaf
                      - mtn-zambia
                      - tigo-tanzania
                      - celbux-zaf
                      - airtel
                      - zamtel
                      - vodacom
                  required:
                  - name
                  - id
                  - type
                  - currency
                  - provider
        '401':
          $ref: '#/components/responses/401'
components:
  responses:
    '404':
      description: "HTTP 404 - Not Found \nRequested resource could not be found"
    '401':
      description: "HTTP 401 - Unauthorized \nUser is not authenticated or session has expired"
    '204':
      description: "HTTP 204 - No Content \nThe request has been processed, but no content will be provided in response"
    '409':
      description: "HTTP 409 - Conflict \nThe request could not be completed due to a conflict with the current state of the target resource"
    NewProfileTimestamp:
      description: HTTP 200 - Profile modification successful
      content:
        application/json:
          schema:
            type: object
            properties:
              lastModified:
                type: number
                description: If profile was modified, contains new `lastModified` timestamp
                example: 1568894551000
    '422':
      description: "HTTP 422 - Unprocessable Request \nThe server understands the content type of the request entity and the syntax of the request is correct, but was unable to process the contained instructions"
    '400':
      description: "HTTP 400 - Bad Request \nThe request is formatted incorrectly, most likely some of the required parameters are missed"
    '403':
      description: "HTTP 403 - Forbidden \nNot authorized to access selected resource"
  schemas:
    ExistentProfile:
      allOf:
      - type: object
        properties:
          id:
            $ref: '#/components/schemas/ImmutableId'
      - $ref: '#/components/schemas/Profile'
      unevaluatedProperties: false
    Attachment:
      type: object
      additionalProperties: false
      properties:
        downloadUrl:
          type: string
          format: url
        fileName:
          type: string
          minLength: 1
        fileSize:
          type: number
          minimum: 0
        mimeType:
          type: string
          minLength: 1
          example: image/jpeg
        md5:
          type: string
          minLength: 32
          maxLength: 32
          pattern: ^[a-f0-9]{32}$
      required:
      - downloadUrl
    AssetDescription:
      type: string
      minLength: 0
      maxLength: 200
    ConnectionFilter:
      type: object
      properties:
        criteria:
          type: array
          items:
            type: object
            properties:
              action:
                type: string
                enum:
                - '='
                - '>'
                - <
                - '!='
                - in
                - notIn
                - contains
              formId:
                description: Id of user or org profile form
                type: string
              name:
                description: Field JSON name. For multiple sections format is sectionName[].fieldName
                type: string
              value:
                description: 'type: string, number, boolean, array<string> value that should be compared against in specified field of found profiles'
                anyOf:
                - type: object
                - type: string
                - type: number
                - type: boolean
            required:
            - action
            - formId
            - name
            - value
        match:
          type: string
          enum:
          - any
          - all
      required:
      - filter
      - match
    AssetUsagePreferences:
      type: object
      additionalProperties: false
      properties:
        buy:
          type: boolean
        sell:
          type: boolean
        send:
          type: boolean
        receive:
          type: boolean
        batch:
          type: boolean
    ScimResourceMetadata:
      type: object
      readOnly: true
      properties:
        displayName:
          type: string
          readOnly: true
        meta:
          type: object
          properties:
            resourceType:
              type: string
              readOnly: true
            created:
              type: number
              readOnly: true
            lastModified:
              type: number
              readOnly: true
          required:
          - resourceType
          - created
          - lastModified
      required:
      - displayName
      - meta
    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
    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
    Asset:
      type: object
      additionalProperties: false
      properties:
        id:
          $ref: '#/components/schemas/ImmutableId'
        ownerId:
          $ref: '#/components/schemas/Id'
        creatorId:
          $ref: '#/components/schemas/ImmutableId'
        code:
          $ref: '#/components/schemas/AssetCode'
        description:
          $ref: '#/components/schemas/AssetDescription'
        uom:
          $ref: '#/components/schemas/AssetUom'
        attachments:
          $ref: '#/components/schemas/Attachments'
        isCredit:
          type: boolean
          default: false
          description: Indicates whether the asset will be used as a normal resource or as a credit balance
        qty:
          type: number
          default: 0
          writeOnly: true
        minQty:
          type: number
        balance:
          type: number
          readOnly: true
        confirmedBalance:
          type: number
          readOnly: true
        rejectedAmount:
          type: number
          readOnly: true
        archived:
          type: boolean
          readOnly: true
        transferPropertiesForm:
          $ref: '#/components/schemas/Form'
        prices:
          $ref: '#/components/schemas/AssetPrices'
        allowOtherCurrencies:
          type: boolean
          description: Indicates if currencies other than listed in `prices` can be used in transactions
          default: false
        requireExplicitSources:
          description: Indicates if explicit transfer sources must be specified for every transfer
          type: boolean
          default: false
        autoFilterProperties:
          description: Indicates if automatic filtering by matching properties should occur when selecting sources or sellers
          type: boolean
          default: false
        allowDoubleSourcing:
          description: Indicates that operations of this asset can be used as sources multiple times without tracing availability
          type: boolean
          default: false
        usagePreferences:
          $ref: '#/components/schemas/AssetUsagePreferences'
        confirmationPropagationMode:
          type: string
          enum:
          - none
          - proportional
          - scot-free
      required:
      - code
      - uom
      - qty
    ImmutableId:
      type: string
      readOnly: true
      minLength: 32
      maxLength: 32
      example: '00000000000000000000000000000000'
    ReadWriteVisibility:
      type: string
      enum:
      - readonly
      - edit
    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
            navbarCreate:
              type: boolean
              description: If true, the form data entry can be created from the navbar
            identityCreate:
              type: boolean
              description: If true, the form data entry can be created from the connected identity page
          additionalProperties: false
        deletedFrozenFields:
          type: object
          readOnly: true
          description: A map containing all deleted frozen fields (available for restoration). Managed on serverside
        owner:
          $ref: '#/components/schemas/ImmutableId'
        sections:
          title: Form Sections
          type: array
          items:
            $ref: '#/components/schemas/FormSection'
        groups:
          title: Form Groups
          type: array
          items:
            $ref: '#/components/schemas/FormGroup'
        archived:
          type: boolean
          description: Indicates if form is archived
          readOnly: true
        thirdPartyValidation:
          type: boolean
          description: On profile forms indicates if the form data can be reviewed by a third-party contract specified in data entry
      required:
      - title
      - sections
      additionalProperties: false
      example:
        title:
          en: My Form
        version: 1
        sections:
        - title:
            en: Some List
          name: section1
          multiple: true
          required: true
          fields:
          - name: field1
            type: text
            title:
              en: Field Title
            required: true
            visibility:
              approver: readonly
              reviewer: hidden
              responder: edit
        sharing:
          level: shared
    FormField:
      title: Form Field
      type: object
      properties:
        $entityId:
          type: string
          description: Internal unique identifier for the fie

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