Download OpenAPI specification:Download
Hi there,
Welcome to Our Bamboo API Documentation!
In line with our focus on democratizing access to the global capital markets for Africans, we decided to make our APIs available to partner institutions.
Here you will find comprehensive information on how to integrate and utilize our PBB API set. Whether you're a developer, a business owner, or an enthusiast, this documentation will guide you through the process of leveraging our powerful API capabilities. Get ready to unlock new possibilities and enhance your applications with our intuitive and feature-rich APIs. Let's dive in!
Bamboo aims to provide access to both global and local stock markets and we are doing that by providing pretty much all the endpoints that will enable you to;
- Build the necessary infrastructure to enable your users trade securities in the US Stock market.
- Set up accounts for users that will allow them to make deposits, withdrawals and place trades within the system.
- Share real-time market data with your users to encourage investment.
- Show users their portfolio status and handle money movement.
- Monitor real-time user and business performance and make necessary business decisions.
- And many more.
Getting started isn't difficult. 😊
Before we delve into the details, it's essential to clarify the terminologies we use at Bamboo. In our system, we categorize developers, business owners, and all our partner institutions as "Tenants." On the other hand, we refer to the individuals associated with these tenants, such as customers or clients, as "Users".
Throughout this document, you will come across the terms "Tenants" and "Users" frequently, representing these distinct categories of people. We want to ensure clarity and avoid any confusion as you navigate our API documentation. If you have any questions or need further clarification, you can reach out to our support team at partnersupport@investbamboo.com. We're here to assist you!
This section serves as a guide to the available methods, parameters, and responses provided by the API.
Developers can refer to the API Reference section to gain a clear understanding of how to interact with the API, what data to provide in API requests, and how to handle the API responses.
Requests and Responses
We provide the API endpoints, request body schema and sample responses next to each method to help guide your tests. All you need to do is insert your specific parameters, and you can test the calls on your command line.
Both request body data and response data are formatted as JSON. The content type for responses will always be application/json.
HTTP Methods, Parameters and Status Codes
We support the following HTTP methods: GET, PUT, POST, and PATCH. The required parameters for each endpoint may vary, and you can find detailed information about these parameters, as well as any optional parameters, in the corresponding documentation for each endpoint.
For successful requests, Bamboo returns an HTTP 200 status code and for failed requests, Bamboo returns 4xx codes. We discuss some common codes and their meanings below:
Response Code | Meaning | Description |
---|---|---|
200 | Success | This code is used for every successful request made. |
400 | Bad request | This is used to indicate that a tenant has performed an incorrect action, such as uploading a user's BVN instead of their phone number, using the provided endpoint. |
401 | Invalid credentials or token | This means that the credentials or token provided are invalid or unauthorised. Check your input and try again. |
404 | Resource not found | This signifies that a tenant's attempt to fetch a user by their provided credentials, such as a phone number, did not match any records in the database, indicating potential non-registration or unavailability of the requested information. |
409 | Account exists | Account already exists. Please log in. |
422 | Incorrect/Incomplete parameters | This is used when incorrect parameters have have been imputed or some compulsory values in the request body are incomplete. A map of errors is usually shown to help guide resolution. |
422 | Unprocessable entity | The message was well formatted but failed due to semantic errors. Please check your parameters and try again. |
422 | Invalid ID information | This code means your information was not correct. Please check your input or contact support for further assistance. |
422 | Error Response | This is used to communicate when an accepter or broker parameter is invalid. |
To start using Bamboo’s APIs, you first need to Set up a Sandbox account. The Bamboo integration team will provide your test credentials after business agreements have been signed. The sandbox server for test purposes is available under the address:
https://powered-by-bamboo-sandbox.investbamboo.com/
It's an exact copy of the production environment with a separate database. It can be used for any kind of testing without violating data consistency in a production environment.
After tests are concluded, access to the production environment will also be provided.
When a tenant wants to send requests to the sandbox server, the tenant would need to authorize such request.
To achieve this, every request is required to include an access token and the tenant’s unique "app_key" which will be provided by the Bamboo integration team when provisioning the tenant’s account credentials.
It is important to note that for every user interaction within the Bamboo System, authentication is required which allows us verify a user's identity before they can interact with their account. A tenant is expected to pass their x-client-token which is the unique tenant authorisation token, the x-subject-type with "tenant" as the value and the x-user-id which holds the user's ID in the header for each user requests.
Generate Access Token
The tenant access token is called the "x-client-token" within Bamboo's system. This token can be fetched using this endpoint.
header Parameters
content-type required | string Example: application/json Advertises which content type is acceptable. |
accept-language required | string Example: en Advertises which languages the tenant is able to understand. For example, 'en' for English Language. |
app-key required | string Example: 1755d3dd-e6b9-4df1-9537-eb9017da70g9 Application key that uniquely identifies a tenant as an API consumer. |
Request Body schema: application/json
Login Credentials
username required | string Username |
password required | string Password |
Responses
Request samples
- Payload
{- "username": "new-horizon-investments",
- "password": "32qC6I2U5J-0i73zJDEdapFJvwICJAl1I7ScekqupVfouiAMz_J7obWHI3kuDVOL"
}
Response samples
- 200
- 401
- 422
{- "tenant": {
- "access_token": "eyJhbGciOlJSUzI1NlIsInR5cCI6IkpXVCIbLmtpZCI7Ikx6aTZoUVRwc2gtS21BNjdzbXdCWiJ9.eyGodHRwczovL2V4YW1wbGUuY29tL2NsYWltIjoiYmFyIiwiaXNzIjoiaHR0cHM6Ly9pbnZlc3RiYW1ib28uYXV0aDAuY29tLyIsInN1YiI6IjVOczMzZHJDek84S01PUmNBYmNvVkU3VEpRa1daVGFTQGNsaWVudHMiLCJhdWQiOiJodHRwczovL3N0YWdpbmctYXBpLmludmVzdGJhbWJvby5jb20vIiwiaWF0IjoxNjk0MTg1Nzg1LCJleHAiOjE2OTQyNzIxODUsImF6cCI6IjVOczMzZHJDek84S01PUmNBYmNvVkU3VEpRa1daVGFTIiwic2NvcGUiOiJyZWFkOmJhbWJvb19kYXRhIGV4dHJhIiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIn9.EcjJWlqQ7Um1gJRd7PMNteuKDILT3RgZQjVd6HfcV95YDyKZ9WXmDgiKpaTjKvnEuCtG21W_jKaaXc1s9piFR9zhVJcFF2wv1hh7dURNKsVg52jplD4QVgFpU5FtMbCGAQlSbVDj5UA0ss7VeK_RYJysCuOltRPtvKyBCx_KXblDl1YJbiyNkmR4SJRvuI_qDkgrq2VuHtzu6b-mYf5Zp9nTtqkK-GTWQuHC6leQTP87WAK52nEstteIQea7KXXuJP8Evpo_ncuU1vXYgF3ilESp_lWcheTQWrl3nekQunTw4KbDqYG9-U92jCTRTra--m0fiR5lmVXh6uAE4j8wSg",
- "expires_in": 86400
}
}
Registration is the first step before users can access the Bamboo system. We offer a streamlined one-step registration endpoint to simplify this process for tenants with verified KYC processes. (This means that you have conducted KYC for your users and are confident of their identity)
Create New User
This endpoint combines all registration steps into a single API call. To use this endpoint, you must provide all fields in the defined payload and ensure that the user’s ID has been verified.
All images should be in Base64 format. The front_id_image
and back_id_image
fields should contain the front and
back pages of the user's identity document, respectively, and are required only for Ghana and South Africa accounts.
A dictionary endpoint is provided below to give insight into all the questions and acceptable values for the fields within the payload.
header Parameters
content-type required | string Example: application/json Advertises which content type is acceptable. |
accept-language required | string Example: en Advertises which languages the tenant is able to understand. For example, 'en' for English Language. |
x-request-source required | string The tenant's username |
x-client-token required | string API Consumer Authorisation Token |
Request Body schema: application/json
Register credentials. (Provide details to subscribe to at least one market)
required | object (User basic info) |
required | object (User verified identity info) |
required | object (Affiliation info) |
required | object (Brokerage account info) |
Responses
Request samples
- Payload
{- "basic_info": {
- "residence_country_code": "NGA",
- "province": "Lagos State",
- "postal_code": "+234",
- "referral_code": "113792",
- "phone_number": "+2347083864023",
- "password": "Password@123",
- "last_name": "Doe",
- "gender": "Man",
- "first_name": "John",
- "date_of_birth": "1927-02-19",
- "country_code": "NGA",
- "city": "Lagos",
- "citizenship": "Nigerian"
}, - "verified_identity_info": {
- "address": "22 Babatunde Anjous Lekki",
- "city": "Lekki",
- "date_of_birth": "1927-02-19",
- "document_type": "BVN",
- "email": "string",
- "expiration_date": "2026-10-10",
- "full_name": "John Doe",
- "gender": "Man",
- "identifier": "22488743663",
- "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAB9gA...",
- "front_id_image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAB9gA...",
- "back_id_image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAB9gA...",
- "phone_number": "+2347083864023",
- "residence_country": "NGA",
- "state": "Lagos"
}, - "affiliation_info": {
- "director_of": "",
- "broker": false
}, - "brokerage_account_info": {
- "employment_status": "SELF_EMPLOYED",
- "yearly_income": 12500,
- "source_of_wealth": "COMPANY",
- "risk_tolerance": "LOW",
- "position": "AUDITOR",
- "net_worth": 62500,
- "marital_status": "MARRIED",
- "liquid": 12500,
- "goal": "FREQUENT",
- "experience": "NONE",
- "employment_type": "AGRICULTURE",
- "dependents": 2,
- "company": "Phil Technologies LTD."
}
}
Response samples
- 200
- 401
- 404
{- "expiration_time": 1697532406,
- "jwt": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ3ZWIiLCJleHAiOjE2OTc1MzI0MDYsImlhdCI6MTY5NDk0MDQwNiwiaXNzIjoid2ViIiwianRpIjoiMTE5MGRjMDEtZjQxNS00NmQ3LWFjOTctYzM5M2Y2MWEzYWJjIiwibmJmIjoxNjk0OTQwNDA1LCJyZXNpZGVuY2VfY291bnRyeSI6Ik5HQSIsInN1YiI6NTc3MSwidHlwIjoiYWNjZXNzIn0.GN3THXBJPynv0BcKuWKc84UHexAD22iGtO8A7kSjR92VKxLaiXxz0bDC-CEa8pVKum3oVwjjdRdAXeJL6c4Tsw",
- "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ3ZWIiLCJleHAiOjE2OTczNTk2MDYsImlhdCI6MTY5NDk0MDQwNiwiaXNzIjoid2ViIiwianRpIjoiYWQ4MDA2MzMtMWU4Ny00MGQ0LWFkMTMtNzc4YjY0M2JlNWQwIiwibmJmIjoxNjk0OTQwNDA1LCJyZXNpZGVuY2VfY291bnRyeSI6Ik5HQSIsInN1YiI6NTc3MSwidHlwIjoicmVmcmVzaCJ9.a5Vn2ApDrDBnroDk-7n3neJOuZPDOJxSP29V85rej_eKx4w0JiJ112-tghkSi3xijf0RSkw_AeVq-9sS7bjr0w",
- "user": {
- "application_id": 50083181,
- "bvn_api_fail": false,
- "date_of_birth": "1927-02-19",
- "first_name": "John",
- "full_name": "John Doe",
- "id": 4101,
- "last_name": "Doe",
- "name": "John",
- "phone_number": "+2347083864023",
- "registration_step": "Pending review",
- "surname": "Doe"
}
}
View User Profile
This endpoint fetches a user's profile.
header Parameters
content-type required | string Example: application/json Advertises which content type is acceptable. |
accept-language required | string Example: en Advertises which languages the tenant is able to understand. For example, 'en' for English Language. |
x-user-id required | string Required for user authentication |
x-subject-type required | string For user request -> 'tenant'. |
x-client-token required | string API consumer token |
Responses
Response samples
- 200
- 401
- 404
{- "surname": "Doe",
- "street": "4383 Ms. Godspower Savage Squares, Ngaski Lagos",
- "province": "Lagos State",
- "postal_code": "+234",
- "phone_number": "+2347083864023",
- "next_of_kin": "Phil Doe",
- "name": "John",
- "gender": "Man",
- "engagement_status": "no_trade",
- "email_verified": false,
- "city": "Lekki",
- "citizenship": "Nigeria",
- "carrot_integration_status": "not_available",
- "age": 96,
- "account_restriction": {
- "restricted": false,
- "reason": "Account is under review"
}, - "account_number": "84861889"
}
Update User Password
This endpoint is used to update a user's password.
header Parameters
content-type required | string Example: application/json Advertises which content type is acceptable. |
accept-language required | string Example: en Advertises which languages the tenant is able to understand. For example, 'en' for English Language. |
x-user-id required | string Required for user authentication |
x-subject-type required | string For user request -> 'tenant'. |
x-client-token required | any API consumer token |
Request Body schema: application/json
New password
password required | string Actual password |
new_password required | string New password |
Responses
Request samples
- Payload
{- "password": "Password@123",
- "new_password": "Password@123!"
}
Response samples
- 200
- 401
- 422
"Successful"
This section provides the necessary endpoints for managing user deposits. User deposits are made in two steps, then the actual cash exchange (settlement) happens offline between our settlement team and yours.
Notification Request: To make a deposit, we require you to send a notification request with the necessary details to credit the user's brokerage account. Upon receiving the request, a record is created in our system and then we run verification checks to confirm the deposit source.
Verification: This is done using a verification endpoint you would provide to our integration team during account set-up. Once the deposit is verified, the requested amount would be credited into the user's brokerage account.
Use the details below when creating your deposit verification endpoint;
Request Type:
GET
URL Pattern:
THE_URL/deposit/status/UNIQUE_REFERENCE
Required Header: 'hash': 'an_agreed_hash'
Response data:
{ "data": { "status": "failed or settled", "currency": "NGN", "amount": 30.99 }, "status": "failed or settled" }
Create Deposit
This endpoint is used to initiate a deposit request for your users. To get statuses about your deposit, head to the events section.
header Parameters
content-type required | string Example: application/json Advertises which content type is acceptable. |
accept-language required | string Example: en Advertises which languages the tenant is able to understand. For example, 'en' for English Language. |
x-user-id required | string Required for user authentication |
x-subject-type required | string For user request -> 'tenant'. |
x-client-token required | string API Consumer Authorisation Token |
x-request-source required | string The tenant's username |
Request Body schema: application/json
Deposit request
amount_paid required | number Amount to be deposited |
currency required | string Currency |
provider required | string API Consumer Name |
reference required | string Deposit reference |
phone_number required | string User phone number |
transaction_date required | string Amount to be deposited |
Responses
Request samples
- Payload
{- "amount_paid": 5000,
- "currency": "NGN",
- "provider": "new-horizon-investments",
- "reference": "INVcal2VzeVGJkCXNx",
- "phone_number": "+2348036477166",
- "transaction_date": "2022-02-02"
}
Response samples
- 200
- 400
- 422
""
Fetch All Deposits
This endpoint is used to view a paginated list of all deposits made for your users.
query Parameters
limit | string Number of requested results default=20 |
next_token | integer Next token for pagination |
start_date | string Unix datetime stamp |
end_date | string Unix datetime stamp |
header Parameters
accept_language required | string Accepted format. For example 'application/json' |
x-user-id required | string Required for user authentication |
x-subject-type required | string For user request -> 'tenant'. |
x-client-token required | string API Consumer Authorisation Token |
x-request-source required | string The tenant's username |
Responses
Response samples
- 200
- 401
{- "next_token": 10,
- "deposits": [
- {
- "user_surname": "Doe",
- "user_name": "John",
- "user_id": 5804,
- "txref": "b5c58aa9-7ebb-49cd-b756-b21d8d3421cd-1696688177",
- "status": "pending",
- "phone_number": 8033741268,
- "id": 5804,
- "created_at": "2022-02-02 01:10:20 UTC",
- "api_consumer_name": "new-horizon-investments",
- "api_consumer_id": 1,
- "account": "string",
- "example": null
}
]
}
Fetch Deposit by User ID
This endpoint is used to gather all the deposits that have been made by a particular user within a specified time frame.
query Parameters
limit | string Number of requested results default=20 |
next_token | integer Next token for pagination |
start_date | string Unix datetime stamp |
end_date | string Unix datetime stamp |
header Parameters
accept_language required | string Accepted format. For example 'application/json' |
x-user-id required | string Required for user authentication |
x-subject-type required | string For user request -> 'tenant'. |
x-client-token required | string API Consumer Authorisation Token |
x-request-source required | string The tenant's username |
Responses
Response samples
- 200
- 401
{- "next_token": 10,
- "deposits": [
- {
- "user_surname": "Doe",
- "user_name": "John",
- "user_id": 5804,
- "txref": "b5c58aa9-7ebb-49cd-b756-b21d8d3421cd-1696688177",
- "status": "pending",
- "phone_number": 8033741268,
- "id": 5804,
- "created_at": "2022-02-02 01:10:20 UTC",
- "api_consumer_name": "new-horizon-investments",
- "api_consumer_id": 1,
- "account": "string",
- "example": null
}
]
}
Fetch Deposit Status
This endpoint is used to get the status of a deposit.
header Parameters
accept_language required | string Accepted format. For example 'application/json' |
x-user-id required | string Required for user authentication |
x-subject-type required | string For user request -> 'tenant'. |
x-client-token required | string API Consumer Authorisation Token |
x-request-source required | string The tenant's username |
Responses
Response samples
- 200
- 401
{- "amount": 100.02,
- "currency": "USD",
- "status": "Settlemented",
- "txref": "21b94e1d-75d6-45b7-bb60-28126a7f170d"
}
This section contains all endpoints for users withdrawals.
To make a withdrawal, we require you to send a notification request with the necessary details to debit the user's brokerage account. Upon receiving the request, a record is created in our system and upon confirmation from the broker, we mark the withdrawal as successful.
Please note that the actual cash exchange (settlement) happens offline between our settlement team and yours.
Create Withdrawal
This endpoint is used to withdraw from users' withdrawable cash balances.
header Parameters
content-type required | string Example: application/json Advertises which content type is acceptable. |
accept-language required | string Example: en Advertises which languages the tenant is able to understand. For example, 'en' for English Language. |
x-user-id required | string Required for user authentication |
x-subject-type required | string For user request -> 'tenant'. |
x-client-token required | string API Consumer Authorisation Token |
Request Body schema: application/json
tenant withdraw body parameter for NGN
currency required | string currency |
amount required | integer amount |
reference required | string reference |
Responses
Request samples
- Payload
{- "currency": "NGN",
- "amount": 13400,
- "reference": "INVKPxiJVc40BNaQBH"
}
Response samples
- 200
- 401
- 422
""
Fetch All Withdrawals
This endpoint returns a paginated list of all withdrawals made by all users within a specified timeframe.
query Parameters
limit | string Number of requested results default=20 |
next_token | integer Next token for pagination |
start_date | string Unix datetime stamp |
end_date | string Unix datetime stamp |
header Parameters
accept_language required | string Accepted format. For example 'application/json' |
x-user-id required | string Required for user authentication |
x-subject-type required | string For user request -> 'tenant'. |
x-client-token required | string API Consumer Authorisation Token |
x-request-source required | string The tenant's username |
Responses
Response samples
- 200
- 401
{- "next_token": 10,
- "withdrawals": [
- {
- "user_surname": "Doe",
- "user_phone": 8033741268,
- "user_name": "John",
- "user_indentifier": 22388291636,
- "swift_aba_code": "string",
- "status": "pending",
- "reference": "INVKPxiJVc40BNaQBH",
- "intermediary_bank_swift_code": "string",
- "intermediary_bank": "string",
- "id": 5804,
- "fees": "string",
- "exchange_rate": "string",
- "dollar_fees": "string",
- "dollar_amount": 130,
- "currency": "string",
- "created_at": "2022-02-02 01:10:20 UTC",
- "beneficiary_name": "string",
- "bank_zip_code": "string",
- "bank_state": "string",
- "bank_name": "string",
- "bank_country": "string",
- "bank_address": "string",
- "api_consumer_name": "new-horizon-investments",
- "api_consumer_id": 1,
- "amount": 13400,
- "additional_instructions": "string",
- "account_number": 23768954
}
]
}
Fetch User Withdrawals
This endpoint returns a paginated list of all withdrawals made by a particular user within a specified timeframe.
path Parameters
id required | string User ID |
query Parameters
limit | string Number of requested results default=20 |
next_token | integer Next token for pagination |
start_date | string Unix datetime stamp |
end_date | string Unix datetime stamp |
header Parameters
accept_language required | string Accepted format. For example 'application/json' |
x-user-id required | string Required for user authentication |
x-subject-type required | string For user request -> 'tenant'. |
x-client-token required | string API Consumer Authorisation Token |
x-request-source required | string The tenant's username |
Responses
Response samples
- 200
- 401
{- "next_token": 10,
- "withdrawals": [
- {
- "user_surname": "Doe",
- "user_phone": 8033741268,
- "user_name": "John",
- "user_indentifier": 22388291636,
- "swift_aba_code": "string",
- "status": "pending",
- "reference": "INVKPxiJVc40BNaQBH",
- "intermediary_bank_swift_code": "string",
- "intermediary_bank": "string",
- "id": 5804,
- "fees": "string",
- "exchange_rate": "string",
- "dollar_fees": "string",
- "dollar_amount": 130,
- "currency": "string",
- "created_at": "2022-02-02 01:10:20 UTC",
- "beneficiary_name": "string",
- "bank_zip_code": "string",
- "bank_state": "string",
- "bank_name": "string",
- "bank_country": "string",
- "bank_address": "string",
- "api_consumer_name": "new-horizon-investments",
- "api_consumer_id": 1,
- "amount": 13400,
- "additional_instructions": "string",
- "account_number": 23768954
}
]
}
Fetch Withdrawal Status
This endpoint is used to request a withdrawal status for your users.
path Parameters
reference required | string withdrawal reference |
header Parameters
content-type required | string Example: application/json Advertises which content type is acceptable. |
accept-language required | string Example: en Advertises which languages the tenant is able to understand. For example, 'en' for English Language. |
x-user-id required | string Required for user authentication |
x-subject-type required | string For user request -> 'tenant'. |
x-client-token required | string API Consumer Authorisation Token |
x-request-source required | string The tenant's username |
Responses
Response samples
- 200
- 401
{- "status": "pending",
- "reference": "INVKPxiJVc40BNaQBH",
- "currency": "NGN",
- "amount": 13400
}
This section provides all the information a tenant needs to know about a user's investment portfolio values and general user performance.
Fetch User Portfolio
This endpoint returns summarised information of a user's total portfolio value, gains/losses, the value of cash, and pending deposits & withdrawals with regards to the US market.
header Parameters
content-type required | string Example: application/json Advertises which content type is acceptable. |
accept-language required | string Example: en Advertises which languages the tenant is able to understand. For example, 'en' for English Language. |
x-user-id required | string Required for user authentication |
x-subject-type required | string For user request -> 'tenant'. |
currency | string NGN - to get prices in Naira |
x-client-token required | string API consumer token |
Responses
Response samples
- 200
- 401
- 404
- 422
{- "withdrawal_cash": 0,
- "withdraw_details": [
- {
- "country": "Nigeria",
- "name": "John",
- "network": "string",
- "phone_number": "string",
- "user_id": 0,
- "bank_code": "string",
- "bank_fw_id": "string",
- "bank_name": "Sterling Bank",
- "account_number": "0211873910",
- "beneficiary_name": "John Doe"
}
], - "value_percent_change": 0,
- "value_change": 0,
- "value": 0,
- "user_currency_to_usd": 0.001152073732718894,
- "user_currency_symbol": "₦",
- "usd_to_user_currency": 868,
- "usd_to_naira": 868,
- "unsettled_cash": 0,
- "total_cash": 0,
- "residence_country": "NGA",
- "reserved_cash": 0,
- "referral_cashback_blocked_value": 0,
- "processing_withdrawal": 0,
- "processing_gift_sent": 0,
- "processing_gift_received": 0,
- "pending_deposit": 0,
- "naira_to_usd": 0.001152073732718894,
- "dollar_cash": 0,
- "dollar_balance": 0,
- "currency_symbol": "₦",
- "currency_name": "Nigerian Naira",
- "currency_code": "NGN",
- "cash": 0,
- "carrot_held_value": 0,
- "base_wallet_balance": 0,
- "actual_value": 0,
- "account_restricted": false
}
Fetch User Portfolio Breakdown
This endpoint provides information about the user’s good faith violation, restrictions possibly put on the user’s account, money available for the user to invest or withdraw and the user’s overall performance on investments and return.
header Parameters
content-type required | string Example: application/json Advertises which content type is acceptable. |
accept-language required | string Example: en Advertises which languages the tenant is able to understand. For example, 'en' for English Language. |
x-user-id required | string Required for user authentication |
x-subject-type required | string For user request -> 'tenant'. |
currency | string NGN - to get prices in Naira |
x-client-token required | string API consumer token |
Responses
Response samples
- 200
- 401
- 404
- 422
{- "withdrawable_cash": 0,
- "value": 0,
- "total_return": 0,
- "total_percent_change": 0,
- "total_invested": 0,
- "total_aum": 0,
- "restricted_by_dw": false,
- "number_of_violations": 0,
- "equity_value": 0,
- "currency_symbol": "$",
- "base_wallet_balance": 0,
- "available_to_invest": 0
}
The section provides us endpoints that allows a client to fetch all the information pertaining to the US stocks available on Bamboo. Stocks can be categorized into themes.
Fetch List of All Stocks
This endpoint fetches the list of stocks with basic information about them like their symbol and logo.
query Parameters
limit | string Number of requested results. (Default = 20) |
next_token | integer Next token for pagination |
header Parameters
x-user-id required | string Required for user authentication |
x-subject-type required | string For user request -> 'tenant'. |
x-client-token required | string API consumer token |
Responses
Response samples
- 200
- 401
{- "next_token": 10,
- "stocks": [
- {
- "name": "Apple Inc",
- "symbol": "AAPL",
}
]
}
Fetch Stock Details
This endpoint returns comprehensive details of a specific stock, including its pricing information. It is designed to provide users with in-depth insight into the stock.
path Parameters
symbol required | string Stock Symbol |
header Parameters
content-type required | string Example: application/json Advertises which content type is acceptable. |
accept-language required | string Example: en Advertises which languages the tenant is able to understand. For example, 'en' for English Language. |
x-user-id required | string Required for user authentication |
x-subject-type required | string For user request -> 'tenant'. |
x-client-token required | string API consumer token |
x-request-source required | string The tenant's username |
currency | string NGN - to order in Naira |
Responses
Response samples
- 200
- 401
- 404
- 422
{- "high": null,
- "low": null,
- "name": null,
- "open": null,
- "symbol": "MDY",
- "currency_symbol": "$",
- "price": 200,
- "avatar": "string",
- "story": "When we talk about “the value of branding” and “brand investing”, you need look no further than Apple to understand how important and powerful a well-branded company can be... and how clearly that can be reflected in its share price.\r\n\r\nIn fact, in 2014, Interbrand determined Apple to be the world's most valuable brand and Forbes named Apple the most admired company in the world for five consecutive years.\r\n\r\nThat reputation carries over into each one of its products and services, including the iPhone, iPad, iPod, Mac computer, iTunes, iCloud and the Safari web browser.\r\n\r\nApple was founded by Steve Jobs, Steve Wozniak and Ronald Wayne on April Fools' Day of 1976. Their first product was the Apple 1 Personal Computer Kit and each one was painstakingly hand-built by Wozniak.\r\n\r\nBy the end of the 1970s, Apple had earned enough profits to bring on a full-time staff of computer designers and a legitimate production line.\r\n\r\nIn 1980, Apple went public and generated more capital than any IPO since Ford Motor Company did in 1956.\r\n\r\nIn January 1984, Apple grabbed the world's attention with the introduction of the Macintosh, changing personal computing forever.\r\n\r\nIn 1985, Steve Jobs was ousted, and went on to found NeXT, and also buy Pixar, and eventually returned as CEO in July 1997.\r\n\r\nIn August 1998, Jobs rejuvenated the stagnant Apple with the introduction of the iMac, stunning the tech industry.\r\n\r\nBy the end of 2001, a staple of Apple emerged, the iPod and iTunes, which later evolved into Apple Music. Apple also created the OS X software the same year, which was later used to power the iPhone, iPad, and Apple Watch.\r\n\r\nIn January 2007, Apple unveiled its first iPhone, and we all know how that story goes. Since then, Apple has sold more than 2 billion units. \r\n\r\nIn the following 3 years, the iPhone was improved, while the iPad and Apple TV were developed. \r\n\r\nIn 2011, Jobs, who had been diagnosed with pancreatic cancer, resigned as CEO and became chairman of the board. Tim Cook was named the new CEO in August of that year. Six weeks later, Jobs succumbed to his illness, and his death provoked widespread mourning as well as statements from Bill Gates, George Lucas and President Barack Obama.\r\n\r\nUnder Tim Cook’s leadership, the company has continued its astounding growth. In 2015, Apple released the Apple Watch, the first entirely new product in the post-Jobs era.\r\n\r\nIn 2016, Apple released the AirPods — a new wireless earphone. \r\n\r\nIn 2018, Apple became the first US company to be valued above $1 trillion.\r\n\r\nMarch 2019 - After more than four decades making money primarily by selling gadgets, Apple said it intended to expand efforts in monthly subscriptions. The company has expanded services in news, streaming, music, video-games and more. \r\n\r\nAs of 2020, the company’s wearables segment, including the Apple Watch and AirPods, had overtaken the Mac in revenue generation. The same year the company announced the Apple HomePod. \r\n\r\n_MyWallSt operates a full disclosure policy. MyWallSt staff hold long positions in this stock._",
- "background_color": "ff9201",
- "percent_change": 1.4200000000000002,
- "price_change": 2.8,
- "earnings": [ ],
- "avg_volume": 43464062,
- "dividend_yield": 43464062,
- "latest_update": 43464062,
- "latest_volume": 43464062,
- "market_cap": 2081325483000,
- "pe_ratio": 2081325483000,
- "wk_52_high": 2081325483000,
- "wk_52_low": 2081325483000,
- "short_description": "Apple is one of the world's largest companies. Its most well-known products are the iPhone, iPod and MAC computer. Apple is currently the world's most valuable brand.",
- "about": {
- "sector": "Manufacturing",
- "description": "Apple Inc. is an American multinational technology company headquartered in Cupertino, California. Apple is the worlds largest technology company by revenue, with US$394.3 billion in 2022 revenue. As of March 2023, Apple is the worlds biggest company by market capitalization.",
- "ceo": "Timothy Cook"
}, - "categories": [ ],
- "opinion": {
- "points": [
- "Massive cash reserves",
- "Proven pricing power",
- "Strong customer loyalty"
], - "text": "There’s a scene in the 1994 film 'Forrest Gump' where the protagonist casually announces that due to an investment in “some kind of fruit company”, he wouldn’t have to worry about money any more. How many people watched that scene at the time of its release and thought they’d missed the boat on an investment in Apple?\r\n\r\nThe stock is currently up over 15,000% since.\r\n\r\nNow worth roughly $2 trillion and boasting 1.65 billion active devices, I still believe there are plenty of reasons to be an Apple investor.\r\n\r\nThe world’s largest public company has been accused of failing to be truly innovative in a post-Jobs era. While the annual keynote from Cupertino may not attract the same fervour as it did during the release of the first iPod or iPhone, behind the scenes Tim Cook is slowly building a robust and highly-profitable services business. The App Store, Apple Pay, and Apple Music are all becoming an integral part of this business story. Between 2016 and 2020, the company managed to double its services revenue and quarter after quarter this segment continues to grow. Thanks to its consistent new offerings, such as Apple Fitness+, Apple now has over 620 million paid subscriptions. This considerable consumer base now allows the brand to turn towards cross-selling and up-selling in the the form of Apple One, a bundling service which will combine popular offerings and encourage consumers to pay one, flat fee. \r\n\r\nNotable innovation also comes in the form of wearables, such as as the Apple Watch and AirPods, which continue to lure new buyers with their tiered, accessible pricing. As of 2020, the segment now generates more revenue than Mac computers and this growth doesn't seem to be slowing down, analysts expect the wearable market to expand between 15-25% annually. The Apple Watch dominates its competition, controlling 36% market share, and with the release of Apple Fitness+, it becomes a viable option within the connected fitness space. \r\n\r\nImportantly, while iPhone sales slowed in 2019 and became a concern for investors, the release of the iPhone 12 and its 5G capability brought this segment record-setting sales figures. The first quarter of 2021 saw 17% revenue growth year-over-year. \r\n\r\nThis combination of hardware, software, and services creates a sticky ecosystem that leads to lifelong customers. Combined with its powerful brand (the most valuable in the world), Apple are able to maintain high margins, which generates huge amounts of cash for research and development, stock buybacks, and dividends. Their balance sheet was so impressive that Warren Buffett, who typically avoids tech companies, loaded up on Apple stock over the last few years, becoming one of their largest shareholders.\r\n\r\nThat being said, investors and Apple must keep their eyes on the horizon as the company faces scrutiny for its monopoly of the App Store. It is unclear if the current administration will take action against the company but Apple did acknowledge this as a risk to its financial condition in its most recent annual report. \r\n\r\nDespite this, Apple's dedication to innovation has granted it years of growth and capital. Combined with the company's talent, experience, and brand, it should continue to overcome obstacles and succeed. \r\n\r\nApple is the king of consumer hardware and its stock would be a great bedrock for any portfolio.",
- "update_date": "2023-09-25T06:54:25"
}, - "data_source": "IEX Trading Group, DriveWealth"
}
Search Stocks
This endpoint searches for a stock by a given query phrase or a set of phrases. Below, you would find the query parameters and a description for how it is used.
The acceptable values of the sorting parameter are;
Alphabetical ASC - alphabetical:asc
,
Alphabetical DSC - alphabetical:desc
,
Price - price:asc
,
Percentage Change - percent_change:asc
,
Market Cap - market_cap:asc
,
P/E Ratio - pe_ratio:asc
,
EPS - eps:asc
,
Div/Yield - div_yield:asc
,
Volume - volume:asc
.
The acceptable values of the filters parameter are;
Price Above - price;a:${value}
,
Price Below - price;b:${value}
,
percent Change Above - percent_change;a:${value}
,
percent Change Below - percent_change;b:${value}
,
Market Cap Above - market_cap;a:${value}
,
Market Cap Below - market_cap;b:${value}
,
P/E Ratio above - pe_ratio;a:${value}
,
P/E Ratio below - pe_ratio;b:${value}
,
EPS Above - eps;a:${value}
,
EPS below - eps;b:${value}
,
DIV/Yield Above - div_yield;a:${value}
,
DIV/Yield Below - div_yield;b:${value}
,
Volume Above - volume;b:${value}
,
Volume Below - volume;b:${value}
,
My Stocks - my_stocks
,
Top Gainers - top_gainers
,
Top Losers - top_losers
.
(Note that ${value}
will be replaced with the value entered by the customer)
query Parameters
query | string Query phrase to match stock name or symbol |
theme_id | string Theme id to filter by. This takes only one value |
sorting | string Example: sorting=alphabetical:asc Used to sort the search either by ascending order, descending order, etc. The acceptable values are stated in the description above. |
filters | string Example: filters=price;a:10, price;b:50 Used to filter the search by providing certain string values separated by a comma. The expected values to be passed for the filters param are stated in the description above. |
header Parameters
content-type required | string Example: application/json Advertises which content type is acceptable. |
accept-language required | string Example: en Advertises which languages the tenant is able to understand. For example, 'en' for English Language. |
x-user-id required | string Required for user authentication |
x-subject-type required | string For user request -> 'tenant'. |
x-client-token required | string API consumer token |
Responses
Response samples
- 200
- 401
{- "currency_symbol": "$",
- "result": [
- {
- "value_change": 0,
- "user_equity": 0,
- "total_return": 0,
- "symbol": "MDY",
- "quantity": 0,
- "name": "S&P MidCap 400 ETF SPDR",
- "favourite": false,
- "background_color": "FFFFFF",
}
]
}
Fetch User Stock Ownership
This endpoint is used to get the list of stocks a user owns.
header Parameters
content-type required | string Example: application/json Advertises which content type is acceptable. |
accept-language required | string Example: en Advertises which languages the tenant is able to understand. For example, 'en' for English Language. |
x-user-id required | string Required for user authentication |
x-subject-type required | string For user request -> 'tenant'. |
x-client-token required | string API consumer token |
x-request-source required | string The tenant's username |
currency | string NGN - to order in Naira |
Responses
Response samples
- 200
- 401
- 404
- 422
{- "currency_symbol": "$",
- "equity_value": 2267.91,
- "stocks": [
- {
- "name": "Apple Inc",
- "symbol": "AAPL",
- "quantity": 3.769942,
- "price": 234.8,
- "total_return": 226.94,
- "total_percent_change": 34.45,
- "background_color": "22222",
- "value_change": 16.51,
- "cost_basis": 658.69,
- "market_price": 234.8,
- "percent_change": 1.848,
- "user_equity": 885.1823816,
- "market_cap": 3600442453600,
- "pe_ratio": 35.21420936835709,
- "div_yield": null,
- "eps": 6.43,
- "volume": 31018872,
- "favourite": false
}, - {
- "name": "First Trust Exchange-Traded Fund III - First Trust NASDAQ Cybersecurity ETF",
- "symbol": "CIBR",
- "quantity": 0.27618859,
- "price": 58.24,
- "total_return": 2.09,
- "total_percent_change": 14.93,
- "background_color": "FFFFFF",
- "value_change": 0.16,
- "cost_basis": 14,
- "market_price": 58.24,
- "percent_change": 0.971,
- "user_equity": 16.0852234816,
- "market_cap": 6892704116,
- "pe_ratio": 0,
- "div_yield": null,
- "eps": 0,
- "volume": 240146,
- "favourite": false
}
]
}
The stock trading section details all the endpoints needed to calculate and make trade orders for all US stock available on Bamboo. Please note that trade charges are applicable and should be agreed upon with the business team. During system setup, the agreed charges would be applied by the integration team.
Calculate Order
This endpoint is used to calculate an order request to help determine if a user can proceed with their desired BUY or SELL order. Please note that there are three types of orders that can be placed, MARKET, LIMIT and STOP.
MARKET
: means you want to buy or sell the stock at the current market price.
LIMIT
: means you want to buy or sell the stock at a price below the current market price. The goal is to buy at a cheaper price that you set yourself.
STOP
: means you want to buy or sell the stock at a price above the current market price. This is a way to catch a stock on the way up.
header Parameters
content-type required | string Example: application/json Advertises which content type is acceptable. |
accept-language required | string Example: en Advertises which languages the tenant is able to understand. For example, 'en' for English Language. |
x-user-id required | string Required for user authentication |
x-subject-type required | string For user request -> 'tenant'. |
x-client-token required | string API Consumer Authorisation Token |
x-request-source required | string The tenant's username |
currency | string NGN - to order in Naira |
Request Body schema: application/json
Order params
type required | string Default: "MARKET" Order type options: |
symbol required | string Default: "DDD" Stock symbol |
amount required | number Default: 100000 amount |
price required | number Default: 0.51 price |
price_per_share required | number Default: 0.51 Price per share |
side required | string Default: "BUY" side |
Responses
Request samples
- Payload
{- "type": "MARKET",
- "symbol": "DDD",
- "amount": 100000,
- "price": 0.51,
- "price_per_share": 0.51,
- "side": "BUY"
}
Response samples
- 200
- 401
- 422
{- "fee": 49,
- "order_price": 4900,
- "total_price": 4949,
- "number_of_violations": 0,
- "gfv_occurs": false,
- "currency_symbol": "$",
- "blocked_quantity": 0,
- "quantity": 0,
- "price_per_share": 0
}
Place Order
If the user is eligible to make trades, this endpoint is used to place an order using the result of the calculate order endpoint.
header Parameters
content-type required | string Example: application/json Advertises which content type is acceptable. |
accept-language required | string Example: en Advertises which languages the tenant is able to understand. For example, 'en' for English Language. |
x-user-id required | string Required for user authentication |
x-subject-type required | string For user request -> 'tenant'. |
x-client-token required | string API Consumer Authorisation Token |
x-request-source required | string The tenant's username |
currency | string NGN - to order in Naira |
Request Body schema: application/json
Order params
fee required | number Default: 0.01 Fee from calculate order response for all order types |
order_type required | string Default: "MARKET" Order type options: |
quantity required | number Default: 1.941176 Order quantity in share amounts for all order types. |
total_price required | number Default: 1 Total invested price, without fee |
price_per_share required | number Default: 8.27 Price per share for all order |
side required | string Default: "BUY" Order side options: |
symbol required | string Default: "DDD" Stock symbol to |
Responses
Request samples
- Payload
{- "fee": 0.01,
- "order_type": "MARKET",
- "quantity": 1.941176,
- "total_price": 1,
- "price_per_share": 8.27,
- "side": "BUY",
- "symbol": "DDD"
}
Response samples
- 200
- 401
- 404
- 422
{- "order_id": "string"
}
Fetch Order Status
This endpoint is used to check for the status of an order that has been placed.
path Parameters
id required | string Order id |
header Parameters
content-type required | string Example: application/json Advertises which content type is acceptable. |
accept-language required | string Example: en Advertises which languages the tenant is able to understand. For example, 'en' for English Language. |
x-user-id required | string Required for user authentication |
x-subject-type required | string For user request -> 'tenant'. |
x-client-token required | string API Consumer Authorisation Token |
x-request-source required | string The tenant's username |
Responses
Response samples
- 200
- 401
- 404
- 422
{- "update_reason": "string",
- "type": "string",
- "symbol": "string",
- "stop_price": 0,
- "side": "string",
- "quantity": 0,
- "price": 0,
- "order_status": "string",
- "name": "string",
- "naira_price": null,
- "naira_fee": null,
- "logo": "string",
- "limit_price": 0,
- "id": "string",
- "dollar_price": null,
- "dollar_fee": null,
- "created_when": "string",
- "commision": "string",
- "background_color": "string",
- "avatar": "string"
}
View Pending Orders
This endpoint is used to check for all the pending orders made by users.
header Parameters
content-type required | string Example: application/json Advertises which content type is acceptable. |
accept-language required | string Example: en Advertises which languages the tenant is able to understand. For example, 'en' for English Language. |
x-user-id required | string Required for user authentication |
x-subject-type required | string For user request -> 'tenant'. |
x-client-token required | string API Consumer Authorisation Token |
x-request-source required | string The tenant's username |
currency | string NGN - to get prices in Naira |
Responses
Response samples
- 200
- 401
- 422
{- "pending_orders": [
- {
- "type": "string",
- "symbol": "string",
- "status": "string",
- "side": "string",
- "quantity": 0,
- "price_per_share": 0,
- "order_price": 0,
- "order_expiration_timestamp": 0,
- "number": "string",
- "name": "string",
- "logo": "string",
- "limit_expiration": "string",
- "id": "string",
- "creation_timestamp": 0,
- "created_at": "string",
- "background_color": "string",
- "avg_price": 0,
- "avatar": "string"
}
], - "currency_symbol": "$"
}
Cancel Order
This endpoint is used to cancel a pending order.
path Parameters
id required | string Order id |
header Parameters
content-type required | string Example: application/json Advertises which content type is acceptable. |
accept-language required | string Example: en Advertises which languages the tenant is able to understand. For example, 'en' for English Language. |
x-user-id required | string Required for user authentication |
x-subject-type required | string For user request -> 'tenant'. |
x-client-token required | string API Consumer Authorisation Token |
x-request-source required | string The tenant's username |
currency | string NGN - to order in Naira |
Responses
Response samples
- 200
- 401
- 404
- 422
null
Events are a result of account or transaction status change within the Bamboo system. This section sets forward events published to Tenants through the PubSub mechanism for the change in status of accounts and transactions sent to the Bamboo system.
When a user account is created on the PBB system, a brokerage account is also created for the user after the user details are verified, the possible statuses for a brokerage account creation request are provided in the table below.
When these status changes on the user account events will be triggered. The user's account is ready for activities like deposits or placing trades when the "Account Live" event is triggered.
Status | Description | Events available |
---|---|---|
Account Live | User brokerage account is created and ready for trading | Yes |
Account Rejected | User brokerage account creation request is rejected by brokerage partners. Please contact our Admin | Yes |
{
event: "brokerage_account_update",
payload: {
"status": "Account Live",
"user_id": 12345
}
}
Deposits are transaction types that put funds into the users brokerage account, the only way for Bank Tenant users to deposit money into Bamboo is through a deposit webhook which is verified through a service provided by the Tenant.
All deposits are created with a default pending status and transition into the final states of the transaction after verification. The following are the valid transaction status in relation to Bamboo.
Funds are available for a Bank Tenant user to use for trading when the deposit status is “Settlemented”.
Status | Description | Events available |
---|---|---|
Accepted | Payment has been received by Bamboo | Yes |
Settlemented | Fund has been credited to brokerage account | Yes |
Deleted | Reference doesn't exist (unable to verify from Tenant) | Yes |
Pending | Awaiting verification from Tenant | Yes |
Event Structure
{
event: "deposit_status_update",
payload: {
"amount": 5000.00,
"amount_paid": 4950.00,
"currency": "NGN",
"dollar_amount": 6.25,
"deposit_type": "instant",
"dollar_fee": 0.50,
"dollar_instant_deposit_fee": 0.10,
"dollar_processing_fee": 0.15,
"exchange_rate": "800.00",
"fee": 50.00,
"reference": "AB123456789",
"txref": "TX987654321",
"status": "settlemented"
}
}
Withdrawals are transactions that take funds out of either the user brokerage account or Bamboo system. The following are the valid transaction status in relation to Bamboo.
Status | Description | Events available |
---|---|---|
Sent | Customer’s brokerage account has been debited and funds credited to the tenant. This indicates a successful user withdrawal and the only trigger for disbursing value. | Yes |
Rejected | The withdrawal request failed and we couldn’t retrieve funds from the customer’s brokerage account. | Yes |
Event Structure
{
event: "withdraw_status_update",
payload: {
"account_number": "1234567890",
"additional_instructions": "Please process the withdrawal for this user",
"amount": 1500.00,
"bank_address": "123 Bank Street, Lagos, Nigeria",
"bank_code": "123456",
"bank_country": "NG",
"bank_fw_id": "FW123456",
"bank_name": "Guaranty Trust Bank",
"bank_state": "Lagos",
"bank_zip_code": "100001",
"beneficiary_name": "Bamboo Global Inc",
"brokerage_withdrawal_request_id": 987654321,
"currency": "USD",
"exchange_rate_value": 0.0027,
"fees": 25.00,
"requested_by": "Jane Doe",
"intermediary_bank": "Intermediary Bank Name",
"intermediary_bank_swift_code": "IBSWIFT123",
"reason": "Personal expenses",
"status": "sent",
"reference": "WD123456789",
"swift_aba_code": "SWIFT123456",
"account_currency": "NGN"
}
}
The process of buying and selling stocks triggers a number of events from trade initiation to its fulfillment or rejection.
Trade status can also be retrieved through an api call at any point from the time of placing the order using the GET Order Status endpoint. The following are the set of trade events fired at the different status changes.
Status | Description | Events available |
---|---|---|
New | The order has been sent to the broker and its received | Yes |
Filled | The order has been filled and should be visible on the Tenant app | Yes |
Cancelled | The order has been canceled because the user canceled the request before it was processed. This can happen when an order is sent at the time the market is closed | Yes |
Rejected | The order could not be executed and so it got rejected. | Yes |
Event Structure
{
event: "trade_status_update",
payload: {
"dollar_fee": 15.00,
"dw_order_id": "ORD123456789",
"naira_fee": 12000.00,
"price_per_share": 50.75,
"quantity": 100.00,
"side": "buy",
"status": "filled",
"stock_symbol": "AAPL",
"transaction_value": 5075.00,
"type": "market",
"user_currency_fee": 9000.00,
"user_currency_price_per_share": 45.00,
"user_currency_transaction_value": 4500.00
}
}
US Dictionary
This endpoint provides the acceptable data for the brokerage_account_info required during account creation. This info is needed to enable users trade in the US market.
Responses
Response samples
- 200
- 404
{- "assets_range": [
- {
- "12500": "₦0-₦9,000,000"
}, - {
- "62500": "₦9,000,001-₦36,000,001"
}, - {
- "175000": "₦36,000,001-₦90,000,000"
}, - {
- "250000": "₦90,000,001+"
}
], - "dependents": [
- {
- "0": "0",
- "1": "1",
- "2": "2",
- "3": "3",
- "4": "4",
- "5": "5",
- "6": "6",
- "7": "7",
- "8": "8",
- "9": "9"
}
], - "employment_status": [
- {
- "EMPLOYED": "Employed",
- "RETIRED": "Retired",
- "SELF_EMPLOYED": "Self Employed/Business Owner",
- "STUDENT": "Student",
- "UNEMPLOYED": "Not employed"
}
], - "employment_type": [
- {
- "AGRICULTURE": "Agriculture, Forestry, Fishing and Hunting",
- "ART": "Arts, Entertainment, and Recreation",
- "CONSTRUCTION": "Construction",
- "EDUCATION": "Educational Services",
- "FINANCE": "Finance and Insurance",
- "FOOD": "Accommodation and Food Services",
- "HEALTH": "Health Care and Social Assistance",
- "INFORMATION": "Information",
- "MANAGEMENT": "Management of Companies and Enterprises",
- "MANUFACTURING": "Manufacturing",
- "MINING": "Mining, Quarrying, and Oil and Gas Extraction",
- "PROFESSIONAL": "Professional, Scientific, and Technical Services",
- "PUBLIC": "Public Administration",
- "REAL_ESTATE": "Real Estate and Rental and Leasing",
- "RETAIL": "Retail Trade",
- "TRANSPORT": "Transportation and Warehousing",
- "UTILITIES": "Utilities",
- "WASTE": "Administrative and Support and Waste Management and Remediation Services",
- "WHOLESALE": "Wholesale Trade"
}
], - "experience": [
- {
- "NONE": "None"
}, - {
- "YRS_1_2": "1-2 years"
}, - {
- "YRS_3_5": "3-5 years"
}, - {
- "YRS_5_10": "5-10 years"
}, - {
- "YRS_10_": "10+ years"
}
], - "goal": [
- {
- "ACTIVE_DAILY": "Active trader, daily trader",
- "FREQUENT": "Frequent trader, depending on the market",
- "INFREQUENT": "Trading infrequently when I see an opportunity",
- "LONG_TERM": "Long–term buy & hold investing",
- "NEW": "New to investing"
}
], - "martial_status": [
- {
- "DIVORCED": "Divorced",
- "MARRIED": "Married",
- "PARTNER": "Domestic Partner",
- "SINGLE": "Single",
- "WIDOWED": "Widowed"
}
], - "position": [
- {
- "ARTIST": "Artist/Performer/Actor/Dancer",
- "TRANSPORTER": "Transporter",
- "APPRAISER": "Appraiser",
- "PILOT": "Pilot",
- "IMPEX": "Importer/Exporter",
- "BROKER": "Broker",
- "CLERGY": "Clergy",
- "FISHERMAN": "Fisherman",
- "BUSINESS_EXEC": "Business Executive (VP, Director, etc.)",
- "CONSULTANT": "Consultant",
- "ASSISTANT": "Assistant",
- "BARBER": "Barber/Beautician/Hairstylist",
- "SCIENTIST": "Scientist",
- "JANITOR": "Janitor",
- "ANALYST": "Analyst",
- "MECHANIC": "Mechanic",
- "MORTICIAN": "Mortician/Funeral Director",
- "FINANCIAL": "Financial Planner",
- "SECURITY": "Security Guard",
- "AMBASSADOR": "Ambassador/Consulate Professional",
- "LABORER": "Laborer",
- "CIVIL": "Civil Servant",
- "CLERK": "Clerk",
- "JEWELER": "Jeweler",
- "INSPECTOR": "Inspector/Investigator",
- "ENGINEER": "Engineer",
- "NURSE": "Nurse",
- "DOCTOR": "Doctor/Dentist/Veterinarian/Surgeon",
- "CHIROPRACTOR": "Chiropractor",
- "POLICE": "Police Officer/Firefighter/Law Enforcement Professional",
- "DEVELOPER": "Developer",
- "TEACHER": "Teacher/Professor",
- "EXAMINER": "Examiner",
- "TRAINER": "Trainer/Instructor",
- "TELLER": "Teller",
- "PM": "Project Manager",
- "COMPLIANCE": "Compliance/Regulatory Professional",
- "PHYSICAL": "Physical Therapist",
- "CONTRACTOR": "Contractor",
- "INVESTMENT": "Investment Advisor/Investment Manager",
- "AUDITOR": "Auditor",
- "RESEARCHER": "Researcher",
- "TRADESPERSON": "Tradesperson/Craftsperson",
- "SOCIAL": "Social Worker",
- "DEALER": "Dealer",
- "EXTERMINATOR": "Exterminator",
- "OFFICE": "Office Associate",
- "MANAGER": "Manager",
- "LANDSCAPER": "Landscaper",
- "ACTUARY": "Actuary",
- "FLIGHT": "Flight Attendant",
- "FARMER": "Farmer/Rancher",
- "AUCTIONEER": "Auctioneer",
- "ATHLETE": "Athlete",
- "ADMINISTRATOR": "Administrator",
- "HR": "Human Resources Professional",
- "NUTRITIONIST": "Nutritionist",
- "ACCOUNTANT": "Accountant/CPA/Bookkeeper/Controller",
- "DISTRIBUTOR": "Distributor",
- "INTERN": "Intern",
- "LENDING": "Lending Professional",
- "CASHIER": "Cashier",
- "AGENT": "Agent",
- "CAREGIVER": "Caregiver",
- "SEAMSTRESS": "Seamstress/Tailor",
- "WRITER": "Writer/Journalist/Editor",
- "REP": "Registered Rep",
- "MILITARY": "Military, Officer or Associated",
- "COUNSELOR": "Counselor/Therapist",
- "SALES": "Salesperson",
- "DRIVER": "Driver",
- "PHARMACIST": "Pharmacist",
- "BUSINESS_OWNER": "Business Owner",
- "INVESTOR": "Investor",
- "FACTORY": "Factory/Warehouse Worker",
- "TECHNICIAN": "Technician",
- "POLITICIAN": "Politician",
- "ATC": "Air Traffic Controller",
- "ATTENDANT": "Attendant",
- "CARPENTER": "Carpenter/Construction Worker",
- "ADVERTISER": "Advertiser/Marketer/PR Professional",
- "ARCHITECT": "Architect/Designer",
- "CUSTOMER_SERVICE": "Customer Service Representative",
- "IT": "IT Professional/IT Associate",
- "ATTORNEY": "Attorney/Judge/Legal Professional",
- "ADJUSTER": "Adjuster",
- "UNDERWRITER": "Underwriter",
- "CHEF": "Chef/Cook",
- "SAILOR": "Sailor/Seaman"
}
], - "risk_tolerance": [
- {
- "LOW": "Low Risk"
}, - {
- "MODERATE": "Moderate Risk"
}, - {
- "SPECULATION": "Speculative Risk"
}, - {
- "HIGH": "High Risk"
}
], - "source_of_wealth": [
- {
- "COMPANY": "Company sale",
- "GIFT": "Gift",
- "INHERITANCE": "Inheritance",
- "INVESTMENTS": "Sales of shares or other investments/liquidation of an investment portfolio",
- "LOAN": "Loan",
- "PROPERTY": "Sale of property",
- "SAVINGS": "Savings from salary"
}
]
}
The market activity section provides you with endpoints that return the opening and closing times for markets we support, allowing you to check current market activity status. Use this to determine if a market is open or closed.
US Market Activity Status
This endpoint is used to determine if the US market is open or closed.
query Parameters
market required | string Market Type; US or NGX |
header Parameters
content-type required | string Example: application/json Advertises which content type is acceptable. |
accept-language required | string Example: en Advertises which languages the tenant is able to understand. For example, 'en' for English Language. |
x-client-token required | string API consumer token |
x-user-id required | string Required for user authentication |
x-subject-type required | string For user request -> 'tenant'. |
Responses
Response samples
- 200
- 404
{- "date": 1725456600,
- "market_open": false
}
The exchange rate section provides you with an endpoint that fetches real-time exchange rates effortlessly, enabling accurate currency conversions and financial calculations.
Fetch Exchange Rate
This endpoint fetches the current exchange rates for decisioning.
header Parameters
content-type required | string Example: application/json Advertises which content type is acceptable. |
accept-language required | string Example: en Advertises which languages the tenant is able to understand. For example, 'en' for English Language. |
x-client-token required | string API consumer token |
Responses
Response samples
- 200
- 404
{- "exchange_rates": [
- {
- "buy_rate": 805,
- "currency": "NGN",
- "currency_symbol": "₦",
- "flag_image": "string",
- "id": 2,
- "residence_country": "NGA",
- "sell_rate": 868
}
]
}
Stocks are grouped into various categories which help users explore and filter stocks based on common themes, sectors, or other criteria. The endpoints in this section allow you to retrieve a list of categories that group different stocks together and also view details about these categories.
Fetch List of Themes
This is the endpoint to fetch the list of all Themed categories within our system.
header Parameters
content-type required | string Example: application/json Advertises which content type is acceptable. |
accept-language required | string Example: en Advertises which languages the tenant is able to understand. For example, 'en' for English Language. |
x-client-token required | string API Consumer Authorisation Token |
x-request-source required | string The tenant's username |
x-subject-type required | string If standard user -> 'standard’, if manager -> 'manager’. |
Responses
Response samples
- 200
- 401
{- "themes": [
- {
- "name": "Most Popularr",
- "id": 45,
- "hex_color": "D5F59A",
- "description": "The most-owned stocks in the Bamboo community.",
- "color": "Blue",
}
], - "currency_symbol": "$"
}
View Theme Details
This endpoint is used to fetch an existing theme by its unique theme id.
query Parameters
featured | boolean Featured Themes Flag |
header Parameters
content-type required | string Example: application/json Advertises which content type is acceptable. |
accept-language required | string Example: en Advertises which languages the tenant is able to understand. For example, 'en' for English Language. |
x-client-token required | string API Consumer Authorisation Token |
x-request-source required | string The tenant's username |
x-subject-type required | string If standard user -> 'standard’, if manager -> 'manager’. |
Responses
Response samples
- 200
- 401
{- "themes": [
- {
- "name": "Most Popularr",
- "id": 45,
- "hex_color": "D5F59A",
- "description": "The most-owned stocks in the Bamboo community.",
- "color": "Blue",
}
], - "currency_symbol": "$"
}
The documents section provides endpoints for accessing various financial documents related to user accounts. Use these endpoints to retrieve Trade Confirmations, Account Statements, and Tax Documents.
Fetch List of All Documents
This endpoint allows you to retrieve a list of documents including Trade Confirmations, Account Statements, and Tax Documents. You can specify the type of document you wish to access by passing a query parameter of confirms, statements, or taxforms.
- Trade Confirmations: Generated at the end of each trading day for users who have engaged in stock trades on that day.
- Account Statements: Generated at the end of each month.
- Tax Documents: Generated once, at the end of the year.
query Parameters
document_type required | string Used to state the type of document you want to download;
|
header Parameters
content-type required | string Example: application/json Advertises which content type is acceptable. |
accept-language required | string Example: en Advertises which languages the tenant is able to understand. For example, 'en' for English Language. |
x-client-token required | string API consumer token |
x-user-id required | string Required for user authentication |
x-subject-type required | string For user request -> 'tenant'. |
Responses
Response samples
- 200
- 404
{- "documents": [
- {
- "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"
}
]
}
Fetch a Single Document
This endpoint provides you with a URL you can use to download a specific document by passing the file_key as a query parameter.
query Parameters
file_key required | string Example: file_key=2024081901 File key gotten from the document list |
header Parameters
content-type required | string Example: application/json Advertises which content type is acceptable. |
accept-language required | string Example: en Advertises which languages the tenant is able to understand. For example, 'en' for English Language. |
x-client-token required | string API consumer token |
x-user-id required | string Required for user authentication |
x-subject-type required | string For user request -> 'tenant'. |