WhaleBooks | API for third party access

The API is ideal for third-party applications that aim to record their clients' transactions in WhaleBooks while also retrieving their portfolio results.

Comprehensive API documentation can be found at https://whalebooks.com/open-api .

First, you need to obtain an API key. To acquire one, contact support.

Next, authenticate using this API key by including it in the "X-Api-Key" header.

Here is the recommended approach:

1. Create a User

Using: POST /api/v2/users

• If successful, you will receive a response containing the user and their ID.

• If an HTTP 409 error is returned, the user already exists in our system, and you must first obtain their permission to write data to their account. To do this, redirect the user to:

  • https://whalebooks.com/allow-api?user=<USER_EMAIL>&subject-id=<YOUR_ID>.

  • Once the user grants you access, you can resend the POST request and receive a user response that includes the userId.

2. Create Organization

Under an existing or new user, you’ll need to create an organization for which you will have write access.

Use POST /api/v2/organizations and pass userId in request:

Example body:

{
    "userId": 1,
    "orgName": "fromAPI",
    "displayName": "fromAPI",
    "email": "fromAPI@api.com",
    "taxResidency": "CZ",
    "taxSubject": "NATURAL_PERSON"
}

3. Get the Organization vault-id 

Use: GET /api/v2/organizations/{organization-id}/vaults

• You will need vault-id in subsequent API calls.

4. Create portfolio

Under Organization create Portfolio. A Portfolio is required to obtain meaningful computation results.

Use: POST /api/v2/organizations/{organization-id}/vaults/{vault-id}/portfolios

Example body:

{
   "name": "fromAPI1",
   "currency": "USD",
   "computationType": "FIFO",
   "experimentalComputation": true,  
   "feeApplicationType": "AT_PROFIT_REALIZATION",
   "initialState": null
}

5. Create transaction container

Transactions are grouped into transaction containers. 1 (per client) should suffice.

Use: POST /api/v2/organizations/{organization-id}/vaults/{vault-id}/containers

Example body:

{
   "name": "fromAPI1",
   "portfolioId": 1,
   "type": "MANUAL"  # you should always use type manual in this usecase
}