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:
  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
    Resource:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
            uniqueItems: true
          readOnly: true
        id:
          type: string
          description: The resource type's server unique id
          readOnly: true
        externalId:
          type: string
          description: A String that is an identifier for the resource as defined by the provisioning client. The "externalId" may simplify identification of a resource between the provisioning client and the service provider by allowing the client to use a filter to locate the resource with an identifier from the provisioning domain, obviating the need to store a local mapping between the provisioning domain's identifier of the resource and the identifier used by the service provider.
        meta:
          type: object
          description: A complex attribute containing resource metadata. All "meta" sub-attributes are assigned by the service provider (have a "mutability" of "readOnly"), and all of these sub-attributes have a "returned" characteristic of "default".
          properties:
            resourceType:
              type: string
              enum:
              - User
              - Org
              - Invite
              readOnly: true
            created:
              type: number
              readOnly: true
            lastModified:
              type: number
              readOnly: true
            location:
              type: string
              format: uri
              readOnly: true
          readOnly: true
    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_]*$
    ProfileRequirements:
      title: Profile with email, phoneNumber, identification document, or name and birthday
      anyOf:
      - title: emails not empty
        properties:
          emails:
            minItems: 1
        required:
        - emails
      - title: phoneNumbers not empty
        properties:
          phoneNumbers:
            minItems: 1
        required:
        - phoneNumbers
      - title: identification documents not empty
        properties:
          urn:banqu:schemas:scim:User:identification:
            minItems: 1
        required:
        - urn:banqu:schemas:scim:User:identification
      - title: name and birthday not empty
        properties:
          urn:banqu:schemas:scim:User:social:
            required:
            - birthday
        required:
        - name
        - urn:banqu:schemas:scim:User:social
      - title: name and userName not empty
        required:
        - name
        - userName
    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+))*$
    Attachments:
      type: array
      items:
        $ref: '#/components/schemas/Attachment'
    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
    AssetCode:
      type: string
      minLength: 2
      maxLength: 32
    AssetDescription:
      type: string
      minLength: 0
      maxLength: 200
    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
       

# --- 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