Skip to main content
API docs by Redocly

Wealthica API (Wealthica API 1.0 (20260831-1.5159))

Download OpenAPI specification:Download

Terms of Service

A secure and simple way to access financial data and enable powerful financial apps.

Learn more about Wealthica API

The Wealthica website is using this same API. One way to quickly get going with Wealthica API is looking at the calls made by our dashboard by inspecting the network calls (using Chrome Inspector for example).

API Authentication

Check /auth/token endpoint for how to get an API token.

Read-only access sharing

Users can give read-only access of their data to specific Wealthica users via the Sharings API. Wealthica uses the term sharer for users who share read-only access of their data to other users, and sharee for users who are given read-only access of other users.

For sharees to request data of a sharer, aside from the API Authorization header, sharees will need to pass the sharer's user ID in a request header in the following format: X-Wealthica-Effective-User: [sharer user id]. When the header is present, API requests will be carried out on behalf of the sharer, instead of the user identified by the token.

Currently X-Wealthica-Effective-User header is only supported in GET requests. The header is ignored in other types of request and special endpoints such as /v1/login.

Auth

Create authentication token

Returns an authentication token. The token is to be included in API request header for authentication purpose.

header Parameters
loginName
required
string

The user's unique identification from your system (could be the username, id, or email).

Request Body schema: application/json
required

API client and secret

clientId
required
string

API Client ID

secret
required
string

API Secret

Responses

Request samples

Content type
application/json
{
  • "clientId": "string",
  • "secret": "string"
}

Response samples

Content type
application/json
{
  • "token": "string"
}

Institution

Get user institutions

Returns the list of institutions (optionally at some specific date) belonging to the user that has authorized with the application.

query Parameters
date
string <date>

The date at which to capture the data.

deleted
boolean

Whether or not to return deleted items. true means to return only deleted items. false means to return all except deleted items. Defaults to return both deleted and non-deleted items.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add user institution

Add a new user institution to the authorized user account.

Automated Institutions: Each institution requires a different set of credentials. See the table below for the list of institutions Wealthica currently supports, and the corresponding attributes that are required for the credentials object. Adding an automated institution will toggle an asynchronous first sync task. If the institution returns a login failed on the first sync, the institution will automatically be removed from the user's institutions list.

Manual Institutions: Set manual: true to create a manual institution that doesn't require credentials and won't be synced automatically. Manual institutions allow users to manually manage account balances, positions, and transactions.

Request Body schema: application/json
required

The institution object that needs to be added.

name
string

Name of the institution.

manual
boolean

Set to true to create a manual institution that doesn't require credentials and won't be synced automatically. Manual institutions allow users to manually manage account balances, positions, and transactions. Defaults to false for automated institutions.

logo
string <uri>

Base64 encoded data URI for the institution logo (max 100KB). Only supported for manual institutions. Example: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg=="

Array of objects

Array of investment accounts for manual institutions. Each investment represents an account within the institution. Only supported for manual institutions.

object

Credentials needed for connecting to the financial institutions. The credentials object varies according to institution type. See the Institutions table for a list of credentials type to be used.

sync_documents
boolean

Whether or not to sync documents from this institution. Defaults to true.

sync_transactions
boolean

Whether or not to sync transactions from this institution. Defaults to true.

daily_sync
boolean

Whether or not to sync this institution daily. Defaults to true.

webhook_uri
string or null

Optional HTTPS URL to receive webhook notifications for this institution. Contact us if you wish to enable this feature.

type
required
string

Type of the institution. Get the list of supported types from the /providers endpoint.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "manual": true,
  • "logo": "http://example.com",
  • "investments": [
    ],
  • "credentials": {
    },
  • "sync_documents": true,
  • "sync_transactions": true,
  • "daily_sync": true,
  • "webhook_uri": "string",
  • "type": "string"
}

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "user": "5742b1f7535cf2baba8fff91",
  • "name": "Demo",
  • "type": "string",
  • "manual": true,
  • "logo": "http://example.com",
  • "investments": [
    ],
  • "accounts": [
    ],
  • "overall_gain": 0,
  • "overall_roi": 0,
  • "value": 0,
  • "market_value": 0,
  • "book_value": 0,
  • "cash": 0,
  • "sync_status": "ok",
  • "sync_date": "2019-08-24T14:15:22Z",
  • "sync_request_date": "2019-08-24T14:15:22Z",
  • "sync_error": {
    },
  • "sync_status_details": {
    },
  • "authorized": true,
  • "retry_count": 0,
  • "retry_date": "2019-08-24T14:15:22Z",
  • "creation_date": "2019-08-24T14:15:22Z",
  • "deleted": true,
  • "webhook_uri": "string"
}

Get user institution by ID

Returns an institution that belongs to the authorized user, provided a valid ID.

path Parameters
id
required
string^[a-f0-9]{24}$

ID of the item that needs to be fetched/updated/deleted.

Responses

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "user": "5742b1f7535cf2baba8fff91",
  • "name": "Demo",
  • "type": "string",
  • "manual": true,
  • "logo": "http://example.com",
  • "investments": [
    ],
  • "accounts": [
    ],
  • "overall_gain": 0,
  • "overall_roi": 0,
  • "value": 0,
  • "market_value": 0,
  • "book_value": 0,
  • "cash": 0,
  • "sync_status": "ok",
  • "sync_date": "2019-08-24T14:15:22Z",
  • "sync_request_date": "2019-08-24T14:15:22Z",
  • "sync_error": {
    },
  • "sync_status_details": {
    },
  • "authorized": true,
  • "retry_count": 0,
  • "retry_date": "2019-08-24T14:15:22Z",
  • "creation_date": "2019-08-24T14:15:22Z",
  • "deleted": true,
  • "webhook_uri": "string"
}

Update an existing user institution

Update an existing user institution. If credentials are provided, a synchronization will be triggered.

path Parameters
id
required
string^[a-f0-9]{24}$

ID of the item that needs to be fetched/updated/deleted.

Request Body schema: application/json
required

The institution object for update.

name
string

Name of the institution.

manual
boolean

Set to true to create a manual institution that doesn't require credentials and won't be synced automatically. Manual institutions allow users to manually manage account balances, positions, and transactions. Defaults to false for automated institutions.

logo
string <uri>

Base64 encoded data URI for the institution logo (max 100KB). Only supported for manual institutions. Example: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg=="

Array of objects

Array of investment accounts for manual institutions. Each investment represents an account within the institution. Only supported for manual institutions.

object

Credentials needed for connecting to the financial institutions. The credentials object varies according to institution type. See the Institutions table for a list of credentials type to be used.

sync_documents
boolean

Whether or not to sync documents from this institution. Defaults to true.

sync_transactions
boolean

Whether or not to sync transactions from this institution. Defaults to true.

daily_sync
boolean

Whether or not to sync this institution daily. Defaults to true.

webhook_uri
string or null

Optional HTTPS URL to receive webhook notifications for this institution. Contact us if you wish to enable this feature.

portfolio_manager
string

Name of the portfolio manager from the institution.

deleted
boolean

Whether or not the item is marked as deleted. Deleted items are not taken into account in calculations.

security_answer
string

Answer to the security question prompted by the institution website. If security_answer is provided it will be used to trigger a synchronization for the institution.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "manual": true,
  • "logo": "http://example.com",
  • "investments": [
    ],
  • "credentials": {
    },
  • "sync_documents": true,
  • "sync_transactions": true,
  • "daily_sync": true,
  • "webhook_uri": "string",
  • "portfolio_manager": "string",
  • "deleted": true,
  • "security_answer": "string"
}

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "user": "5742b1f7535cf2baba8fff91",
  • "name": "Demo",
  • "type": "string",
  • "manual": true,
  • "logo": "http://example.com",
  • "investments": [
    ],
  • "accounts": [
    ],
  • "overall_gain": 0,
  • "overall_roi": 0,
  • "value": 0,
  • "market_value": 0,
  • "book_value": 0,
  • "cash": 0,
  • "sync_status": "ok",
  • "sync_date": "2019-08-24T14:15:22Z",
  • "sync_request_date": "2019-08-24T14:15:22Z",
  • "sync_error": {
    },
  • "sync_status_details": {
    },
  • "authorized": true,
  • "retry_count": 0,
  • "retry_date": "2019-08-24T14:15:22Z",
  • "creation_date": "2019-08-24T14:15:22Z",
  • "deleted": true,
  • "webhook_uri": "string"
}

Delete an existing user institution

path Parameters
id
required
string^[a-f0-9]{24}$

ID of the item that needs to be fetched/updated/deleted.

Responses

Poll institution for an update

Blocks (for max 30 seconds) listening for change to an institution, and returns the updated version if any.

path Parameters
id
required
string^[a-f0-9]{24}$

ID of the item that needs to be fetched/updated/deleted.

query Parameters
v
number

Base version number of the institution, which is usually the newest version number that the API client knows.

If provided it will be used to compare with the latest version number on the server to determine if the institution has been updated (its investments are retrieved, positions are updated, or sync is finished).

Defaults to the version number at the start of the poll.

Responses

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "user": "5742b1f7535cf2baba8fff91",
  • "name": "Demo",
  • "type": "string",
  • "manual": true,
  • "logo": "http://example.com",
  • "investments": [
    ],
  • "accounts": [
    ],
  • "overall_gain": 0,
  • "overall_roi": 0,
  • "value": 0,
  • "market_value": 0,
  • "book_value": 0,
  • "cash": 0,
  • "sync_status": "ok",
  • "sync_date": "2019-08-24T14:15:22Z",
  • "sync_request_date": "2019-08-24T14:15:22Z",
  • "sync_error": {
    },
  • "sync_status_details": {
    },
  • "authorized": true,
  • "retry_count": 0,
  • "retry_date": "2019-08-24T14:15:22Z",
  • "creation_date": "2019-08-24T14:15:22Z",
  • "deleted": true,
  • "webhook_uri": "string"
}

Sync institution

Trigger synchronization for the institution. Manual institutions cannot be synced and will return a 400 error.

path Parameters
id
required
string^[a-f0-9]{24}$

ID of the item that needs to be fetched/updated/deleted.

Request Body schema: application/json
interactive
boolean

Run sync task in interactive mode.

force
boolean

Run sync task with ignore-lock argument.

Responses

Request samples

Content type
application/json
{
  • "interactive": true,
  • "force": true
}

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "user": "5742b1f7535cf2baba8fff91",
  • "name": "Demo",
  • "type": "string",
  • "manual": true,
  • "logo": "http://example.com",
  • "investments": [
    ],
  • "accounts": [
    ],
  • "overall_gain": 0,
  • "overall_roi": 0,
  • "value": 0,
  • "market_value": 0,
  • "book_value": 0,
  • "cash": 0,
  • "sync_status": "ok",
  • "sync_date": "2019-08-24T14:15:22Z",
  • "sync_request_date": "2019-08-24T14:15:22Z",
  • "sync_error": {
    },
  • "sync_status_details": {
    },
  • "authorized": true,
  • "retry_count": 0,
  • "retry_date": "2019-08-24T14:15:22Z",
  • "creation_date": "2019-08-24T14:15:22Z",
  • "deleted": true,
  • "webhook_uri": "string"
}

Asset

Get assets

Returns the list of assets (optionally at some specific date) belonging to the user that has authorized with the application.

query Parameters
date
string <date>

The date at which to capture the data.

deleted
boolean

Whether or not to return deleted items. true means to return only deleted items. false means to return all except deleted items. Defaults to return both deleted and non-deleted items.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add asset

Add a new asset to the authorized user account.

Request Body schema: application/json
required

The asset object that needs to be added.

name
required
string

Name of the asset.

category
string

The asset category.

type
required
string
Enum: "primary_residence" "secondary_residence" "income_property" "investment_property" "land" "other_real_estate" "private_equity" "private_fund" "vc_fund" "private_loan" "insurance" "other_investment" "other_asset"

Type of the asset.

currency
required
string
Enum: "aud" "bbd" "brl" "btc" "cad" "chf" "cny" "dkk" "eth" "eur" "gbp" "hkd" "huf" "ils" "inr" "jpy" "krw" "mxn" "nok" "nzd" "ron" "pln" "aed" "sek" "sgd" "thb" "twd" "usd" "vnd" "zar"

The asset currency.

book_value
required
number >= 0

The book value of the asset, in asset currency.

market_value
number >= 0

The market value of the asset, in asset currency.

Responses

Request samples

Content type
application/json
{
  • "name": "Home",
  • "category": "string",
  • "type": "primary_residence",
  • "currency": "aud",
  • "book_value": 0,
  • "market_value": 0
}

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "name": "Home",
  • "class": "equity",
  • "classes": [
    ],
  • "category": "string",
  • "categories": [
    ],
  • "geo": "United States",
  • "geos": [
    ],
  • "industries": [
    ],
  • "sectors": [
    ],
  • "type": "primary_residence",
  • "currency": "aud",
  • "groups": [
    ],
  • "group": "5742b1f7535cf2baba8fff91",
  • "banking": true,
  • "image": "string",
  • "value": 0,
  • "book_value": 0,
  • "market_value": 0,
  • "gain_amount": 0,
  • "gain_currency_amount": 0,
  • "gain_percent": 0,
  • "creation_date": "2019-08-24T14:15:22Z",
  • "deleted": true
}

Get asset by ID

Returns an asset that belongs to the authorized user, provided a valid ID.

path Parameters
id
required
string^[a-f0-9]{24}$

ID of the item that needs to be fetched/updated/deleted.

Responses

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "name": "Home",
  • "class": "equity",
  • "classes": [
    ],
  • "category": "string",
  • "categories": [
    ],
  • "geo": "United States",
  • "geos": [
    ],
  • "industries": [
    ],
  • "sectors": [
    ],
  • "type": "primary_residence",
  • "currency": "aud",
  • "groups": [
    ],
  • "group": "5742b1f7535cf2baba8fff91",
  • "banking": true,
  • "image": "string",
  • "value": 0,
  • "book_value": 0,
  • "market_value": 0,
  • "gain_amount": 0,
  • "gain_currency_amount": 0,
  • "gain_percent": 0,
  • "creation_date": "2019-08-24T14:15:22Z",
  • "deleted": true
}

Update an existing asset

path Parameters
id
required
string^[a-f0-9]{24}$

ID of the item that needs to be fetched/updated/deleted.

Request Body schema: application/json
required

The asset object for update.

name
string

Name of the asset.

class
string
Enum: "equity" "fixed_income" "cash_equivalent" "tangible_asset" "private_equity" "preferred_shares" "crypto" "other"

The asset class.

Array of objects

The asset classes.

category
string

The asset category.

Array of objects

The asset categories.

type
string
Enum: "primary_residence" "secondary_residence" "income_property" "investment_property" "land" "other_real_estate" "private_equity" "private_fund" "vc_fund" "private_loan" "insurance" "other_investment" "other_asset"

Type of the asset.

groups
Array of strings[ items^[a-f0-9]{24}$ ]

List of group IDs or name of the groups the item belongs to. If the list contains a new group name, the group will be automatically created and the ID correctly assigned to the item. Sending a null value will disassociate the item from any groups.

group
string

[Deprecated] ID or name of the group the item belongs to. If this is a new group name, the group will be automatically created and the ID correctly assigned to the item. Sending a null value will remove the association with the current group. Use groups instead.

image
string <data URI> <= 102400 characters

The item's image, in base64-encoded data URI. In an UPDATE request, sending a null value for image will remove the image.

book_value
number >= 0

The book value of the asset, in asset currency.

market_value
number >= 0

The market value of the asset, in asset currency.

deleted
boolean

Whether or not the item is marked as deleted. Deleted items are not taken into account in calculations.

Responses

Request samples

Content type
application/json
{
  • "name": "Home",
  • "class": "equity",
  • "classes": [
    ],
  • "category": "string",
  • "categories": [
    ],
  • "type": "primary_residence",
  • "groups": [
    ],
  • "group": "5742b1f7535cf2baba8fff91",
  • "image": "string",
  • "book_value": 0,
  • "market_value": 0,
  • "deleted": true
}

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "name": "Home",
  • "class": "equity",
  • "classes": [
    ],
  • "category": "string",
  • "categories": [
    ],
  • "geo": "United States",
  • "geos": [
    ],
  • "industries": [
    ],
  • "sectors": [
    ],
  • "type": "primary_residence",
  • "currency": "aud",
  • "groups": [
    ],
  • "group": "5742b1f7535cf2baba8fff91",
  • "banking": true,
  • "image": "string",
  • "value": 0,
  • "book_value": 0,
  • "market_value": 0,
  • "gain_amount": 0,
  • "gain_currency_amount": 0,
  • "gain_percent": 0,
  • "creation_date": "2019-08-24T14:15:22Z",
  • "deleted": true
}

Delete an existing asset

path Parameters
id
required
string^[a-f0-9]{24}$

ID of the item that needs to be fetched/updated/deleted.

Responses

AssetNote

Get asset notes for assets or liabilities

Retrieve a list of asset notes filtered by asset or liability.

query Parameters
asset
string

ID of the asset

liability
string

ID of the liability

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new note for asset or liability

Create a new asset asset note with the provided data.

Request Body schema: application/json
required

New asset note object

user
string

ID of the user who owns the asset note

asset
string

ID of the asset associated with the asset note

liability
string

ID of the liability associated with the asset note

title
required
string

Title of the asset note

date
required
string <date-time>

Date of the asset note

content
required
string

Content of the asset note

tags
Array of strings

Tags associated with the asset note

Responses

Request samples

Content type
application/json
{
  • "user": "string",
  • "asset": "string",
  • "liability": "string",
  • "title": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "content": "string",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "user": "string",
  • "asset": "string",
  • "liability": "string",
  • "title": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "content": "string",
  • "tags": [
    ]
}

Get asset note for asset or liability

Retrieve asset note by its ID.

path Parameters
id
required
string

Asset Note ID

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "user": "string",
  • "asset": "string",
  • "liability": "string",
  • "title": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "content": "string",
  • "tags": [
    ]
}

Update asset note for asset or liability

Update an existing asset note by its ID.

path Parameters
id
required
string

Asset note ID

Request Body schema: application/json
required

Updated asset note object

title
string

Title of the asset note

date
string <date-time>

Date of the asset note

content
string

Content of the asset note

tags
Array of strings

Tags associated with the asset note

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "content": "string",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "user": "string",
  • "asset": "string",
  • "liability": "string",
  • "title": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "content": "string",
  • "tags": [
    ]
}

Delete asset note

Delete asset note by its ID.

path Parameters
id
required
string

Asset note ID

Responses

Get all tags for the user's asset notes

Retrieve a list of all unique tags used in the user's asset notes.

Responses

Response samples

Content type
application/json
[
  • "string"
]

Liability

Get liabilities

Returns the list of liabilities (optionally at some specific date) belonging to the user that has authorized with the application.

query Parameters
date
string <date>

The date at which to capture the data.

deleted
boolean

Whether or not to return deleted items. true means to return only deleted items. false means to return all except deleted items. Defaults to return both deleted and non-deleted items.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add liability

Add a new liability to the authorized user account.

Request Body schema: application/json
required

The liability object that needs to be added.

name
required
string

Name of the liability.

type
required
string
Enum: "mortgage" "other_debt" "private_loan" "line_of_credit"

Type of the liability.

currency
required
string
Enum: "aud" "bbd" "brl" "btc" "cad" "chf" "cny" "dkk" "eth" "eur" "gbp" "hkd" "huf" "ils" "inr" "jpy" "krw" "mxn" "nok" "nzd" "ron" "pln" "aed" "sek" "sgd" "thb" "twd" "usd" "vnd" "zar"

The liability currency.

currency_value
required
number >= 0

The value of the liability, in liability currency.

Responses

Request samples

Content type
application/json
{
  • "name": "Home",
  • "type": "mortgage",
  • "currency": "aud",
  • "currency_value": 0
}

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "name": "Mortgage",
  • "type": "mortgage",
  • "currency": "aud",
  • "groups": [
    ],
  • "group": "5742b1f7535cf2baba8fff91",
  • "banking": true,
  • "image": "string",
  • "value": 0,
  • "currency_value": 0,
  • "creation_date": "2019-08-24T14:15:22Z",
  • "deleted": true
}

Get liability by ID

Returns a liability that belongs to the authorized user, provided a valid ID.

path Parameters
id
required
string^[a-f0-9]{24}$

ID of the item that needs to be fetched/updated/deleted.

Responses

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "name": "Mortgage",
  • "type": "mortgage",
  • "currency": "aud",
  • "groups": [
    ],
  • "group": "5742b1f7535cf2baba8fff91",
  • "banking": true,
  • "image": "string",
  • "value": 0,
  • "currency_value": 0,
  • "creation_date": "2019-08-24T14:15:22Z",
  • "deleted": true
}

Update an existing liability

path Parameters
id
required
string^[a-f0-9]{24}$

ID of the item that needs to be fetched/updated/deleted.

Request Body schema: application/json
required

The liability object for update.

name
string

Name of the liability.

type
string
Enum: "mortgage" "other_debt" "private_loan" "line_of_credit"

Type of the liability.

groups
Array of strings[ items^[a-f0-9]{24}$ ]

List of group IDs or name of the groups the item belongs to. If the list contains a new group name, the group will be automatically created and the ID correctly assigned to the item. Sending a null value will disassociate the item from any groups.

group
string

[Deprecated] ID or name of the group the item belongs to. If this is a new group name, the group will be automatically created and the ID correctly assigned to the item. Sending a null value will remove the association with the current group. Use groups instead.

image
string <data URI> <= 102400 characters

The item's image, in base64-encoded data URI. In an UPDATE request, sending a null value for image will remove the image.

currency_value
number >= 0

The value of the liability, in liability currency.

deleted
boolean

Whether or not the item is marked as deleted. Deleted items are not taken into account in calculations.

Responses

Request samples

Content type
application/json
{
  • "name": "Home",
  • "type": "mortgage",
  • "groups": [
    ],
  • "group": "5742b1f7535cf2baba8fff91",
  • "image": "string",
  • "currency_value": 0,
  • "deleted": true
}

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "name": "Mortgage",
  • "type": "mortgage",
  • "currency": "aud",
  • "groups": [
    ],
  • "group": "5742b1f7535cf2baba8fff91",
  • "banking": true,
  • "image": "string",
  • "value": 0,
  • "currency_value": 0,
  • "creation_date": "2019-08-24T14:15:22Z",
  • "deleted": true
}

Delete an existing liability

path Parameters
id
required
string^[a-f0-9]{24}$

ID of the item that needs to be fetched/updated/deleted.

Responses

Category

Get categories

Returns the list of user asset, position and transaction categories.

Responses

Response samples

Content type
application/json
{
  • "assets": [
    ],
  • "positions": [
    ],
  • "transactions": [
    ]
}

Currency

Get currencies

Returns the list of currencies that Wealthica supports.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get currency history

Returns a currency's exchange rate history against another base currency.

If no base currency is provided, redirects to the same endpoint with the base parameter set to the authenticated user's preferred currency. For unauthenticated user, base will be set to 'cad'.

path Parameters
id
required
string^[a-f0-9]{24}$

ID of the item that needs to be fetched/updated/deleted.

query Parameters
from
string <date>

The start date of the period to perform the query. This cannot be a date after to date. Defaults to start of the current year.

to
string <date>

The end date of the period to perform the query. This cannot be a date before from date. Defaults to today.

base
string
Enum: "aud" "bbd" "brl" "btc" "cad" "chf" "cny" "dkk" "eth" "eur" "gbp" "hkd" "huf" "ils" "inr" "jpy" "krw" "mxn" "nok" "nzd" "ron" "pln" "aed" "sek" "sgd" "thb" "twd" "usd" "vnd" "zar"

Base currency id to retrieve exchange rate history against.

Responses

Response samples

Content type
application/json
{
  • "from": "2019-08-24T14:15:22Z",
  • "to": "2019-08-24T14:15:22Z",
  • "high": {
    },
  • "low": {
    },
  • "first": {
    },
  • "last": {
    },
  • "difference": 0,
  • "change": 0,
  • "data": [
    ]
}

Document

Get documents

Returns the list of documents belonging to the user that has authorized with the application.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add document

Add a new document to the authorized user account.

Request Body schema: application/json
required

The document object that needs to be added.

name
required
string

Name of the document.

type
required
string
Enum: "statement" "trade_confirmation" "tax_receipt" "fund_facts" "investment_policy" "other"

The document type.

institution
string^[a-f0-9]{24}$

ID of the institution the document belongs to. Mutually exclusive with asset.

investments
Array of strings

The investment accounts the document belongs to. Could be account numbers in plain strings (e.g. ABCDEFGH01) or Wealthica investment id format (e.g. demo:cash:usd). Mutually exclusive with asset.

asset
string^[a-f0-9]{24}$

ID of the asset the document belongs to. Mutually exclusive with institution & investments.

date
required
string <date-time>

The date the document is issued.

note
string

Some notes for the item set by the user.

data
required
string <data URI> <= 20971520 characters

The document file, in base64-encoded data URI.

Responses

Request samples

Content type
application/json
{
  • "name": "Tax Receipts Q1-2021",
  • "type": "statement",
  • "institution": "5742b1f7535cf2baba8fff91",
  • "investments": [
    ],
  • "asset": "5742b1f7535cf2baba8fff91",
  • "date": "2019-08-24T14:15:22Z",
  • "note": "string",
  • "data": "string"
}

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "name": "Tax Receipts Q1-2021",
  • "type": "statement",
  • "size": 0,
  • "mime": "application/pdf",
  • "preview": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "user": "5742b1f7535cf2baba8fff91",
  • "institution": "5742b1f7535cf2baba8fff91",
  • "investments": [
    ],
  • "asset": "5742b1f7535cf2baba8fff91",
  • "new": true,
  • "url": "string",
  • "note": "string"
}

Get document by ID

Returns a document that belongs to the authorized user, provided a valid ID. The returned data also includes the document's download URL.

path Parameters
id
required
string^[a-f0-9]{24}$

ID of the item that needs to be fetched/updated/deleted.

Responses

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "name": "Tax Receipts Q1-2021",
  • "type": "statement",
  • "size": 0,
  • "mime": "application/pdf",
  • "preview": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "user": "5742b1f7535cf2baba8fff91",
  • "institution": "5742b1f7535cf2baba8fff91",
  • "investments": [
    ],
  • "asset": "5742b1f7535cf2baba8fff91",
  • "new": true,
  • "url": "string",
  • "note": "string"
}

Update an existing document

path Parameters
id
required
string^[a-f0-9]{24}$

ID of the item that needs to be fetched/updated/deleted.

Request Body schema: application/json
required

The document object for update.

name
string

Name of the document.

type
string
Enum: "statement" "trade_confirmation" "tax_receipt" "fund_facts" "investment_policy" "other"

The document type.

institution
string^[a-f0-9]{24}$

ID of the institution the document belongs to. Mutually exclusive with asset.

investments
Array of strings

The investment accounts the document belongs to. Could be account numbers in plain strings (e.g. ABCDEFGH01) or Wealthica investment id format (e.g. demo:cash:usd). Mutually exclusive with asset.

asset
string^[a-f0-9]{24}$

ID of the asset the document belongs to. Mutually exclusive with institution & investments.

date
string <date-time>

The date the document is issued.

note
string

Some notes for the item set by the user.

data
string <data URI> <= 20971520 characters

The document file, in base64-encoded data URI.

Responses

Request samples

Content type
application/json
{
  • "name": "Tax Receipts Q1-2021",
  • "type": "statement",
  • "institution": "5742b1f7535cf2baba8fff91",
  • "investments": [
    ],
  • "asset": "5742b1f7535cf2baba8fff91",
  • "date": "2019-08-24T14:15:22Z",
  • "note": "string",
  • "data": "string"
}

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "name": "Tax Receipts Q1-2021",
  • "type": "statement",
  • "size": 0,
  • "mime": "application/pdf",
  • "preview": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "user": "5742b1f7535cf2baba8fff91",
  • "institution": "5742b1f7535cf2baba8fff91",
  • "investments": [
    ],
  • "asset": "5742b1f7535cf2baba8fff91",
  • "new": true,
  • "url": "string",
  • "note": "string"
}

Delete an existing document

path Parameters
id
required
string^[a-f0-9]{24}$

ID of the item that needs to be fetched/updated/deleted.

Responses

Enums

Get transaction types

Returns the list of transaction types that Wealthica supports. This list is subject to change as we might add more transaction types.

Responses

Response samples

Content type
application/json
[
  • "string"
]

Get investment types

Returns the list of investment (account) types that Wealthica supports. This list is subject to change as we might add more investment types.

Responses

Response samples

Content type
application/json
[
  • "string"
]

Get sectors and industries

Returns the canonical list of sectors and industries with English and French names. Used for security sector/industry classification (e.g. in the holdings addon). Structure is nested: each sector has an array of industries; each item has name: { en, fr }.

Responses

Response samples

Content type
application/json
{
  • "sectors": [
    ]
}

History

Get history entries

Returns the daily history entries for investments, assets and liabilities in a specific period of time for the authenticated user.

query Parameters
from
string <date>

The start date of the period to perform the query. This cannot be a date after to date. Defaults to start of the current year.

to
string <date>

The end date of the period to perform the query. This cannot be a date before from date. Defaults to today.

groups
Array of strings[ items^[a-f0-9]{24}$ ]

A list of IDs for the groups to be used to filter the query. If provided, groups that aren't specified will not be included in the snapshot. The ID that represents 'no group' is '000000000000000000000000' (24 zeros). If this ID is provided, the API will return resources that belong to no group.

institutions
Array of strings[ items^[a-f0-9]{24}$ ]

A list of IDs for the institutions to be used to filter the query. If provided, institutions that aren't specified will not be included in the snapshot. Defaults to include all if both assets and liabilities are not provided. Defaults to exclude all if either assets or liabilities is provided.

investments
Array of strings

A list of IDs for the investment accounts to be used to filter the query. If provided, investment accounts that aren't specified will not be included in the snapshot.

assets
boolean

Whether or not to include assets in the response. Defaults to include assets if both institutions and liabilities are not provided. Defaults to exclude assets if either institutions or liabilities is provided.

liabilities
boolean

Whether or not to include liabilities in the response. Defaults to include liabilities if both institutions and assets are not provided. Defaults to exclude liabilities if either institutions or assets is provided.

banking
boolean

Whether or not to return only banking items in the response. true means to return only banking items. false (default) means to return all items.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add history entry

Add a new history entry to the authenticated user account.

Request Body schema: application/json
required

The history entry object that needs to be added.

user
required
string^[a-f0-9]{24}$

ID of the item's owner user.

date
required
string <date-time>

The date the history entry is recorded.

currency_value
required
number

The value of the investment, asset or liability at the recorded date, in its currency.

Responses

Request samples

Content type
application/json
{
  • "user": "5742b1f7535cf2baba8fff91",
  • "date": "2019-08-24T14:15:22Z",
  • "currency_value": 0
}

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "user": "5742b1f7535cf2baba8fff91",
  • "date": "2019-08-24T14:15:22Z",
  • "currency_value": 0,
  • "value": 0
}

Get history entry by ID

Returns a history entry that belongs to the authorized user, provided a valid ID.

path Parameters
id
required
string^[a-f0-9]{24}$

ID of the item that needs to be fetched/updated/deleted.

Responses

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "user": "5742b1f7535cf2baba8fff91",
  • "date": "2019-08-24T14:15:22Z",
  • "currency_value": 0,
  • "value": 0
}

Update an existing history entry value

path Parameters
id
required
string^[a-f0-9]{24}$

ID of the item that needs to be fetched/updated/deleted.

Request Body schema: application/json
required

The history entry object for update.

currency_value
required
number

The value of the investment, asset or liability at the recorded date, in its currency.

Responses

Request samples

Content type
application/json
{
  • "currency_value": 0
}

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "user": "5742b1f7535cf2baba8fff91",
  • "date": "2019-08-24T14:15:22Z",
  • "currency_value": 0,
  • "value": 0
}

Delete an existing history entry

path Parameters
id
required
string^[a-f0-9]{24}$

ID of the item that needs to be fetched/updated/deleted.

Responses

Portfolio

(Experimental) Get user portfolio Deprecated

Returns the portfolio snapshot of the authenticated user for a specific time period.

This is an experimental API that is still being developed and should not be used in production.

query Parameters
from
string <date>

The start date of the period to perform the query. This cannot be a date after to date. Defaults to start of the current year.

to
string <date>

The end date of the period to perform the query. This cannot be a date before from date. Defaults to today.

groups
Array of strings[ items^[a-f0-9]{24}$ ]

A list of IDs for the groups to be used to filter the query. If provided, groups that aren't specified will not be included in the snapshot. The ID that represents 'no group' is '000000000000000000000000' (24 zeros). If this ID is provided, the API will return resources that belong to no group.

institutions
Array of strings[ items^[a-f0-9]{24}$ ]

A list of IDs for the institutions to be used to filter the query. If provided, institutions that aren't specified will not be included in the snapshot. Defaults to include all if both assets and liabilities are not provided. Defaults to exclude all if either assets or liabilities is provided.

assets
boolean

Whether or not to include assets in the response. Defaults to include assets if both institutions and liabilities are not provided. Defaults to exclude assets if either institutions or liabilities is provided.

liabilities
boolean

Whether or not to include liabilities in the response. Defaults to include liabilities if both institutions and assets are not provided. Defaults to exclude liabilities if either institutions or assets is provided.

banking
boolean

Whether or not to return only banking items in the response. true means to return only banking items. false (default) means to return all items.

Responses

Response samples

Content type
application/json
{
  • "history": {
    },
  • "transactions": {
    }
}

Position

Get positions

Returns an aggregated list of currently owned positions for the authenticated user.

query Parameters
groups
Array of strings[ items^[a-f0-9]{24}$ ]

A list of IDs for the groups to be used to filter the query. If provided, groups that aren't specified will not be included in the snapshot. The ID that represents 'no group' is '000000000000000000000000' (24 zeros). If this ID is provided, the API will return resources that belong to no group.

institutions
Array of strings[ items^[a-f0-9]{24}$ ]

A list of IDs for the institutions to be used to filter the query. If provided, institutions that aren't specified will not be included in the snapshot. Defaults to include all if both assets and liabilities are not provided. Defaults to exclude all if either assets or liabilities is provided.

investments
Array of strings

A list of IDs for the investment accounts to be used to filter the query. If provided, investment accounts that aren't specified will not be included in the snapshot.

assets
boolean

Whether or not to include assets in the response. Defaults to include assets if both institutions and liabilities are not provided. Defaults to exclude assets if either institutions or liabilities is provided.

liabilities
boolean

Whether or not to include liabilities in the response. Defaults to include liabilities if both institutions and assets are not provided. Defaults to exclude liabilities if either institutions or assets is provided.

banking
boolean

Whether or not to return only banking items in the response. true means to return only banking items. false (default) means to return all items.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new position

Create a new position for a completely new security. This endpoint is typically used for manual positions where users want to track holdings of a security that doesn't exist in their automated institutions.

The position will be created with the specified investments, and each investment will be flagged as manual or automated based on the type of institution it belongs to.

Request Body schema: application/json
required

The position object to create

security
required
string

The ID of the security for this position

required
Array of objects

Array of investments that make up this position

class
string

Asset class for the position. If provided, takes precedence over classes field.

Array of objects

Array of asset classes with weights. Ignored if class field is provided.

category
string

Category for the position. If provided, takes precedence over categories field.

Array of objects

Array of categories with weights. Ignored if category field is provided.

geo
string

Geographic allocation for the position. If provided, takes precedence over geos field.

Array of objects

Array of geographic allocations with weights. Ignored if geo field is provided.

Responses

Request samples

Content type
application/json
{
  • "security": "507f1f77bcf86cd799439011",
  • "investments": [
    ],
  • "class": "equity",
  • "classes": [
    ],
  • "category": "Technology",
  • "categories": [
    ],
  • "geo": "North America",
  • "geos": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "class": "equity",
  • "classes": [
    ],
  • "category": "string",
  • "categories": [
    ],
  • "geo": "United States",
  • "geos": [
    ],
  • "industries": [
    ],
  • "sectors": [
    ],
  • "security": {
    },
  • "investments": [
    ],
  • "quantity": 0,
  • "book_value": 0,
  • "market_value": 0,
  • "gain_amount": 0,
  • "gain_percent": 0,
  • "option_details": {
    }
}

Update an existing position

Update an existing position. This endpoint supports updating position metadata (class, category, geo) and managing manual investments through the manual_investments parameter.

When manual_investments is provided, it represents the desired state of all manual investments for this position. The system will:

  • Remove any existing manual investments not present in the array
  • Add new manual investments from the array
  • Update existing manual investments with new values
  • Leave automated investments unchanged

If the position has no investments left after the update, it will be automatically deleted.

path Parameters
id
required
string^[a-f0-9]{24}$

ID of the item that needs to be fetched/updated/deleted.

Request Body schema: application/json
required

The position object for update.

class
string
Enum: "equity" "fixed_income" "cash_equivalent" "tangible_asset" "private_equity" "preferred_shares" "crypto" "other"

The position class. If provided, takes precedence over classes field.

Array of objects

Array of position classes with weights. Ignored if class field is provided.

category
string

The position category. If provided, takes precedence over categories field.

categories
string

The position category. If provided, takes precedence over categories field.

Array of objects

Array representing the desired state of manual investments for this position. Only manual institutions are allowed. Automated investments are not affected.

Responses

Request samples

Content type
application/json
{
  • "class": "equity",
  • "classes": [
    ],
  • "category": "string",
  • "categories": "string",
  • "manual_investments": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "class": "equity",
  • "classes": [
    ],
  • "category": "string",
  • "categories": [
    ],
  • "geo": "United States",
  • "geos": [
    ],
  • "industries": [
    ],
  • "sectors": [
    ],
  • "security": {
    },
  • "investments": [
    ],
  • "quantity": 0,
  • "book_value": 0,
  • "market_value": 0,
  • "gain_amount": 0,
  • "gain_percent": 0,
  • "option_details": {
    }
}

Performance

Get user performance Deprecated

[Work in progress] Returns the performance snapshot of the authenticated user for a specific time period. This API is not finalized and is expected to change in the future.

query Parameters
from
string <date>

The start date of the period to perform the query. This cannot be a date after to date. Defaults to start of the current year.

to
string <date>

The end date of the period to perform the query. This cannot be a date before from date. Defaults to today.

groups
Array of strings[ items^[a-f0-9]{24}$ ]

A list of IDs for the groups to be used to filter the query. If provided, groups that aren't specified will not be included in the snapshot. The ID that represents 'no group' is '000000000000000000000000' (24 zeros). If this ID is provided, the API will return resources that belong to no group.

institutions
Array of strings[ items^[a-f0-9]{24}$ ]

A list of IDs for the institutions to be used to filter the query. If provided, institutions that aren't specified will not be included in the snapshot. Defaults to include all if both assets and liabilities are not provided. Defaults to exclude all if either assets or liabilities is provided.

assets
boolean

Whether or not to include assets in the response. Defaults to include assets if both institutions and liabilities are not provided. Defaults to exclude assets if either institutions or liabilities is provided.

liabilities
boolean

Whether or not to include liabilities in the response. Defaults to include liabilities if both institutions and assets are not provided. Defaults to exclude liabilities if either institutions or assets is provided.

banking
boolean

Whether or not to return only banking items in the response. true means to return only banking items. false (default) means to return all items.

Responses

Response samples

Content type
application/json
{
  • "history": {
    },
  • "institutions": [
    ],
  • "investments": [
    ],
  • "assets": [
    ],
  • "positions": [
    ]
}

Sharing

Get sharings

Returns the list of sharings.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add sharing

Add a new sharing object. Only sharer can do this.

Request Body schema: application/json
required

The sharing object to be added. Only sharee ID is required/accepted

sharee
string^[a-f0-9]{24}$

The sharee user ID

Responses

Request samples

Content type
application/json
{
  • "sharee": "5742b1f7535cf2baba8fff91"
}

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "sharer": {
    },
  • "sharee": {
    }
}

Delete an existing sharing

path Parameters
id
required
string^[a-f0-9]{24}$

ID of the item that needs to be fetched/updated/deleted.

Responses

Provider

Get providers

Returns list all supported providers (endpoint is not finalized and will be updated soon).

query Parameters
unpublished
boolean

not passed - all providers are displayed; true - only unpublished providers are displayed; false - unpublished providers are hidden.

group
string
Enum: "core" "vezgo" "yodlee"

Allows to filter by providers class.

class
string
Enum: "api" "oauth" "scraper"

Allows to filter by providers class.

format
string
Enum: "array" "object"

Select which format to return. NOTE due to legacy reasons, this defaults to "object" when no parameter is provided (GET /providers). However the default is planned to be changed to "array". New API clients are advised to always explicitly pass format=array.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Transaction

Get transactions

Returns the list of transactions in a specific period of time that belongs to the user that has authorized with the application.

query Parameters
from
string <date>

The start date of the period to perform the query. This cannot be a date after to date. Defaults to start of the current year.

to
string <date>

The end date of the period to perform the query. This cannot be a date before from date. Defaults to today.

groups
Array of strings[ items^[a-f0-9]{24}$ ]

A list of IDs for the groups to be used to filter the query. If provided, groups that aren't specified will not be included in the snapshot. The ID that represents 'no group' is '000000000000000000000000' (24 zeros). If this ID is provided, the API will return resources that belong to no group.

institutions
Array of strings[ items^[a-f0-9]{24}$ ]

A list of IDs for the institutions to be used to filter the query. If provided, institutions that aren't specified will not be included in the snapshot. Defaults to include all if both assets and liabilities are not provided. Defaults to exclude all if either assets or liabilities is provided.

investments
Array of strings

A list of IDs for the investment accounts to be used to filter the query. If provided, investment accounts that aren't specified will not be included in the snapshot.

assets
boolean

Whether or not to include assets in the response. Defaults to include assets if both institutions and liabilities are not provided. Defaults to exclude assets if either institutions or liabilities is provided.

liabilities
boolean

Whether or not to include liabilities in the response. Defaults to include liabilities if both institutions and assets are not provided. Defaults to exclude liabilities if either institutions or assets is provided.

banking
boolean

Whether or not to return only banking items in the response. true means to return only banking items. false (default) means to return all items.

types
Array of strings
Items Enum: "deposit" "withdrawal" "transfer" "transfer_in" "transfer_out" "switch" "interest" "dividend" "distribution" "roc" "reinvest" "drip" "tax" "fee" "sell" "buy" "income" "split" "mtm" "loan" "recall" "name_change" "spinoff" "merger" "unknown"

A list of transaction types to be used to filter the query. If provided, transactions that aren't specified will not be included in the response. This list may be modified in the future as we consider the inclusion of more transaction types.

deleted
boolean

Whether or not to return deleted items. true means to return only deleted items. false means to return all except deleted items. Defaults to return both deleted and non-deleted items.

invalid
boolean

Whether or not to return invalid/unknown/incomplete items. true means to return only invalid/unknown/incomplete items. false means to return all except invalid/unknown/incomplete items. Defaults to return both invalid/unknown/incomplete and valid items.

new
boolean

Whether or not to return new items. true means to return only new items. false means to return all except new items. Defaults to return both new and non-new items.

peek
boolean

Whether or not to reset the new flag for items. true means to leave new flags untouched. false means to clear the new flag (mark as viewed) for returned items. Defaults to false.

missing
boolean

Whether or not to include missing items. true means to incluse missing items. false means to exclude missing items. Defaults to false.

last
string^[a-f0-9]{24}$

The ID for a last-known transaction. When this is passed in, only transactions newer than (added to Wealthica after) this one will be returned. If an empty value is passed in, the first transactions ever added to Wealthica will be returned.

Will trigger pagination mode, which returns transactions ordered ascendingly by the date on which they're added to Wealthica, instead of by the trade date.

limit
integer [ 1 .. 1000 ]

The number of transactions to return.

Will trigger pagination mode. In pagination mode, by default a maximum of 100 transactions are returned if limit is not provided.

sort
string
Enum: "asc" "desc"

Sort transactions direction. ASC is default direction. Sorted by "date" by default and by "_id" in pagination mode if "limit" or "last" param passed.

security
boolean

If true, return transactions that have either security or symbol set. Transactions with symbol but no security are also returned since they are deemed to have a security assigned even though the security is unknown.

If false, return transactions that have neither security or symbol set.

skip_date_filter
boolean

If true, skip date filter params "from" and "to" if it's set, otherwise, do not use default date filtering. Besides pagination mode forcibly enabled.

skip_reset_new_transactions
boolean

If true, do not reset "new" flag for transactions.

sort_field
string
Value: "date"

Allows to sort by date in pagination mode.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add transaction

Add a new transaction to the authorized user account.

Request Body schema: application/json
required

The transaction object that needs to be added.

type
required
string
Enum: "deposit" "withdrawal" "transfer" "transfer_in" "transfer_out" "switch" "interest" "dividend" "distribution" "roc" "reinvest" "drip" "tax" "fee" "sell" "buy" "income" "split" "mtm" "loan" "recall" "name_change" "spinoff" "merger" "unknown"

The transaction type.

category
string <= 30 characters
security
string^[a-f0-9]{24}$

ID of the security involved in the transaction. Either security or symbol must be provided for transaction of types dividend, distribution, roc, reinvest, sell, buy, transfer_in and transfer_out.

symbol
string^[A-Z0-9.]+$

The ticker symbol for the security involved in the transaction (if any). Either security or symbol must be provided for transactions of types dividend, distribution, roc, reinvest, sell, buy, transfer_in and transfer_out.

quantity
number

The quantity of security involved in the transaction (if any).

currency_amount
required
number

The transaction amount, in transaction currency.

Array of objects

Transaction amount in different currencies.

description
string <= 350 characters

The transaction description.

note
string <= 400 characters

The transaction note.

fee
number

The transaction fee, in transaction currency.

realized_gain
number

[Deprecated] The realized gain amount for the sell transaction, in user preferred currency.

institution
string^[a-f0-9]{24}$

ID of the institution the transaction belongs to. This is not required if asset is available.

investment
string

ID of the investment account the transaction belongs to. This is not required if asset is available.

asset
string^[a-f0-9]{24}$

ID of the asset the transaction belongs to. This is not required if institution and investment are available.

date
required
string <date-time>

The date the transaction occured (trade date).

settlement_date
string <date-time>

The settlement date of the transaction.

Responses

Request samples

Content type
application/json
{
  • "type": "deposit",
  • "category": "string",
  • "security": "5742b1f7535cf2baba8fff91",
  • "symbol": "string",
  • "quantity": 0,
  • "currency_amount": 0,
  • "amounts": [
    ],
  • "description": "string",
  • "note": "string",
  • "fee": 0,
  • "realized_gain": 0,
  • "institution": "5742b1f7535cf2baba8fff91",
  • "investment": "demo:cash:usd",
  • "asset": "5742b1f7535cf2baba8fff91",
  • "date": "2019-08-24T14:15:22Z",
  • "settlement_date": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "user": "5742b1f7535cf2baba8fff91",
  • "institution": "5742b1f7535cf2baba8fff91",
  • "investment": "demo:cash:usd",
  • "asset": "5742b1f7535cf2baba8fff91",
  • "currency": "aud",
  • "date": "2019-08-24T14:15:22Z",
  • "processing_date": "2019-08-24T14:15:22Z",
  • "settlement_date": "2019-08-24T14:15:22Z",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "type": "deposit",
  • "origin_type": "string",
  • "origin_id": "string",
  • "category": "string",
  • "origin_category": "string",
  • "security": {
    },
  • "symbol": "string",
  • "description": "string",
  • "note": "string",
  • "currency_amount": 0,
  • "amount": 0,
  • "amounts": [
    ],
  • "fee": 0,
  • "quantity": 0,
  • "realized_gain": 0,
  • "user_created": true,
  • "deleted": true,
  • "incomplete": [
    ],
  • "missing": true,
  • "new": true,
  • "history": [
    ],
  • "other_parties": [
    ]
}

Get paginated transactions

Returns paginated transactions with metadata for efficient loading. This endpoint is optimized for frontend pagination and provides cursor-based pagination with metadata about total counts and pagination state.

Use limit to control page size (1-1000, default: 200), last cursor from previous response for next page, and check has_more to determine if more pages exist. Note that total_count may be null for very large datasets.

query Parameters
from
string <date>

The start date of the period to perform the query. This cannot be a date after to date. Defaults to start of the current year.

to
string <date>

The end date of the period to perform the query. This cannot be a date before from date. Defaults to today.

groups
Array of strings[ items^[a-f0-9]{24}$ ]

A list of IDs for the groups to be used to filter the query. If provided, groups that aren't specified will not be included in the snapshot. The ID that represents 'no group' is '000000000000000000000000' (24 zeros). If this ID is provided, the API will return resources that belong to no group.

institutions
Array of strings[ items^[a-f0-9]{24}$ ]

A list of IDs for the institutions to be used to filter the query. If provided, institutions that aren't specified will not be included in the snapshot. Defaults to include all if both assets and liabilities are not provided. Defaults to exclude all if either assets or liabilities is provided.

investments
Array of strings

A list of IDs for the investment accounts to be used to filter the query. If provided, investment accounts that aren't specified will not be included in the snapshot.

assets
boolean

Whether or not to include assets in the response. Defaults to include assets if both institutions and liabilities are not provided. Defaults to exclude assets if either institutions or liabilities is provided.

liabilities
boolean

Whether or not to include liabilities in the response. Defaults to include liabilities if both institutions and assets are not provided. Defaults to exclude liabilities if either institutions or assets is provided.

banking
boolean

Whether or not to return only banking items in the response. true means to return only banking items. false (default) means to return all items.

types
Array of strings
Items Enum: "deposit" "withdrawal" "transfer" "transfer_in" "transfer_out" "switch" "interest" "dividend" "distribution" "roc" "reinvest" "drip" "tax" "fee" "sell" "buy" "income" "split" "mtm" "loan" "recall" "name_change" "spinoff" "merger" "unknown"

A list of transaction types to be used to filter the query. If provided, transactions that aren't specified will not be included in the response. This list may be modified in the future as we consider the inclusion of more transaction types.

deleted
boolean

Whether or not to return deleted items. true means to return only deleted items. false means to return all except deleted items. Defaults to return both deleted and non-deleted items.

invalid
boolean

Whether or not to return invalid/unknown/incomplete items. true means to return only invalid/unknown/incomplete items. false means to return all except invalid/unknown/incomplete items. Defaults to return both invalid/unknown/incomplete and valid items.

new
boolean

Whether or not to return new items. true means to return only new items. false means to return all except new items. Defaults to return both new and non-new items.

peek
boolean

Whether or not to reset the new flag for items. true means to leave new flags untouched. false means to clear the new flag (mark as viewed) for returned items. Defaults to false.

missing
boolean

Whether or not to include missing items. true means to incluse missing items. false means to exclude missing items. Defaults to false.

last
string^[a-f0-9]{24}$

Cursor for pagination. The ID of the last transaction from the previous page. When provided, returns transactions after this cursor.

limit
integer [ 1 .. 1000 ]
Default: 200

Number of transactions to return per page. Defaults to 200, maximum 1000.

sort
string
Default: "desc"
Enum: "asc" "desc"

Sort direction for transactions. Defaults to desc (newest first).

sort_field
string
Value: "date"

Field to sort by. Currently only supports 'date'.

skip_date_filter
boolean

If true, skip default date filtering and return transactions for all time. By default, transactions are filtered to the current year only.

skip_reset_new_transactions
boolean

If true, do not reset the "new" flag on transactions. Useful for read-only operations or when sharing data.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get transaction aggregations

Returns pre-calculated aggregations for transactions including filter counts, type breakdowns with USD/CAD/consolidated totals, and grand totals. This endpoint is optimized for dashboard summaries and filter UI.

query Parameters
from
string <date>

The start date of the period to perform the query. This cannot be a date after to date. Defaults to start of the current year.

to
string <date>

The end date of the period to perform the query. This cannot be a date before from date. Defaults to today.

groups
Array of strings[ items^[a-f0-9]{24}$ ]

A list of IDs for the groups to be used to filter the query. If provided, groups that aren't specified will not be included in the snapshot. The ID that represents 'no group' is '000000000000000000000000' (24 zeros). If this ID is provided, the API will return resources that belong to no group.

institutions
Array of strings[ items^[a-f0-9]{24}$ ]

A list of IDs for the institutions to be used to filter the query. If provided, institutions that aren't specified will not be included in the snapshot. Defaults to include all if both assets and liabilities are not provided. Defaults to exclude all if either assets or liabilities is provided.

investments
Array of strings

A list of IDs for the investment accounts to be used to filter the query. If provided, investment accounts that aren't specified will not be included in the snapshot.

assets
boolean

Whether or not to include assets in the response. Defaults to include assets if both institutions and liabilities are not provided. Defaults to exclude assets if either institutions or liabilities is provided.

liabilities
boolean

Whether or not to include liabilities in the response. Defaults to include liabilities if both institutions and assets are not provided. Defaults to exclude liabilities if either institutions or assets is provided.

banking
boolean

Whether or not to return only banking items in the response. true means to return only banking items. false (default) means to return all items.

types
Array of strings
Items Enum: "deposit" "withdrawal" "transfer" "transfer_in" "transfer_out" "switch" "interest" "dividend" "distribution" "roc" "reinvest" "drip" "tax" "fee" "sell" "buy" "income" "split" "mtm" "loan" "recall" "name_change" "spinoff" "merger" "unknown"

A list of transaction types to be used to filter the query. If provided, transactions that aren't specified will not be included in the response. This list may be modified in the future as we consider the inclusion of more transaction types.

deleted
boolean

Whether or not to return deleted items. true means to return only deleted items. false means to return all except deleted items. Defaults to return both deleted and non-deleted items.

invalid
boolean

Whether or not to return invalid/unknown/incomplete items. true means to return only invalid/unknown/incomplete items. false means to return all except invalid/unknown/incomplete items. Defaults to return both invalid/unknown/incomplete and valid items.

new
boolean

Whether or not to return new items. true means to return only new items. false means to return all except new items. Defaults to return both new and non-new items.

missing
boolean

Whether or not to include missing items. true means to incluse missing items. false means to exclude missing items. Defaults to false.

include_totals
boolean
Default: true

Whether to include type breakdown and grand totals in the response. Set to false to only get filter counts for better performance.

skip_date_filter
boolean

If true, skip default date filtering and return aggregations for all time. By default, aggregations are calculated for the current year only.

Responses

Response samples

Content type
application/json
{
  • "filter_counts": {
    },
  • "type_breakdown": [
    ],
  • "grand_totals": {
    }
}

Get transaction by ID

Returns a transaction that belongs to the authorized user, provided a valid ID.

path Parameters
id
required
string^[a-f0-9]{24}$

ID of the item that needs to be fetched/updated/deleted.

Responses

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "user": "5742b1f7535cf2baba8fff91",
  • "institution": "5742b1f7535cf2baba8fff91",
  • "investment": "demo:cash:usd",
  • "asset": "5742b1f7535cf2baba8fff91",
  • "currency": "aud",
  • "date": "2019-08-24T14:15:22Z",
  • "processing_date": "2019-08-24T14:15:22Z",
  • "settlement_date": "2019-08-24T14:15:22Z",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "type": "deposit",
  • "origin_type": "string",
  • "origin_id": "string",
  • "category": "string",
  • "origin_category": "string",
  • "security": {
    },
  • "symbol": "string",
  • "description": "string",
  • "note": "string",
  • "currency_amount": 0,
  • "amount": 0,
  • "amounts": [
    ],
  • "fee": 0,
  • "quantity": 0,
  • "realized_gain": 0,
  • "user_created": true,
  • "deleted": true,
  • "incomplete": [
    ],
  • "missing": true,
  • "new": true,
  • "history": [
    ],
  • "other_parties": [
    ]
}

Update an existing transaction

path Parameters
id
required
string^[a-f0-9]{24}$

ID of the item that needs to be fetched/updated/deleted.

Request Body schema: application/json
required

The transaction object for update.

type
required
string
Enum: "deposit" "withdrawal" "transfer" "transfer_in" "transfer_out" "switch" "interest" "dividend" "distribution" "roc" "reinvest" "drip" "tax" "fee" "sell" "buy" "income" "split" "mtm" "loan" "recall" "name_change" "spinoff" "merger" "unknown"

The transaction type.

category
string <= 30 characters
security
string^[a-f0-9]{24}$

ID of the security involved in the transaction. Either security or symbol must be provided for transaction of types dividend, distribution, roc, reinvest, sell, buy, transfer_in and transfer_out.

symbol
string^[A-Z0-9.]+$

The ticker symbol for the security involved in the transaction (if any). Either security or symbol must be provided for transactions of types dividend, distribution, roc, reinvest, sell, buy, transfer_in and transfer_out.

quantity
number

The quantity of security involved in the transaction (if any).

currency_amount
required
number

The transaction amount, in transaction currency.

Array of objects

Transaction amount in different currencies.

description
string <= 350 characters

The transaction description.

note
string <= 400 characters

The transaction note.

fee
number

The transaction fee, in transaction currency.

realized_gain
number

[Deprecated] The realized gain amount for the sell transaction, in user preferred currency.

deleted
boolean

Whether or not the item is marked as deleted. Deleted items are not taken into account in calculations.

Responses

Request samples

Content type
application/json
{
  • "type": "deposit",
  • "category": "string",
  • "security": "5742b1f7535cf2baba8fff91",
  • "symbol": "string",
  • "quantity": 0,
  • "currency_amount": 0,
  • "amounts": [
    ],
  • "description": "string",
  • "note": "string",
  • "fee": 0,
  • "realized_gain": 0,
  • "deleted": true
}

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "user": "5742b1f7535cf2baba8fff91",
  • "institution": "5742b1f7535cf2baba8fff91",
  • "investment": "demo:cash:usd",
  • "asset": "5742b1f7535cf2baba8fff91",
  • "currency": "aud",
  • "date": "2019-08-24T14:15:22Z",
  • "processing_date": "2019-08-24T14:15:22Z",
  • "settlement_date": "2019-08-24T14:15:22Z",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "type": "deposit",
  • "origin_type": "string",
  • "origin_id": "string",
  • "category": "string",
  • "origin_category": "string",
  • "security": {
    },
  • "symbol": "string",
  • "description": "string",
  • "note": "string",
  • "currency_amount": 0,
  • "amount": 0,
  • "amounts": [
    ],
  • "fee": 0,
  • "quantity": 0,
  • "realized_gain": 0,
  • "user_created": true,
  • "deleted": true,
  • "incomplete": [
    ],
  • "missing": true,
  • "new": true,
  • "history": [
    ],
  • "other_parties": [
    ]
}

Security

Batch securities lookup

Resolves multiple {country}:{symbol} pairs at once and returns enriched security records, including the exchange. Equities only — options and funds frequently lack a symbol and/or exchange.

exchange is the raw enriched value (mixed short codes and full names, e.g. NASDAQ, Toronto Stock Exchange); exchange_code is the normalized short code (e.g. NASDAQ, TO, VN), or null when unknown.

Pairs that could not be resolved are returned in the missing list.

query Parameters
symbols
required
string

Comma-separated list of {country}:{symbol} pairs, country CA or US (e.g. CA:BCE,US:AAPL). Maximum 1000 pairs per request.

types
string
Value: "equities"

Security types filter. Only equities is supported currently.

Responses

Response samples

Content type
application/json
{
  • "securities": [
    ],
  • "missing": [
    ]
}

Preferences

Update user preferences

This endpoint is used to update user preferences.

Request Body schema: application/json
required

The preferences object for update. Attributes not present in this object will not be updated.

private_mode
required
boolean

Whether or not to enable Private Mode on login.

hide_switch_user_modal
required
boolean

Whether or not to hide Switch User modal on login.

hide_welcome_modal
required
boolean

Whether or not to hide Welcome modal on login.

hide_sidebar
boolean

Whether or not to hide Sidebar.

show_deleted_investments
required
boolean

Whether or not to show deleted investments/assets/liabilities on Dashboard.

required
object

Notification preferences

currency
required
string
Enum: "aud" "bbd" "brl" "btc" "cad" "chf" "cny" "dkk" "eth" "eur" "gbp" "hkd" "huf" "ils" "inr" "jpy" "krw" "mxn" "nok" "nzd" "ron" "pln" "aed" "sek" "sgd" "thb" "twd" "usd" "vnd" "zar"

User's preferred currency. This is the currency of all values returned in other API requests.

timezone
string

User's timezone, in which history data for assets & liabilities are recorded.

banner
string <data URI> <= 102400 characters

The user's banner image, in base64-encoded data URI. In an UPDATE request, sending a null value for banner will remove the image.

hide_first_time_connect_notice
boolean
Default: false

Whether or not to hide Connect Notice modal on connection flow.

date_range_filter_start
string <date-time>

The start date of the date range filter. By default, the date range filter starts from 10 years ago. This allows setting a custom starting date, for users who have transactions dated back further than that.

Responses

Request samples

Content type
application/json
{
  • "private_mode": true,
  • "hide_switch_user_modal": true,
  • "hide_welcome_modal": true,
  • "hide_sidebar": true,
  • "show_deleted_investments": true,
  • "notifications": {
    },
  • "currency": "aud",
  • "timezone": "string",
  • "banner": "string",
  • "hide_first_time_connect_notice": false,
  • "date_range_filter_start": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "private_mode": true,
  • "hide_switch_user_modal": true,
  • "hide_welcome_modal": true,
  • "hide_sidebar": true,
  • "show_deleted_investments": true,
  • "notifications": {
    },
  • "currency": "aud",
  • "timezone": "string",
  • "banner": "string",
  • "hide_first_time_connect_notice": false,
  • "date_range_filter_start": "2019-08-24T14:15:22Z"
}