openapi: 3.0.1
info:
  title: Bamboo Account Management Withdrawals 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: Withdrawals
  description: 'Withdrawals allow users to extract funds from their brokerage accounts after successful trades. Understanding the settlement timeline is essential.


    #### Settlement Timeline

    - Stock sale proceeds settle at T+1 business day.

    - `unsettled_cash` indicates funds that are pending settlement.

    - Once settled, funds move to `withdrawal_cash` and become available for withdrawal.


    Remember that cash represents total funds in the user''s brokerage account from all sources—deposits, stock sales, cancelled and rejected trades. All cash components (`cash`, `unsettled_cash`, `withdrawal_cash`) are available under the <a href="#tag/Portfolio-Reporting/operation/Web.Api.PortfolioController.portfolio">Portfolio endpoint</a>.

    '
paths:
  /api/tenant_brokerage_withdraw:
    post:
      tags:
      - Withdrawals
      summary: Create Withdrawal
      description: "Withdrawal requests follow a similar verification flow as deposits. You send a notification request with the necessary details to debit the user's brokerage account, we verify that the user has the amount requested. \nOnce verified, the specified amount is deducted from the user's brokerage account, and withdrawal status events are sent via Google Pub/Sub. \n\nOffline settlement happens between our teams using established procedures. (see event details under [withdrawal status events](#section/Withdrawal-Event))\n"
      operationId: Web.Api.WithdrawController.tenant_brokerage_withdraw_ngn
      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-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: x-client-token
        in: header
        description: API Consumer Authorisation Token
        required: true
        schema:
          type: string
      requestBody:
        description: tenant withdraw body parameter for NGN
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantBrokerageWithdrawBody'
      responses:
        '200':
          description: Withdrawal requested
          content:
            application/json:
              schema:
                type: string
                description: No response body for this endpoint
                example: ''
        '401':
          description: Token has expired or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '422':
          description: Incomplete Parameters
          content:
            application/json:
              example:
                message: Error Message
              schema:
                $ref: '#/components/schemas/ErrorChangesetResponse'
      x-codegen-request-body-name: body
  /api/tenant/withdraws:
    get:
      tags:
      - Withdrawals
      summary: Fetch All Withdrawals
      description: 'Complete withdrawal history with date filtering

        '
      parameters:
      - name: accept-language
        in: header
        description: Acceptable language; 'en' for English
        example: en
        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: x-client-token
        in: header
        description: API Consumer Authorisation Token
        required: true
        schema:
          type: string
      - name: x-request-source
        in: header
        description: The tenant's username
        required: true
        schema:
          type: string
      - name: limit
        in: query
        description: Number of requested results default=20
        schema:
          type: string
      - name: next_token
        in: query
        description: Next token for pagination
        schema:
          type: integer
      - name: start_date
        in: query
        description: Unix datetime stamp
        schema:
          type: string
      - name: end_date
        in: query
        description: Unix datetime stamp
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantWithdrawsPaginationResponse'
        '401':
          description: Token have expired or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
  /api/tenant/withdraw/{id}:
    get:
      tags:
      - Withdrawals
      summary: Fetch User Withdrawals
      description: 'Individual user withdrawal history for performance tracking

        '
      parameters:
      - name: accept-language
        in: header
        description: Acceptable language; 'en' for English
        example: en
        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: x-client-token
        in: header
        description: API Consumer Authorisation Token
        required: true
        schema:
          type: string
      - name: x-request-source
        in: header
        description: The tenant's username
        required: true
        schema:
          type: string
      - name: limit
        in: query
        description: Number of requested results default=20
        schema:
          type: string
      - name: next_token
        in: query
        description: Next token for pagination
        schema:
          type: integer
      - name: start_date
        in: query
        description: Unix datetime stamp
        schema:
          type: string
      - name: end_date
        in: query
        description: Unix datetime stamp
        schema:
          type: string
      - name: id
        in: path
        description: User ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantWithdrawsPaginationResponse'
        '401':
          description: Token have expired or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
  /api/tenant/withdraw/status/{reference}:
    get:
      tags:
      - Withdrawals
      summary: Withdrawal Status Check
      description: 'Real-time status checking for specific withdrawal transactions

        '
      operationId: Web.Api.Tenant.WithdrawController.withdraw_status
      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-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: x-client-token
        in: header
        description: API Consumer Authorisation Token
        required: true
        schema:
          type: string
      - name: x-request-source
        in: header
        description: The tenant's username
        required: true
        schema:
          type: string
      - name: reference
        in: path
        description: withdrawal reference
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawStatusResponse'
        '401':
          description: Token have expired or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
components:
  schemas:
    WithdrawStatusResponse:
      title: Withdraw status
      type: object
      properties:
        status:
          type: string
          description: Withdraw status
          example: pending
        reference:
          type: string
          description: Withdraw reference
          example: INVKPxiJVc40BNaQBH
        currency:
          type: string
          description: Withdraw currency
          example: NGN
        amount:
          type: number
          description: Withdraw amount
          example: 13400
      description: Withdraw status
    Unauthorized:
      title: Unauthorized response
      required:
      - message
      type: object
      properties:
        message:
          type: string
          description: Unauthorized/Invalid Token/Token has expired
          example: Invalid client token supplied.
      description: Token is invalid or have expired
    TenantBrokerageWithdrawBody:
      title: Tenant Brokerage Request body for NGN
      required:
      - reference
      - amount
      - currency
      type: object
      properties:
        currency:
          type: string
          description: currency
          example: NGN
        amount:
          type: integer
          description: amount
          example: 13400
        reference:
          type: string
          description: reference
          example: INVKPxiJVc40BNaQBH
        market:
          type: string
          description: Either "US" or "NGX". It is used to specify desired stock market. If no market is specified, it defaults to US.
          example: US
    TenantWithdrawsPaginationResponse:
      title: List of all withdrawals with pagination
      type: object
      properties:
        next_token:
          type: integer
          description: Next token for pagination
          example: 10
        withdrawals:
          type: array
          description: Withdrawal response
          items:
            title: Deposit response
            type: object
            properties:
              user_surname:
                type: string
                description: User surname
                example: Doe
              user_phone:
                type: string
                description: User's phone number
                example: '+2348033741268'
              user_name:
                type: string
                description: User name
                example: John
              user_indentifier:
                type: string
                description: User indentifier (BVN or NIN)
                example: 22388291636
              user_email:
                type: string
                description: User email
                example: johndoe@gmail.com
              swift_aba_code:
                type: string
                description: Swift or aba code - only if currency is USD
              status:
                type: string
                description: Deposit status
                example: pending
              reference:
                type: string
                description: reference
                example: INVKPxiJVc40BNaQBH
              intermediary_bank_swift_code:
                type: string
                description: bank code
              intermediary_bank:
                type: string
                description: Intermediary bank - only if currency is USD
              id:
                type: integer
                description: Deposit id
                example: 5804
              fees:
                type: string
                description: Fees information
              exchange_rate:
                type: string
                description: Exchange rate
              dollar_fees:
                type: string
                description: Fees information in dollar
              dollar_amount:
                type: integer
                description: amount
                example: 130
              currency:
                type: string
                description: currency
              created_at:
                type: integer
                description: Creation date in unix timestamp UTC
                example: 2022-02-02 01:10:20 UTC
              beneficiary_name:
                type: string
                description: Beneficiary name - only if currency is USD
              bank_zip_code:
                type: string
                description: Bank zip code - only if currency is USD
              bank_state:
                type: string
                description: Bank state - only if currency is USD
              bank_name:
                type: string
                description: Bank name - only if currency is USD
              bank_country:
                type: string
                description: Bank country - only if currency is USD
              bank_address:
                type: string
                description: Bank address - only if currency is USD
              amount:
                type: integer
                description: amount
                example: 13400
              additional_instructions:
                type: string
                description: Additional instructuons - only if currency is USD
              account_number:
                type: string
                description: account number
                example: 23768954
            description: Deposit parameters
      description: List of deposits and next_token
    ErrorChangesetResponse:
      title: Error changeset response
      required:
      - errors
      - message
      type: object
      properties:
        message:
          type: string
          description: Message why request didn't succeed
          example: Invalid credentials
        errors:
          type: object
          properties: {}
          description: Map of errors
      description: Error response for request which manipulates 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