BanQu User Profile Sharing API

openapi: 3.2.0
info:
  title: BanQu User Profile Sharing 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 Sharing
paths:
  /profile/sharing:
    get:
      description: Get profile sharing settings
      tags:
      - User Profile Sharing
      responses:
        '200':
          description: Sharing settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileVisibility'
        '401':
          $ref: '#/components/responses/401'
    patch:
      description: Change profile sharing settings
      tags:
      - User Profile Sharing
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfileVisibility'
      responses:
        '200':
          description: Sharing settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileVisibility'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
  /profile-shared-packages:
    get:
      tags:
      - User Profile Sharing
      description: List packaged profile shares
      responses:
        '200':
          description: List of profile share packages
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PackagedShareProfileListItem'
        '401':
          $ref: '#/components/responses/401'
    post:
      tags:
      - User Profile Sharing
      description: Create packaged profile share
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPackagedShareProfile'
      responses:
        '201':
          $ref: '#/components/responses/201'
        '401':
          $ref: '#/components/responses/401'
  /profile-shared-packages/{id}:
    get:
      tags:
      - User Profile Sharing
      description: Get packaged profile share details
      parameters:
      - name: id
        description: sharing id
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Particular packaged share profile data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackagedShareProfile'
    delete:
      tags:
      - User Profile Sharing
      description: Delete packaged profile share
      parameters:
      - name: id
        description: sharing id
        in: path
        schema:
          type: string
        required: true
      responses:
        '204':
          $ref: '#/components/responses/204'
  /profile-shared-packages/{id}/assets:
    parameters:
    - name: id
      description: sharing id
      in: path
      schema:
        type: string
      required: true
    get:
      tags:
      - User Profile Sharing
      parameters:
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/SortBy'
      description: List packaged profile share assets
      responses:
        '200':
          description: A list of assets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SharedAssets'
        '401':
          $ref: '#/components/responses/401'
  /profile-shared-packages/{id}/transactions:
    get:
      tags:
      - User Profile Sharing
      description: List packaged profile share transactions
      parameters:
      - name: id
        description: sharing id
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: A list of transactions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/401'
  /profile-shared-packages/{id}/connections:
    get:
      tags:
      - User Profile Sharing
      description: List packaged profile share connections
      parameters:
      - name: id
        description: sharing id
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: A list of connections
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Connection'
        '401':
          $ref: '#/components/responses/401'
  /profile-shared-packages/{id}/asset-categories:
    get:
      tags:
      - User Profile Sharing
      description: List packaged profile share categories
      parameters:
      - name: id
        description: sharing id
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: A list of asset categories
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AssetCategory'
        '401':
          $ref: '#/components/responses/401'
  /profile-shared-packages/{id}/geo-data:
    get:
      parameters:
      - name: id
        description: sharing id
        in: path
        schema:
          type: string
        required: true
      description: Get GeoJSON data from shared Profile Sections
      tags:
      - User Profile Sharing
      responses:
        '200':
          description: Successful response containing the GeoJSON object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeoJsonFeatureCollection'
  /profile/shares:
    get:
      tags:
      - User Profile Sharing
      description: List profile shares
      responses:
        '200':
          description: List of profile shares
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProfileShareRequests'
    post:
      tags:
      - User Profile Sharing
      description: Create profile share
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                receiverId:
                  description: User or Org id
                  type: string
                sections:
                  type: array
                  items:
                    type: string
                    uniqueItems: true
                expiresAt:
                  type: number
                  description: expiration time in milliseconds
              required:
              - receiverId
              - sections
      responses:
        '201':
          $ref: '#/components/responses/201'
        '403':
          $ref: '#/components/responses/403'
        '422':
          $ref: '#/components/responses/422'
  /profile/shares/{otherPartyId}:
    parameters:
    - name: otherPartyId
      description: User or Org id
      in: path
      schema:
        type: string
      required: true
    get:
      tags:
      - User Profile Sharing
      description: Get profile share request details
      responses:
        '200':
          description: A certain share request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareRequest'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
    delete:
      tags:
      - User Profile Sharing
      description: Delete/reject profile share request
      responses:
        '204':
          $ref: '#/components/responses/204'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/422'
  /profile/shares/{senderId}/approve:
    post:
      tags:
      - User Profile Sharing
      description: Accept profile share request
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                expiresAt:
                  type: number
                  description: expiration time in milliseconds
      parameters:
      - name: senderId
        description: User or Org id
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Request was approved
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/422'
components:
  schemas:
    PaymentDestinationType:
      title: Destination Type
      description: mobile for payments by phone number; payCode for 6DOT50 partner transfer
      enum:
      - mobile
      - new-mobile
      - payCode
    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
    GeoCoordinates:
      type: object
      properties:
        lat:
          type: number
          format: double
          minimum: -90
          maximum: 90
        lon:
          type: number
          format: double
          minimum: -180
          maximum: 180
      additionalProperties: false
      required:
      - lat
      - lon
      example:
        lat: 37.7749
        lon: -122.4194
    PackagedShareProfile:
      type: object
      properties:
        addresses:
          type: array
          items:
            type: object
            properties:
              country:
                type: string
              locality:
                type: string
              postalCode:
                type: string
              streetAddress:
                type: string
        displayName:
          type: string
        emails:
          type: array
          items:
            type: object
            properties:
              primary:
                type: boolean
              type:
                type: string
              value:
                type: string
        meta:
          type: object
          properties:
            created:
              type: integer
            lastModified:
              type: integer
            resourceType:
              type: string
        name:
          type: object
          properties:
            familyName:
              type: string
            formatted:
              type: string
            givenName:
              type: string
        photos:
          type: array
          items:
            type: object
            properties:
              etag:
                type: string
              primary:
                type: boolean
              value:
                type: string
      additionalProperties:
        type: string
    SharedAsset:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
        code:
          $ref: '#/components/schemas/AssetCode'
        description:
          $ref: '#/components/schemas/AssetDescription'
        uom:
          $ref: '#/components/schemas/AssetUom'
        isCredit:
          type: boolean
        balance:
          type: number
      required:
      - uom
      - isCredit
      - id
      - code
      - balance
    PackagedShareProfileListItem:
      type: object
      description: Packaged share profile data
      properties:
        assets:
          type: array
          items:
            type: string
        bucket:
          type: string
        connections:
          type: string
        createdAt:
          type: integer
        expiresAt:
          type: integer
        ownerId:
          type: string
        sections:
          type: array
          items:
            type: string
        state:
          type: string
    TransformingAsset:
      type: object
      additionalProperties: false
      properties:
        id:
          $ref: '#/components/schemas/Id'
        code:
          $ref: '#/components/schemas/AssetCode'
        description:
          $ref: '#/components/schemas/AssetDescription'
        uom:
          $ref: '#/components/schemas/AssetUom'
      required:
      - id
      - code
      - uom
    ExchangeTransaction:
      type: object
      additionalProperties: false
      properties:
        id:
          $ref: '#/components/schemas/ImmutableId'
        allCodes:
          type: array
          items:
            type: string
        assetIds:
          type: array
          items:
            type: string
        receiverId:
          $ref: '#/components/schemas/Id'
        type:
          type: string
          enum:
          - batch
          - trade
          - exchange
          - transfer
        unconfirmedAssetIds:
          type: array
          items:
            $ref: '#/components/schemas/Id'
        destinationProvider:
          $ref: '#/components/schemas/PaymentDestinationProvider'
        destinationId:
          $ref: '#/components/schemas/PaymentDestinationId'
        destinationType:
          $ref: '#/components/schemas/PaymentDestinationType'
        initiatedBy:
          $ref: '#/components/schemas/TransactionParty'
        initiatedByUser:
          allOf:
          - $ref: '#/components/schemas/TransactionParty'
          - readOnly: true
        sender:
          $ref: '#/components/schemas/TransactionParty'
        receiver:
          $ref: '#/components/schemas/TransactionParty'
        agency:
          $ref: '#/components/schemas/TransactionParty'
        agent:
          $ref: '#/components/schemas/TransactionParty'
        qty:
          type: number
          exclusiveMinimum: 0
        price:
          type: number
          minimum: 0
        priceCurrency:
          type: string
          minLength: 3
          maxLength: 3
          example: USD
        sent:
          type: number
          readOnly: true
        claimed:
          type: number
          readOnly: true
        received:
          type: number
          readOnly: true
        properties:
          type: object
        message:
          type: string
        transactionId:
          type: string
        direction:
          type: string
        code:
          type: string
        uom:
          $ref: '#/components/schemas/AssetUom'
        description:
          type: string
        initiatedByUserId:
          type: string
        assetAttachments:
          $ref: '#/components/schemas/Attachments'
        participants:
          type: array
          items:
            type: string
      required:
      - receiverId
      - qty
    AssetDepositTransaction:
      type: object
      properties:
        description:
          type: string
        holderId:
          type: string
        holder:
          $ref: '#/components/schemas/TransactionParty'
        type:
          type: string
          enum:
          - deposit
        id:
          $ref: '#/components/schemas/Id'
        transactionId:
          $ref: '#/components/schemas/Id'
        sent:
          type: number
        qty:
          type: number
        creatorId:
          $ref: '#/components/schemas/Id'
        creator:
          $ref: '#/components/schemas/TransactionParty'
        code:
          type: string
        assetIds:
          type: array
          items:
            $ref: '#/components/schemas/Id'
        allCodes:
          type: array
          items:
            type: string
        transfers:
          type: array
          items:
            type: string
        participants:
          type: array
          items:
            $ref: '#/components/schemas/Id'
        location:
          $ref: '#/components/schemas/GeoCoordinates'
      readOnly: true
      required:
      - holderId
      - holder
      - type
      - id
      - transactionId
      - sent
      - qty
      - creatorId
      - creator
      - code
      - assetIds
      - allCodes
      - transfers
      - participants
    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
    Attachments:
      type: array
      items:
        $ref: '#/components/schemas/Attachment'
    AssetDescription:
      type: string
      minLength: 0
      maxLength: 200
    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
    AssetUom:
      title: Asset Unit of Measurement
      type: string
      enum:
      - BR
      - BO
      - BX
      - BU
      - CN
      - CA
      - CH
      - DO
      - EA
      - FO
      - FT
      - GA
      - GR
      - HR
      - JA
      - KG
      - KK
      - LT
      - Q3
      - MR
      - MG
      - M4
      - OZ
      - PK
      - PR
      - PC
      - LB
      - SJ
      - VS
      - YD
      example: KG
    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
    AssetCategory:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/AssetCode'
        description:
          $ref: '#/components/schemas/AssetDescription'
        uom:
          $ref: '#/components/schemas/AssetUom'
      required:
      - code
    PaymentDestinationProvider:
      title: Payment Destination Provider
      description: Payment provider where the payment should be delivered to
      type: string
      enum:
      - banqu-agency
      - mtn-zambia
      - 6dot50pay-zaf
      - mtn-uganda
      - tigo-tanzania
      - celbux-zaf
      - airtel
      - zamtel
      - vodacom
    SharedAssets:
      type: array
      description: List of shared assets
      items:
        $ref: '#/components/schemas/SharedAsset'
    TransactionParty:
      type: object
      readOnly: true
      properties:
        id:
          $ref: '#/components/schemas/ImmutableId'
        name:
          type: string
          readOnly: true
        photoUrl:
          type: string
          format: url
          readOnly: true
        photoEtag:
          type: string
          readOnly: true
        isOrg:
          type: boolean
    ShareRequest:
      type: object
      description: A share request
      properties:
        approved:
          type: boolean
        isSenderOrg:
          type: boolean
        isReceiverOrg:
          type: boolean
        sections:
          type: array
          items:
            type: string
          uniqueItems: true
    GeoJsonGeometryObject:
      type: object
      properties:
        type:
          type: string
          enum:
          - Point
          - MultiPoint
          - LineString
          - MultiLineString
          - Polygon
          - MultiPolygon
          - GeometryCollection
        coordinates:
          oneOf:
          - type: array
            items:
              type: number
              minItems: 2
          - type: array
            items:
              type: array
              items:
                type: number
                minItems: 2
          - type: array
            items:
              type: array
              items:
                type: array
                items:
                  type: number
                  minItems: 2
      required:
      - type
      - coordinates
    ProfilePhoneNumber:
      oneOf:
      - allOf:
        - $ref: '#/components/schemas/ProfileProperty'
        - properties:
            value:
              $ref: '#/components/schemas/PhoneNumber'
      - $ref: '#/components/schemas/PhoneNumber'
    GeoJsonFeatureCollection:
      type: object
      properties:
        type:
          type: string
          enum:
          - FeatureCollection
        features:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - Feature
              geometry:
                $ref: '#/components/schemas/GeoJsonGeometryObject'
              properties:
                type: object
            required:
            - type
            - geometry
      required:
      - type
      - features
    Id:
      title: Id
      type: string
      minLength: 32
      maxLength: 32
      example: '00000000000000000000000000000000'
    NewPackagedShareProfile:
      type: object
      properties:
        sections:
          type: array
          items:
            type: string
        expiresAt:
          type: integer
        sectionConfigurations:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
    EffectiveLocation:
      allOf:
      - $ref: '#/components/schemas/GeoCoordinates'
      - title: Effective Transfer Geo Location
        description: The effective location coordinates of a transfer instead of an automatically determined
    DateTime:
      type: string
      format: date-time
    ProfileProperty:
      title: Profile Property
      type: object
      properties:
        type:
          type: string
        value:
          type: string
          minLength: 1
        primary:
          type: boolean
      required:
      - value
    ProfileVisibility:
      type: object
      properties:
        publicEnabled:
          type: boolean
          description: Should the profile be visible from Internet
        publicSections:
          type: array
          description: Profile sections visible to Internet
          items:
            type: string
            uniqueItems: true
        connectionsEnabled:
          type: boolean
          description: Should the profile be visible for Connections
        connectionsSections:
          type: array
          description: Profile sections visible to Connections
          items:
            type: string
            uniqueItems: true
      required:
      - publicEnabled
      - publicSections
      - connectionsEnabled
      - connectionsSections
    PaymentDestinationId:
      title: Destination Identifier
      description: Destination phone number for mobile providers; BanQu agency ID for banqu-agency provider
      type: string
    AssetTransformationTransaction:
      type: object
      description: Asset Transformation
      additionalProperties: false
      properties:
        sources:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/TransformingAsset'
        destinations:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/TransformingAsset'
        creator:
          type: object
          properties:
            id:
              $ref: '#/components/schemas/ImmutableId'
            name:
              type: string
        id:
          type: string
        transactionId:
          type: string
        sent:
          type: number
        allCodes:
          type: array
          items:
            type: string
        assetIds:
          type: array
          items:
            type: string
      required:
      - destinations
      - sources
      - creator
      - id
      - transactionId
      - sent
    Connection:
      type: object
      allOf:
      - $ref: '#/components/schemas/Resource'
      - $ref: '#/components/schemas/Profile'
      - $ref: '#/components/schemas/ConnectionExtension'
      required:
      - id
    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:
          ty

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