Skip to main content
API docs by Redocly

Wealthica API (Wealthica API 1.0 (20240520-1.2016))

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

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. 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.

Note: Adding an 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.

Request Body schema: application/json

The institution object that needs to be added.

name
string

Name of the institution.

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.

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",
  • "credentials": {
    },
  • "sync_documents": true,
  • "sync_transactions": true,
  • "daily_sync": true,
  • "type": "string"
}

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "user": "5742b1f7535cf2baba8fff91",
  • "name": "Demo",
  • "type": "string",
  • "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
}

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",
  • "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
}

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

The institution object for update.

name
string

Name of the institution.

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.

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.

Array of objects

Updated data for investments.

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",
  • "credentials": {
    },
  • "sync_documents": true,
  • "sync_transactions": true,
  • "daily_sync": true,
  • "portfolio_manager": "string",
  • "deleted": true,
  • "investments": [
    ],
  • "security_answer": "string"
}

Response samples

Content type
application/json
{
  • "_id": "5742b1f7535cf2baba8fff91",
  • "user": "5742b1f7535cf2baba8fff91",
  • "name": "Demo",
  • "type": "string",
  • "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
}

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",
  • "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
}

Sync institution

Trigger synchronization for the institution.

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",
  • "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
}

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

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" "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": [
    ],
  • "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": [
    ],
  • "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

The asset object for update.

name
string

Name of the asset.

class
string
Enum: "equity" "fixed_income" "cash_equivalent" "tangible_asset" "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

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": [
    ],
  • "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

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

The liability object that needs to be added.

name
required
string

Name of the liability.

type
required
string
Enum: "mortgage" "other_debt"

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" "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

The liability object for update.

name
string

Name of the liability.

type
string
Enum: "mortgage" "other_debt"

Type of the liability.

groups
Array of strings

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" "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

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

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"
]

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

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

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

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

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

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

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

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

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
[
  • {
    }
]

Update an existing position

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

The position object for update.

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

The position class.

Array of objects

The position classes.

category
string

The position category.

categories
string

The position category.

Responses

Request samples

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

Response samples

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

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

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

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

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

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

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" "tax" "fee" "sell" "buy" "income" "split" "mtm" "loan" "recall" "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

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" "tax" "fee" "sell" "buy" "income" "split" "mtm" "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.

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,
  • "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,
  • "fee": 0,
  • "quantity": 0,
  • "realized_gain": 0,
  • "user_created": true,
  • "deleted": true,
  • "incomplete": [
    ],
  • "missing": true,
  • "new": true,
  • "history": [
    ],
  • "other_parties": [
    ]
}

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,
  • "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

The transaction object for update.

type
required
string
Enum: "deposit" "withdrawal" "transfer" "transfer_in" "transfer_out" "switch" "interest" "dividend" "distribution" "roc" "reinvest" "tax" "fee" "sell" "buy" "income" "split" "mtm" "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.

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,
  • "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,
  • "fee": 0,
  • "quantity": 0,
  • "realized_gain": 0,
  • "user_created": true,
  • "deleted": true,
  • "incomplete": [
    ],
  • "missing": true,
  • "new": true,
  • "history": [
    ],
  • "other_parties": [
    ]
}

Preferences

Update user preferences

This endpoint is used to update user preferences.

Request Body schema: application/json

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" "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.

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
}

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
}