openapi: 3.0.1
info:
  title: Bamboo Account Management Financial Documents API
  version: ''
  description: "Account creation enables users to invest on Bamboo. Ensure KYC has been completed and each user’s identity verified before creating a brokerage account.\n\n**Best Practice:** To avoid maintenance fees on inactive accounts, create and fund brokerage accounts **only when users initiate their first trade**. You may collect account details in advance but delay sending the request until they’re ready to buy.\n\n##### Prerequisites\n- **Minimum Age:** 18 years (verified via government-issued ID)\n- **Compliance:** Must meet local investment regulations\n\n##### Document Requirements\n<table>\n  <thead>\n    <tr>\n      <th>Country</th>\n      <th>Primary ID</th>\n      <th>Image Requirements</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <th>Nigeria</th>\n      <td>BVN</td>\n      <td>Passport photo</td>\n    </tr>\n    <tr>\n      <th>Ghana</th>\n      <td>National ID</td>\n      <td>Front & back ID images</td>\n    </tr>\n    <tr>\n      <th>South Africa</th>\n      <td>National ID</td>\n      <td>Front & back ID images</td>\n    </tr>\n  </tbody>\n</table>\n\n**Note:** Images must be in Base64 format. The `front_id_image` and `back_id_image` fields apply only to Ghana and South Africa.\n\n##### Phone Number Format\n- Must be in international format (e.g., +2347083864023)\n- Country code must match user’s residence\n- Used for notifications and account security\n"
servers:
- url: https://powered-by-bamboo-sandbox.investbamboo.com
tags:
- name: Financial Documents
  description: "Access various financial documents required for user account management, tax reporting, and regulatory compliance through secure document retrieval endpoints.\n\n##### Document Types and Generation\nThe system generates three primary document categories to meet regulatory requirements and provide users with comprehensive account records.\n\n**Trade Confirmations:**\n- **Generation:** Generated for users who have engaged in stock trades at the end of each trading day\n- **Content:** Trade details, execution prices, fees, settlement dates \n- **Purpose:** Legal confirmation of executed trades\n\n**Account Statements:** \n- **Generation:** Generated at the end of each month\n- **Content:** Portfolio holdings, cash balances, transaction history \n- **Purpose:** Comprehensive account activity summary\n\n**Tax Documents:** \n- **Generation:** Generated once, at the end of each year\n- **Content:** Realized gains/losses, dividend income, tax obligations \n- **Purpose:** Support user tax filing requirements\n"
paths:
  /api/document_list:
    get:
      tags:
      - Financial Documents
      summary: Fetch List of All Documents
      description: "Document retrieval begins with obtaining available document lists filtered by document type for efficient access to specific document categories.\n\n**Document Type Parameters:**\n- confirms: Trade confirmation documents \n- statements: Monthly account statements \n- taxforms: Annual tax reporting documents\n\nDocument metadata includes unique file keys for document retrieval, generation dates showing when documents were created, coverage periods indicating date ranges covered by each document, and file formats with all documents provided as PDF files.\n"
      operationId: Web.Api.Tenant.ExchangeRateController.exchange_rate
      parameters:
      - name: content-type
        in: header
        description: Acceptable content type
        example: application/json
        required: true
        schema:
          type: string
      - name: accept-language
        in: header
        description: Acceptable language; 'en' for English
        example: en
        required: true
        schema:
          type: string
      - name: x-client-token
        in: header
        description: API consumer token
        required: true
        schema:
          type: string
      - name: x-user-id
        in: header
        description: Required for user authentication
        required: true
        schema:
          type: string
      - name: x-subject-type
        in: header
        description: For user request -> 'tenant'.
        required: true
        schema:
          type: string
      - name: document_type
        in: query
        description: "Used to state the type of document you want to download; \n- ```confirms``` for Trade Confirmations\n- ```statements``` for Account Statement\n- ```taxforms``` for Tax Documents\n"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/USDocumentList'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFound'
  /api/document:
    get:
      tags:
      - Financial Documents
      summary: Fetch a Single Document
      description: 'This endpoint is used to access individual document download URLs using unique file key identifiers gotten from the `document_list` endpoint.


        Security features include expiring URLs where download links expire for security, IP restrictions limiting access to authorized requests, and user verification ensuring documents are only accessible by account owners.

        '
      operationId: Web.Api.Tenant.DocumentController.document
      parameters:
      - name: content-type
        in: header
        description: Acceptable content type
        example: application/json
        required: true
        schema:
          type: string
      - name: accept-language
        in: header
        description: Acceptable language; 'en' for English
        example: en
        required: true
        schema:
          type: string
      - name: x-client-token
        in: header
        description: API consumer token
        required: true
        schema:
          type: string
      - name: x-user-id
        in: header
        description: Required for user authentication
        required: true
        schema:
          type: string
      - name: x-subject-type
        in: header
        description: For user request -> 'tenant'.
        required: true
        schema:
          type: string
      - name: file_key
        in: query
        description: File key gotten from the document list
        required: true
        schema:
          type: string
        example: 2024081901
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/USDocuments'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFound'
components:
  schemas:
    USDocuments:
      title: URL to download a Single Document
      required:
      - url
      type: object
      properties:
        url:
          type: link
          description: Document URL
          example: https://dzb6emi8pracf.cloudfront.net/420d2907-bb49-421d-accd-9ad4692b0a51.1722266251918/Confirm_BBOO_001_BBMN000009_08302024.pdf?Policy=eyJTdGF0ZW1lbnQiOiBbeyJSZXNvdXJjZSI6Imh0dHBzOi8vZHpiNmVtaThwcmFjZi5jbG91ZGZyb250Lm5ldC80MjBkMjkwNy1iYjQ5LTQyMWQtYWNjZC05YWQ0NjkyYjBhNTEuMTcyMjI2NjI1MTkxOC9Db25maXJtX0JCT09fMDAxX0JCTU4wMDAwMDlfMDgzMDIwMjQucGRmIiwiQ29uZGl0aW9uIjp7IkRhdGVMZXNzVGhhbiI6eyJBV1M6RXBvY2hUaW1lIjoxNzI1NTI1Njg2fSwiSXBBZGRyZXNzIjp7IkFXUzpTb3VyY2VJcCI6IjAuMC4wLjAvMCJ9fX1dfQ__&Signature=WL-Cm2B8BMOvT0ZZf6lMbIUmq1m4jF6atbtsalkgFKOyXs08eaA5nPFnOJjlQBmhqdzva8uGsKdV11U2Mmbmk3UXMzU8-sKQSMlMZ-awknHGSGELJbA1aOlbscsxeznP~MZhVL73ouKuX6scyqqk8AXkiTXTwKfJSxVhPiR0EAcrvW0GkrheiydXiti87eed07t-Tl8BGd7Du83ClueJZxJTTMhNGhuYhpvB-G7yzzRUJWIXsVhofGlmC9mChD~2R6OoaruQ7UckxlHL~IobKzm0oZLiRESiqyuHfgGwIZrY~KGVNXFmgbYNIiFZObjDgbMlVWErM-80VYiRtL9Ctw__&Key-Pair-Id=APKAJP3MFGZ6DRA4CW4Q
    USDocumentList:
      title: List of Documents by Document Type
      required:
      - documents
      type: object
      properties:
        documents:
          type: array
          description: List of Documents
          example:
          - name: Aug 30, 2024 Trade Confirm
            file_key: '2024083001'
          - name: Aug 29, 2024 Trade Confirm
            file_key: '2024082901'
          - name: Aug 28, 2024 Trade Confirm
            file_key: '2024082801'
          - name: Aug 27, 2024 Trade Confirm
            file_key: '2024082701'
          - name: Aug 26, 2024 Trade Confirm
            file_key: '2024082601'
          - name: Aug 23, 2024 Trade Confirm
            file_key: '2024082301'
          - name: Aug 19, 2024 Trade Confirm
            file_key: '2024081901'
          - name: Aug 16, 2024 Trade Confirm
            file_key: '2024081601'
          - name: Aug 14, 2024 Trade Confirm
            file_key: '2024081401'
    ResourceNotFound:
      title: Resource not found
      required:
      - message
      type: object
      properties:
        message:
          type: string
          description: Resource not found (an incorrect url may have been used)
          example: Resource Not Found
      description: Error response for when the resource is not found within our data.
x-logo:
  url: bamboo-logo.png
  altText: bamboo logo
x-tagGroups:
- name: Authentication
  tags:
  - Authentication
  - Account Management
- name: Money Movement
  tags:
  - Overview
  - Deposits
  - Withdrawals
- name: US Brokerage Services
  tags:
  - Portfolio Reporting
  - US Securities
  - US Stock Trading
  - US Stock Events
- name: Utilities
  tags:
  - Dictionaries
  - Market Activity
  - Exchange Rate
  - Featured Themes
  - Financial Documents