FinWise API Reference

Introduction

The FinWise API is in beta: Please note that the FinWise API is currently in beta and breaking changes may occur from time to time. See API changes in our API Changelog.

The FinWise API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

The FinWise API supports bulk operations, such as bulk updates and deletions allowing you to efficiently process and manage large amounts of data in a single request.

BASE URL

https://api.finwiseapp.io

Authentication

The FinWise API uses API keys to authenticate requests. You can view and manage your API keys in the FinWise Dashboard from Settings > API Keys.

To authenticate an API request, specify your API key in the Authorization header.

Your API keys carry many privileges, so be sure to keep them secure. Do not share your API keys in publicly accessible areas such as GitHub, client-side code, and so on.

You can revoke or roll your API keys from the FinWise Dashboard from Settings > API Keys.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

AUTHENTICATE API REQUESTS

import axios from 'axios'

const response = await axios({
  method: 'get',
  url: 'https://api.finwiseapp.io',
  headers: {
    'Content-Type': 'application/json',
    Authorization: '<YOUR_API_KEY>',
  },
})

Errors

FinWise uses conventional HTTP response codes to indicate the success or failure of an API request.

Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.). Codes in the 5xx range indicate an error with FinWise`s servers (these are rare).

Response Body Attributes

name

enum

The type of error returned. One of BadRequestError, UnauthenticatedError, ForbiddenError, NotFoundError, ConflictError

message

string

A human-readable message providing more details about the error.

errors

array of objects

An array of objects containing individual field-level error details.

code

string

Error code of the field error.

message

string

A human-readable message providing more details about the field error.

path

array of strings

Path of the field causing the error.

received

string

Value received by the API.

HTTP RESPONSE CODES

200 OK Everything worked as expected.
400 Bad Request The request was unacceptable, often due to missing a required parameter.
401 Unauthorized No valid API key provided.
402 Request Failed The parameters were valid but the request failed.
403 Forbidden The API key doesn’t have permissions to perform the request.
404 Not Found The requested resource doesn’t exist.
409 Conflict The request conflicts with another request.
429 Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
5xx Server Errors Something went wrong on FinWise’s end. (These are rare.)

SAMPLE ERROR RESPONSE

{
  "name": "BadRequestError",
  "message": "Invalid query parameters specified",
  "errors": [{
      "code": "invalid_type",
      "message": "Invalid date format, must use ISO format.",
      "path": ["date"],
      "received": "28 April 2024",
    }]
}

Pagination

All FinWise API resources have support for bulk fetches using 'list' endpoints using HTTP GET methods, e.g., GET /transactions will return a list of transactions.

All 'list' endpoints support pagination using the pagination parameter which is currently based on limit/offset pagination by specifying pageNumber and pageSize inside the pagination parameter.

In the future, FinWise will support cursor based pagination which is more performant and stable to use across pages.

Query String Attributes

pagination

object

An object containing pagination attributes pageNumber and pageSize.

pageNumber

number

The page number to fetch, defaults to 1.

pageSize

number

The page size to fetch, defaults to 100.

SAMPLE PAGINATED REQUEST

import axios from 'axios'

const response = await axios({
  method: 'get',
  url: 'https://api.finwiseapp.io/transactions?pagination={"pageNumber":1,"pageSize":100}',
  headers: {
    'Content-Type': 'application/json',
    Authorization: '<YOUR_API_KEY>',
  },
})

Request IDs

All FinWise API requests have an associated request ID which is a unique identifier for the request being made. You can find the request ID in the response header Request-Id.

The request ID is useful for debugging purposes and tracks any data retrieved or manipulated by an API request.

SAMPLE RESPONSE

// API response snippet
{
  ...
  headers: {
    "Request-Id": "2de45a90-b728-4c81-b69c-068b9eb68713",
  },
  ...
}

Versioning

The FinWise API is not currently versioned because FinWise is under heavy active development.

Our API will change from time to time with potentially breaking changes, so be sure to check for API changes in our API Changelog and ensure that any code using our API has validation and appropriate error handling.

In the near future, the FinWise API will be versioned so that breaking changes will not affect previous versions of the API and instead will form part of a new version of the API.

Accounts

This object represents a financial account.

ENDPOINTS

POST /accounts Create a new account
PATCH /accounts/:id Update an account
GET /accounts Get a list of accounts
GET /accounts/:id Get an account

The account object

Attributes

id

string

Unique identifier for the account.

createdAt

string

Date the account was created.

updatedAt

string

Date the account was last updated.

userId

string

Unique identifier of the user who owns the account.

name

string

Name of the account.

logoBase64

nullable string

Base64 encoded logo image of the account.

emoji

nullable string

Emoji of the account.

accountNumber

nullable string

Account number from the financial institution of the account.

currentBalance

object

Current balance of the account.

amount

number

Amount of the balance.

currencyCode

string

Currency code of the balance.

availableBalance

nullable object

Available balance of the account.

amount

number

Amount of the balance.

currencyCode

string

Currency code of the balance.

type

enum

Type of account, one of the following values: depository, credit, loan, investment, other.

subType

enum

Sub type of account.

originalLoanAmount

nullable object

Original loan amount, only applies for loan type accounts.

amount

number

Amount of the original loan amount.

currencyCode

string

Currency code of the original loan amount.

originationDate

nullable string

Last payment date for the account.

interestRate

nullable number

Interest rate percentage.

interestRateType

nullable string

The type of the interest rate.

lastPaymentDate

nullable string

Last payment date for the account.

lastPaymentAmount

nullable object

Last payment amount for the account.

amount

number

Amount of the last payment.

currencyCode

string

Currency code of the last payment.

amountDue

nullable object

Amount due for the account.

amount

number

Amount of the amount due.

currencyCode

string

Currency code of the amount due.

minimumAmountDue

nullable object

Minimum amount due for the account.

amount

number

Amount of the minimum amount due.

currencyCode

string

Currency code of the minimum amount due.

archivedAt

nullable string

Date at which the account was archived.

isLinked

nullable boolean

Whether or not the account is linked to a provider like Plaid, Yodlee or MX.

institutionId

nullable string

The unique identifier of the financial institution that the account is linked to.

institutionUserId

nullable string

The unique identifier of the data connection to the financial institution that the account is linked to.

data

nullable object

Additional data and configuration for the account.

excludeFromBudget

boolean

Whether or not the account transactions should be excluded from the budget.

excludeFromNetWorth

boolean

Whether or not the account should be excluded from the net-worth.

excludeTransactions

boolean

Whether or not the account transactions should completely ignored by FinWise.

invertAmounts

boolean

Whether or not the account balances should be inverted.

THE ACCOUNT OBJECT

{
  "id": "94d2f962-d4e3-4c99-ab47-8c941cea012a",
  "createdAt": "2024-05-01T09:15:46.724Z",
  "updatedAt": "2024-05-01T09:15:46.724Z",
  "userId": "f472696c-47ac-4873-98cf-2a1069a1cf45",
  "name": "My Credit Card Account",
  "displayName": null,
  "friendlyName": null,
  "accountNumber": "275417291",
  "currentBalance": {
    "amount": -3432,
    "currencyCode": "USD"
  },
  "availableBalance": null,
  "accountType": null,
  "archivedAt": null,
  "isLinked": true,
  "institutionId": "b8cb6f04-2f2b-440a-a55f-6708ebb57130",
  "type": "credit",
  "subType": "credit card",
  "logoBase64": null,
  "data": null,
  "interestRate": null,
  "interestRateType": null,
  "lastPaymentDate": null,
  "lastPaymentAmount": null,
  "minimumAmountDue": null,
  "originationDate": null,
  "amountDue": null,
  "originalLoanAmount": null,
  "institutionUserId": null,
  "emoji": "💳",
  "institution": null
}

Create an account

Request Body Attributes

id

string

Unique identifier for the account.

userId

string

Unique identifier of the user who owns the account.

name

string

Name of the account.

logoBase64

nullable string

Base64 encoded logo image of the account.

emoji

nullable string

Emoji of the account.

accountNumber

nullable string

Account number from the financial institution of the account.

currentBalance

object

Current balance of the account.

amount

number

Amount of the balance.

currencyCode

string

Currency code of the balance.

availableBalance

nullable object

Available balance of the account.

amount

number

Amount of the balance.

currencyCode

string

Currency code of the balance.

type

enum

Type of account, one of the following values: depository, credit, loan, investment, other.

subType

enum

Sub type of account.

originalLoanAmount

nullable object

Original loan amount, only applies for loan type accounts.

amount

number

Amount of the original loan amount.

currencyCode

string

Currency code of the original loan amount.

originationDate

nullable string

Last payment date for the account.

interestRate

nullable number

Interest rate percentage.

interestRateType

nullable string

The type of the interest rate.

lastPaymentDate

nullable string

Last payment date for the account.

lastPaymentAmount

nullable object

Last payment amount for the account.

amount

number

Amount of the last payment.

currencyCode

string

Currency code of the last payment.

amountDue

nullable object

Amount due for the account.

amount

number

Amount of the amount due.

currencyCode

string

Currency code of the amount due.

minimumAmountDue

nullable object

Minimum amount due for the account.

amount

number

Amount of the minimum amount due.

currencyCode

string

Currency code of the minimum amount due.

archivedAt

nullable string

Date at which the account was archived.

data

nullable object

Additional data and configuration for the account.

excludeFromBudget

boolean

Whether or not the account transactions should be excluded from the budget.

excludeFromNetWorth

boolean

Whether or not the account should be excluded from the net-worth.

excludeTransactions

boolean

Whether or not the account transactions should completely ignored by FinWise.

invertAmounts

boolean

Whether or not the account balances should be inverted.

POST /accounts

import axios from 'axios'

const response = await axios({
  method: 'post',
  url: 'https://api.finwiseapp.io/accounts',
  headers: {
    'Content-Type': 'application/json',
    Authorization: '<YOUR_API_KEY>',
  },
  body: {
    "name": "My Credit Card Account",
    "type": "credit",
    "subType": "credit card",
    "currentBalance": {"amount": -3432, "currencyCode": "USD"},
    "accountNumber": "275417291"
  }
})

RESPONSE

{
  "id": "94d2f962-d4e3-4c99-ab47-8c941cea012a",
  "createdAt": "2024-05-01T09:15:46.724Z",
  "updatedAt": "2024-05-01T09:15:46.724Z",
  "userId": "f472696c-47ac-4873-98cf-2a1069a1cf45",
  "name": "My Credit Card Account",
  "displayName": null,
  "friendlyName": null,
  "accountNumber": "275417291",
  "currentBalance": {
    "amount": -3432,
    "currencyCode": "USD"
  },
  "availableBalance": null,
  "accountType": null,
  "archivedAt": null,
  "isLinked": true,
  "institutionId": "b8cb6f04-2f2b-440a-a55f-6708ebb57130",
  "type": "credit",
  "subType": "credit card",
  "logoBase64": null,
  "data": null,
  "interestRate": null,
  "interestRateType": null,
  "lastPaymentDate": null,
  "lastPaymentAmount": null,
  "minimumAmountDue": null,
  "originationDate": null,
  "amountDue": null,
  "originalLoanAmount": null,
  "institutionUserId": null,
  "emoji": "💳",
  "institution": null
}

Update an account

Request Body Attributes

name

string

Name of the account.

logoBase64

nullable string

Base64 encoded logo image of the account.

emoji

nullable string

Emoji of the account.

accountNumber

nullable string

Account number from the financial institution of the account.

currentBalance

object

Current balance of the account.

amount

number

Amount of the balance.

currencyCode

string

Currency code of the balance.

availableBalance

nullable object

Available balance of the account.

amount

number

Amount of the balance.

currencyCode

string

Currency code of the balance.

type

enum

Type of account, one of the following values: depository, credit, loan, investment, other.

subType

enum

Sub type of account.

originalLoanAmount

nullable object

Original loan amount, only applies for loan type accounts.

amount

number

Amount of the original loan amount.

currencyCode

string

Currency code of the original loan amount.

originationDate

nullable string

Last payment date for the account.

interestRate

nullable number

Interest rate percentage.

interestRateType

nullable string

The type of the interest rate.

lastPaymentDate

nullable string

Last payment date for the account.

lastPaymentAmount

nullable object

Last payment amount for the account.

amount

number

Amount of the last payment.

currencyCode

string

Currency code of the last payment.

amountDue

nullable object

Amount due for the account.

amount

number

Amount of the amount due.

currencyCode

string

Currency code of the amount due.

minimumAmountDue

nullable object

Minimum amount due for the account.

amount

number

Amount of the minimum amount due.

currencyCode

string

Currency code of the minimum amount due.

archivedAt

nullable string

Date at which the account was archived.

data

nullable object

Additional data and configuration for the account.

excludeFromBudget

boolean

Whether or not the account transactions should be excluded from the budget.

excludeFromNetWorth

boolean

Whether or not the account should be excluded from the net-worth.

excludeTransactions

boolean

Whether or not the account transactions should completely ignored by FinWise.

invertAmounts

boolean

Whether or not the account balances should be inverted.

PATCH /accounts/:id

import axios from 'axios'

const response = await axios({
  method: 'patch',
  url: 'https://api.finwiseapp.io/accounts/94d2f962-d4e3-4c99-ab47-8c941cea012a',
  headers: {
    'Content-Type': 'application/json',
    Authorization: '<YOUR_API_KEY>',
  },
  body: {
    "name": "My Credit Card Account",
  }
})

RESPONSE

{
  "id": "94d2f962-d4e3-4c99-ab47-8c941cea012a",
  "createdAt": "2024-05-01T09:15:46.724Z",
  "updatedAt": "2024-05-01T09:15:46.724Z",
  "userId": "f472696c-47ac-4873-98cf-2a1069a1cf45",
  "name": "My Credit Card Account",
  "displayName": null,
  "friendlyName": null,
  "accountNumber": "275417291",
  "currentBalance": {
    "amount": -3432,
    "currencyCode": "USD"
  },
  "availableBalance": null,
  "accountType": null,
  "archivedAt": null,
  "isLinked": true,
  "institutionId": "b8cb6f04-2f2b-440a-a55f-6708ebb57130",
  "type": "credit",
  "subType": "credit card",
  "logoBase64": null,
  "data": null,
  "interestRate": null,
  "interestRateType": null,
  "lastPaymentDate": null,
  "lastPaymentAmount": null,
  "minimumAmountDue": null,
  "originationDate": null,
  "amountDue": null,
  "originalLoanAmount": null,
  "institutionUserId": null,
  "emoji": "💳",
  "institution": null
}

Get accounts

Get accounts.

Query String Attributes

filters

nullable object

Apply filters to the list of accounts.

id

nullable string

Filter accounts by the account ID.

userId

nullable string

Filter accounts by the user ID.

search

nullable string

Search accounts. Search performs a wildcard search on account names.

isArchived

nullable boolean

Filter accounts by whether or not the account is archived.

pagination

nullable object

Pagination options.

pageNumber

nullable number

Page number to fetch, defaults to 1.

pageSize

nullable number

Number of items per page to fetch, defaults to 100.

GET /accounts

import axios from 'axios'

const response = await axios({
  method: 'get',
  url: 'https://api.finwiseapp.io/accounts?filters={"userId":"f472696c-47ac-4873-98cf-2a1069a1cf45"}',
  headers: {
    'Content-Type': 'application/json',
    Authorization: '<YOUR_API_KEY>',
  },
})

RESPONSE

[
  {
    "id": "94d2f962-d4e3-4c99-ab47-8c941cea012a",
    "createdAt": "2024-05-01T09:15:46.724Z",
    "updatedAt": "2024-05-01T09:15:46.724Z",
    "userId": "f472696c-47ac-4873-98cf-2a1069a1cf45",
    "name": "My Credit Card Account",
    "displayName": null,
    "friendlyName": null,
    "accountNumber": "275417291",
    "currentBalance": {
      "amount": -3432,
      "currencyCode": "USD"
    },
    "availableBalance": null,
    "accountType": null,
    "archivedAt": null,
    "isLinked": true,
    "institutionId": "b8cb6f04-2f2b-440a-a55f-6708ebb57130",
    "type": "credit",
    "subType": "credit card",
    "logoBase64": null,
    "data": null,
    "interestRate": null,
    "interestRateType": null,
    "lastPaymentDate": null,
    "lastPaymentAmount": null,
    "minimumAmountDue": null,
    "originationDate": null,
    "amountDue": null,
    "originalLoanAmount": null,
    "institutionUserId": null,
    "emoji": "💳",
    "institution": null
  }
]

Get an account

Get an account.

GET /accounts/:id

import axios from 'axios'

const response = await axios({
  method: 'get',
  url: 'https://api.finwiseapp.io/accounts/94d2f962-d4e3-4c99-ab47-8c941cea012a',
  headers: {
    'Content-Type': 'application/json',
    Authorization: '<YOUR_API_KEY>',
  },
})

RESPONSE

{
  "id": "94d2f962-d4e3-4c99-ab47-8c941cea012a",
  "createdAt": "2024-05-01T09:15:46.724Z",
  "updatedAt": "2024-05-01T09:15:46.724Z",
  "userId": "f472696c-47ac-4873-98cf-2a1069a1cf45",
  "name": "My Credit Card Account",
  "displayName": null,
  "friendlyName": null,
  "accountNumber": "275417291",
  "currentBalance": {
    "amount": -3432,
    "currencyCode": "USD"
  },
  "availableBalance": null,
  "accountType": null,
  "archivedAt": null,
  "isLinked": true,
  "institutionId": "b8cb6f04-2f2b-440a-a55f-6708ebb57130",
  "type": "credit",
  "subType": "credit card",
  "logoBase64": null,
  "data": null,
  "interestRate": null,
  "interestRateType": null,
  "lastPaymentDate": null,
  "lastPaymentAmount": null,
  "minimumAmountDue": null,
  "originationDate": null,
  "amountDue": null,
  "originalLoanAmount": null,
  "institutionUserId": null,
  "emoji": "💳",
  "institution": null
}

Archive an account

Archive an account.

POST /accounts/:id/archive

import axios from 'axios'

const response = await axios({
  method: 'post',
  url: 'https://api.finwiseapp.io/accounts/94d2f962-d4e3-4c99-ab47-8c941cea012a/archive',
  headers: {
    'Content-Type': 'application/json',
    Authorization: '<YOUR_API_KEY>',
  },
})

RESPONSE

{
  "id": "94d2f962-d4e3-4c99-ab47-8c941cea012a",
  "createdAt": "2024-05-01T09:15:46.724Z",
  "updatedAt": "2024-05-01T09:15:46.724Z",
  "userId": "f472696c-47ac-4873-98cf-2a1069a1cf45",
  "name": "My Credit Card Account",
  "displayName": null,
  "friendlyName": null,
  "accountNumber": "275417291",
  "currentBalance": {
    "amount": -3432,
    "currencyCode": "USD"
  },
  "availableBalance": null,
  "accountType": null,
  "archivedAt": "2024-04-29T00:03:34",
  "isLinked": true,
  "institutionId": "b8cb6f04-2f2b-440a-a55f-6708ebb57130",
  "type": "credit",
  "subType": "credit card",
  "logoBase64": null,
  "data": null,
  "interestRate": null,
  "interestRateType": null,
  "lastPaymentDate": null,
  "lastPaymentAmount": null,
  "minimumAmountDue": null,
  "originationDate": null,
  "amountDue": null,
  "originalLoanAmount": null,
  "institutionUserId": null,
  "emoji": "💳",
  "institution": null
}

Account Balances

This object represents an account balance, which is a snapshot of the balance of an account on a particular date.

ENDPOINTS

POST /account-balances Create an account balance
GET /account-balances Get a list of account balances
GET /account-balances/aggregated2 Get aggregate account balances
POST /account-balances/:id/archive Archive an account balance

The account balance object

Attributes

id

string

Unique identifier for the account balance.

createdAt

string

Date the account balance was created.

updatedAt

string

Date the account balance was last updated.

accountId

string

Unique identifier of the account of the balance.

userId

string

Unique identifier of the user who owns the account balance.

date

string

Date of the account balance.

amount

nullable object

Amount of the balance.

amount

number

Amount.

currencyCode

string

Currency code of the amount.

type

enum

Type of the balance, one of manual or synced.

dataImportId

nullable string

Unique identifier of the data import that created the account balance.

archivedAt

nullable string

Date the account balance was archived at.

THE ACCOUNT BALANCE OBJECT

{
  "id": "b8cb6f04-2f2b-440a-a55f-6708ebb57130",
  "createdAt": "2024-05-01T09:15:46.728Z",
  "updatedAt": "2024-05-01T09:15:46.728Z",
  "accountId": "94d2f962-d4e3-4c99-ab47-8c941cea012a",
  "date": "2024-05-01T09:15:46.724Z",
  "amount": {
    "amount": -3432,
    "currencyCode": "USD"
  },
  "tt7Details": null,
  "userId": "f472696c-47ac-4873-98cf-2a1069a1cf45",
  "isManual": null,
  "archivedAt": null,
  "type": "manual",
  "dataImportId": null
}

Create an account balance

Create an account balance.

Request Body Attributes

accountId

string

Unique identifier of the account of the balance.

date

string

Date of the account balance.

amount

object

Amount of the balance.

amount

number

Amount.

currencyCode

string

Currency code of the amount.

POST /account-balances

import axios from 'axios'

const response = await axios({
  method: 'post',
  url: 'https://api.finwiseapp.io/account-balances',
  headers: {
    'Content-Type': 'application/json',
    Authorization: '<YOUR_API_KEY>',
  },
  body: {
    "accountId": "94d2f962-d4e3-4c99-ab47-8c941cea012a",
    "amount": {"amount":-3432,"currencyCode":"USD"},
    "date": "2024-05-01T09:15:46.724Z",
  }
})

RESPONSE

{
  "id": "b8cb6f04-2f2b-440a-a55f-6708ebb57130",
  "createdAt": "2024-05-01T09:15:46.728Z",
  "updatedAt": "2024-05-01T09:15:46.728Z",
  "accountId": "94d2f962-d4e3-4c99-ab47-8c941cea012a",
  "date": "2024-05-01T09:15:46.724Z",
  "amount": {
    "amount": -3432,
    "currencyCode": "USD"
  },
  "tt7Details": null,
  "userId": "f472696c-47ac-4873-98cf-2a1069a1cf45",
  "isManual": null,
  "archivedAt": null,
  "type": "manual",
  "dataImportId": null
}

Get account balances

Get account balances.

Query String Attributes

filters

nullable object

Apply filters to the list of account balances.

id

nullable string

Filter account balances by the account balance ID.

ids

nullable array of strings

Filter account balances by account balance IDs.

accountId

nullable string

Filter account balances by an account ID.

accountIds

nullable array of strings

Filter account balances by account IDs.

fromDate

nullable string

Filter account balances from a date.

toDate

nullable string

Filter account balances up to a date.

isPositive

nullable boolean

Filter account balances that are positive.

isNegative

nullable boolean

Filter account balances that are negative.

excludeExcluded

nullable boolean

Exclude account balances from accounts which are configured by to excluded from net-worth calculations.

pagination

nullable object

Pagination options.

pageNumber

nullable number

Page number to fetch, defaults to 1.

pageSize

nullable number

Number of items per page to fetch, defaults to 100.

GET /account-balances

import axios from 'axios'

const response = await axios({
  method: 'get',
  url: 'https://api.finwiseapp.io/account-balances?filters={"userId":"f472696c-47ac-4873-98cf-2a1069a1cf45"}',
  headers: {
    'Content-Type': 'application/json',
    Authorization: '<YOUR_API_KEY>',
  },
})

RESPONSE

[
  {
    "id": "b8cb6f04-2f2b-440a-a55f-6708ebb57130",
    "createdAt": "2024-05-01T09:15:46.728Z",
    "updatedAt": "2024-05-01T09:15:46.728Z",
    "accountId": "94d2f962-d4e3-4c99-ab47-8c941cea012a",
    "date": "2024-05-01T09:15:46.724Z",
    "amount": {
      "amount": -3432,
      "currencyCode": "USD"
    },
    "tt7Details": null,
    "userId": "f472696c-47ac-4873-98cf-2a1069a1cf45",
    "isManual": null,
    "archivedAt": null,
    "type": "manual",
    "dataImportId": null
  }
]

Get aggregated account balances

Get aggregated account balances. This endpoint aggregates account balances and performs addition on the aggregated account balances.

Query String Attributes

aggregateBy

array of enums

Fields to aggregate account balances by, must be an array of one of day, week, Month, Year

aggregateFn

enum

Function to use on aggregation, only latest supported for now.

currencyCode

nullable enum

Currency code to convert balances to.

filters

nullable object

Apply filters to the list of account balances.

id

nullable string

Filter account balances by the account balance ID.

ids

nullable array of strings

Filter account balances by account balance IDs.

accountId

nullable string

Filter account balances by an account ID.

accountIds

nullable array of strings

Filter account balances by account IDs.

fromDate

nullable string

Filter account balances from a date.

toDate

nullable string

Filter account balances up to a date.

isPositive

nullable boolean

Filter account balances that are positive.

isNegative

nullable boolean

Filter account balances that are negative.

excludeExcluded

nullable boolean

Exclude account balances from accounts which are configured by to excluded from net-worth calculations.

pagination

nullable object

Pagination options.

pageNumber

nullable number

Page number to fetch, defaults to 1.

pageSize

nullable number

Number of items per page to fetch, defaults to 100.

GET /account-balances/aggregated2

import axios from 'axios'

const response = await axios({
  method: 'get',
  url: 'https://api.finwiseapp.io/account-balances/aggregated2?aggregateBy[]=day&aggregateFn=latest&filters={"userId":"f472696c-47ac-4873-98cf-2a1069a1cf45"}',
  headers: {
    'Content-Type': 'application/json',
    Authorization: '<YOUR_API_KEY>',
  },
})

RESPONSE

[
  {
    "id": "b8cb6f04-2f2b-440a-a55f-6708ebb57130",
    "createdAt": "2024-05-01T09:15:46.728Z",
    "updatedAt": "2024-05-01T09:15:46.728Z",
    "accountId": "94d2f962-d4e3-4c99-ab47-8c941cea012a",
    "date": "2024-05-01T09:15:46.724Z",
    "amount": {
      "amount": -3432,
      "currencyCode": "USD"
    },
    "tt7Details": null,
    "userId": "f472696c-47ac-4873-98cf-2a1069a1cf45",
    "isManual": null,
    "archivedAt": null,
    "type": "manual",
    "dataImportId": null
  }
]

Archive an account balance

Archive an account balance.

POST /account-balances/:id/archive

import axios from 'axios'

const response = await axios({
  method: 'post',
  url: 'https://api.finwiseapp.io/account-balances/b8cb6f04-2f2b-440a-a55f-6708ebb57130/archive',
  headers: {
    'Content-Type': 'application/json',
    Authorization: '<YOUR_API_KEY>',
  },
})

RESPONSE

{
  "id": "b8cb6f04-2f2b-440a-a55f-6708ebb57130",
  "createdAt": "2024-05-01T09:15:46.728Z",
  "updatedAt": "2024-05-01T09:15:46.728Z",
  "accountId": "94d2f962-d4e3-4c99-ab47-8c941cea012a",
  "date": "2024-05-01T09:15:46.724Z",
  "amount": {
    "amount": -3432,
    "currencyCode": "USD"
  },
  "tt7Details": null,
  "userId": "f472696c-47ac-4873-98cf-2a1069a1cf45",
  "isManual": null,
  "archivedAt": "2024-04-29T00:03:34",
  "type": "manual",
  "dataImportId": null
}

Transactions

This object represents a transaction.

ENDPOINTS

POST /transactions Create a transaction
GET /transactions Get a list of transactions
GET /transactions/aggregated3 Get aggregated transactions
POST /transactions/:id/archive Archive a transaction

The transaction object

Attributes

id

string

Unique identifier for the transaction.

createdAt

string

Date the transaction was created.

updatedAt

string

Date the transaction was last updated.

userId

string

Unique identifier of the user who owns the transaction.

date

string

Date of the transaction.

amount

nullable object

Amount of the transaction.

amount

number

Amount of the transaction.

currencyCode

string

Currency code of the amount.

transactionCategoryId

nullable string

Unique identifier of the transaction category the transaction belongs to.

merchantId

nullable string

Unique identifier of the merchant/payee the transaction belongs to.

isTransfer

nullable boolean

Whether or not the transaction is a transfer.

isPending

nullable boolean

Whether or not the transaction is pending or posted.

needsReview

nullable boolean

Whether or not the transaction needs to be reviewed.

notes

nullable boolean

Notes about the transaction.

THE TRANSACTION OBJECT

{
  "id": "9da3aab1-be6c-4e6a-9b03-fd50e9aca541",
  "createdAt": "2024-05-01T14:18:22.304Z",
  "updatedAt": "2024-05-01T14:18:22.304Z",
  "description": "Walmart",
  "originalDescription": "Walmart",
  "accountId": "94d2f962-d4e3-4c99-ab47-8c941cea012a",
  "amount": {
    "amount": -56,
    "currencyCode": "USD"
  },
  "date": "2024-05-01T14:18:02.744Z",
  "transactionCategoryId": "a00cb43b-ab06-447c-8aeb-527680b20a50",
  "originalTransactionCategoryId": "a00cb43b-ab06-447c-8aeb-527680b20a50",
  "merchantId": "d4dd1cbe-d349-4089-ad63-b98921426656",
  "originalMerchantId": "d4dd1cbe-d349-4089-ad63-b98921426656",
  "parentTransactionId": null,
  "splits": null,
  "isManual": true,
  "isTransfer": null,
  "notes": null,
  "userId": "f472696c-47ac-4873-98cf-2a1069a1cf45",
  "archivedAt": null,
  "effectiveDate": null,
  "dataImportId": null,
  "needsReview": null,
  "isPending": null,
  "pendingTransactionId": null,
  "transactionTags": [],
  "fileRecords": []
}

Create a transaction

Create a transaction.

Request Body Attributes

accountId

string

Unique identifier of the account of the transaction.

date

string

Date of the transaction.

effectiveDate

nullable string

Effective date of the transaction.

amount

object

Amount of the transaction.

amount

number

Amount.

currencyCode

string

Currency code of the amount.

transactionCategoryId

nullable string

Unique identifier of the transaction category of the transaction.

merchantId

nullable string

Unique identifier of the merchant of the transaction.

isTransfer

nullable boolean

Whether or not the transaction is a transfer.

notes

nullable string

Notes for the transaction.

POST /transactions

import axios from 'axios'

const response = await axios({
  method: 'post',
  url: 'https://api.finwiseapp.io/transactions',
  headers: {
    'Content-Type': 'application/json',
    Authorization: '<YOUR_API_KEY>',
  },
  body: {
    "accountId": "94d2f962-d4e3-4c99-ab47-8c941cea012a",
    "amount": {"amount":-56,"currencyCode":"USD"},
    "date": "2024-05-01T14:18:02.744Z",
    "transactionCategoryId": "a00cb43b-ab06-447c-8aeb-527680b20a50",
  }
})

RESPONSE

{
  "id": "9da3aab1-be6c-4e6a-9b03-fd50e9aca541",
  "createdAt": "2024-05-01T14:18:22.304Z",
  "updatedAt": "2024-05-01T14:18:22.304Z",
  "description": "Walmart",
  "originalDescription": "Walmart",
  "accountId": "94d2f962-d4e3-4c99-ab47-8c941cea012a",
  "amount": {
    "amount": -56,
    "currencyCode": "USD"
  },
  "date": "2024-05-01T14:18:02.744Z",
  "transactionCategoryId": "a00cb43b-ab06-447c-8aeb-527680b20a50",
  "originalTransactionCategoryId": "a00cb43b-ab06-447c-8aeb-527680b20a50",
  "merchantId": "d4dd1cbe-d349-4089-ad63-b98921426656",
  "originalMerchantId": "d4dd1cbe-d349-4089-ad63-b98921426656",
  "parentTransactionId": null,
  "splits": null,
  "isManual": true,
  "isTransfer": null,
  "notes": null,
  "userId": "f472696c-47ac-4873-98cf-2a1069a1cf45",
  "archivedAt": null,
  "effectiveDate": null,
  "dataImportId": null,
  "needsReview": null,
  "isPending": null,
  "pendingTransactionId": null,
  "transactionTags": [],
  "fileRecords": []
}

Get transactions

Get transactions.

Query String Attributes

filters

nullable object

Apply filters to the list of transactions.

id

nullable string

Filter transactions by a transaction ID.

ids

nullable array of strings

Filter transactions by multiple transaction IDs.

accountId

nullable string

Filter transactions by an account ID.

accountIds

nullable array of strings

Filter transactions by account IDs.

transactionCategoryIds

nullable array of strings

Filter transactions by transaction category IDs.

search

nullable string

Search param which does a wildcard search on the transaction description and merchant name.

fromDate

nullable string

Filter transactions from a date.

toDate

nullable string

Filter transactions up to a date.

needsReview

nullable boolean

Filter transactions which need review or not.

transactionTypes

nullable array of enums

Filter transactions based on whether they are a debit/withdrawal or credit/deposit. Must be an array of debit or credit.

amountGte

nullable number

Filter transactions which have an amount greater than or equal to a value.

amountLte

nullable number

Filter transactions which have an amount less than or equal to a value.

excludeParentTransactions

nullable boolean

Exclude transactions which are parent transactions of transactions which have been split.

excludeTransfers

nullable boolean

Exclude transactions which are marked as transfers.

excludeArchived

nullable boolean

Exclude transactions which are archived.

excludeExcludedTransactions

nullable boolean

Exclude transactions from accounts which are configured to have their transactions ignored/excluded.

pagination

nullable object

Pagination options.

pageNumber

nullable number

Page number to fetch, defaults to 1.

pageSize

nullable number

Number of items per page to fetch, defaults to 100.

GET /transactions

import axios from 'axios'

const response = await axios({
  method: 'get',
  url: 'https://api.finwiseapp.io/transactions?filters={"accountId":"f472696c-47ac-4873-98cf-2a1069a1cf45"}',
  headers: {
    'Content-Type': 'application/json',
    Authorization: '<YOUR_API_KEY>',
  },
})

RESPONSE

[
  {
    "id": "9da3aab1-be6c-4e6a-9b03-fd50e9aca541",
    "createdAt": "2024-05-01T14:18:22.304Z",
    "updatedAt": "2024-05-01T14:18:22.304Z",
    "description": "Walmart",
    "originalDescription": "Walmart",
    "accountId": "94d2f962-d4e3-4c99-ab47-8c941cea012a",
    "amount": {
      "amount": -56,
      "currencyCode": "USD"
    },
    "date": "2024-05-01T14:18:02.744Z",
    "transactionCategoryId": "a00cb43b-ab06-447c-8aeb-527680b20a50",
    "originalTransactionCategoryId": "a00cb43b-ab06-447c-8aeb-527680b20a50",
    "merchantId": "d4dd1cbe-d349-4089-ad63-b98921426656",
    "originalMerchantId": "d4dd1cbe-d349-4089-ad63-b98921426656",
    "parentTransactionId": null,
    "splits": null,
    "isManual": true,
    "isTransfer": null,
    "notes": null,
    "userId": "f472696c-47ac-4873-98cf-2a1069a1cf45",
    "archivedAt": null,
    "effectiveDate": null,
    "dataImportId": null,
    "needsReview": null,
    "isPending": null,
    "pendingTransactionId": null,
    "transactionTags": [],
    "fileRecords": []
  }
]

Get aggregated transactions

Get aggregated transactions. This endpoint aggregates transactions and performs addition on the aggregated transaction amounts.

Query String Attributes

aggregateBy

array of enums

Fields to aggregate account balances by, must be an array of one of day, week, Month, Year

aggregateFn

enum

Function to use on aggregation, only sum supported for now.

currencyCode

nullable enum

Currency code to convert transaction amounts to.

filters

nullable object

Apply filters to the list of account balances.

id

nullable string

Filter transactions by a transaction ID.

ids

nullable array of strings

Filter transactions by multiple transaction IDs.

accountId

nullable string

Filter transactions by an account ID.

accountIds

nullable array of strings

Filter transactions by account IDs.

transactionCategoryIds

nullable array of strings

Filter transactions by transaction category IDs.

search

nullable string

Search param which does a wildcard search on the transaction description and merchant name.

fromDate

nullable string

Filter transactions from a date.

toDate

nullable string

Filter transactions up to a date.

needsReview

nullable boolean

Filter transactions which need review or not.

transactionTypes

nullable array of enums

Filter transactions based on whether they are a debit/withdrawal or credit/deposit. Must be an array of debit or credit.

amountGte

nullable number

Filter transactions which have an amount greater than or equal to a value.

amountLte

nullable number

Filter transactions which have an amount less than or equal to a value.

excludeParentTransactions

nullable boolean

Exclude transactions which are parent transactions of transactions which have been split.

excludeTransfers

nullable boolean

Exclude transactions which are marked as transfers.

excludeArchived

nullable boolean

Exclude transactions which are archived.

excludeExcludedTransactions

nullable boolean

Exclude transactions from accounts which are configured to have their transactions ignored/excluded.

pagination

nullable object

Pagination options.

pageNumber

nullable number

Page number to fetch, defaults to 1.

pageSize

nullable number

Number of items per page to fetch, defaults to 100.

GET /transactions/aggregated3

import axios from 'axios'

const response = await axios({
  method: 'get',
  url: 'https://api.finwiseapp.io/transactions/aggregated3?aggregateBy[]=day&aggregateFn=sum&filters={"accountId":"f472696c-47ac-4873-98cf-2a1069a1cf45"}',
  headers: {
    'Content-Type': 'application/json',
    Authorization: '<YOUR_API_KEY>',
  },
})

RESPONSE

[
  {
    "date": "2024-01-08T23:00:00.000Z",
    "amount": -80.37651341559103
  },
  {
    "date": "2024-01-09T23:00:00.000Z",
    "amount": -62.46209622712878
  },
  {
    "date": "2024-01-10T23:00:00.000Z",
    "amount": -22.28458543432253
  },
  {
    "date": "2024-01-11T23:00:00.000Z",
    "amount": -296.1955162572017
  },
  {
    "date": "2024-01-12T23:00:00.000Z",
    "amount": -165.1051224018331
  },
  {
    "date": "2024-01-13T23:00:00.000Z",
    "amount": -37.610702462416654
  },
  {
    "date": "2024-01-15T23:00:00.000Z",
    "amount": -163.1581579860514
  },
  {
    "date": "2024-01-16T23:00:00.000Z",
    "amount": 1911.8575115118058
  }
]

Archive a transaction

Archive a transaction.

POST /transactions/:id/archive

import axios from 'axios'

const response = await axios({
  method: 'post',
  url: 'https://api.finwiseapp.io/transactions/9da3aab1-be6c-4e6a-9b03-fd50e9aca541/archive',
  headers: {
    'Content-Type': 'application/json',
    Authorization: '<YOUR_API_KEY>',
  },
})

RESPONSE

{
  "id": "9da3aab1-be6c-4e6a-9b03-fd50e9aca541",
  "createdAt": "2024-05-01T14:18:22.304Z",
  "updatedAt": "2024-05-01T14:18:22.304Z",
  "description": "Walmart",
  "originalDescription": "Walmart",
  "accountId": "94d2f962-d4e3-4c99-ab47-8c941cea012a",
  "amount": {
    "amount": -56,
    "currencyCode": "USD"
  },
  "date": "2024-05-01T14:18:02.744Z",
  "transactionCategoryId": "a00cb43b-ab06-447c-8aeb-527680b20a50",
  "originalTransactionCategoryId": "a00cb43b-ab06-447c-8aeb-527680b20a50",
  "merchantId": "d4dd1cbe-d349-4089-ad63-b98921426656",
  "originalMerchantId": "d4dd1cbe-d349-4089-ad63-b98921426656",
  "parentTransactionId": null,
  "splits": null,
  "isManual": true,
  "isTransfer": null,
  "notes": null,
  "userId": "f472696c-47ac-4873-98cf-2a1069a1cf45",
  "archivedAt": "2024-04-29T00:03:34",
  "effectiveDate": null,
  "dataImportId": null,
  "needsReview": null,
  "isPending": null,
  "pendingTransactionId": null,
  "transactionTags": [],
  "fileRecords": []
}

Transaction Categories

This object represents a transaction category.

ENDPOINTS

POST /transaction-categories Create a transaction category
GET /transaction-categories Get a list of transaction categories
DELETE /transaction-categories/:id Delete a transaction category

The transaction category object

Attributes

id

string

Unique identifier for the transaction category.

createdAt

string

Date the transaction category was created.

updatedAt

string

Date the transaction category was last updated.

name

string

Name of the category

color

string

Color for the category, in hex format.

emoji

string

Emoji for the category, in hex format.

userId

string

Unique identifier of the user who owns the account.

transactionCategoryGroupId

string

Unique identifier of the transaction category group that this category belongs to.

markTransactionsAsTransfers

boolean

Whether transactions in this category should be marked as transfers.

excludeTransactionsFromBudget

boolean

Whether transactions in this category should be excluded from the budget and income and expenses.

consolidateInBudget

boolean

Whether this category should have debits and credits consolidated in the budget.

enableRollover

boolean

Whether budget rollover for this category is enabled or not.

rolloverFromDate

string

Date to count budget rollover from.

THE TRANSACTION CATEGORY OBJECT

{
  "id": "a00cb43b-ab06-447c-8aeb-527680b20a50",
  "createdAt": "2024-05-01T09:15:16.817Z",
  "updatedAt": "2024-05-01T09:15:16.817Z",
  "name": "Groceries",
  "userId": "f472696c-47ac-4873-98cf-2a1069a1cf45",
  "transactionCategoryGroupId": null,
  "color": null,
  "emoji": "🥙",
  "markTransactionsAsTransfers": null,
  "excludeTransactionsFromBudget": null,
  "consolidateInBudget": null,
  "enableRollover": null,
  "rolloverFromDate": null
}

Create a transaction category

Create a transaction category.

Request Body Attributes

id

string

Unique identifier for the transaction category.

createdAt

string

Date the transaction category was created.

updatedAt

string

Date the transaction category was last updated.

name

string

Name of the category

color

string

Color for the category, in hex format.

emoji

string

Emoji for the category, in hex format.

userId

string

Unique identifier of the user who owns the account.

transactionCategoryGroupId

string

Unique identifier of the transaction category group that this category belongs to.

markTransactionsAsTransfers

boolean

Whether transactions in this category should be marked as transfers.

excludeTransactionsFromBudget

boolean

Whether transactions in this category should be excluded from the budget and income and expenses.

consolidateInBudget

boolean

Whether this category should have debits and credits consolidated in the budget.

enableRollover

boolean

Whether budget rollover for this category is enabled or not.

rolloverFromDate

string

Date to count budget rollover from.

POST /transaction-categories

import axios from 'axios'

const response = await axios({
  method: 'post',
  url: 'https://api.finwiseapp.io/transaction-categories',
  headers: {
    'Content-Type': 'application/json',
    Authorization: '<YOUR_API_KEY>',
  },
  body: {
    "name": "Groceries",
    "emoji": "🥙",
  }
})

RESPONSE

{
  "id": "a00cb43b-ab06-447c-8aeb-527680b20a50",
  "createdAt": "2024-05-01T09:15:16.817Z",
  "updatedAt": "2024-05-01T09:15:16.817Z",
  "name": "Groceries",
  "userId": "f472696c-47ac-4873-98cf-2a1069a1cf45",
  "transactionCategoryGroupId": null,
  "color": null,
  "emoji": "🥙",
  "markTransactionsAsTransfers": null,
  "excludeTransactionsFromBudget": null,
  "consolidateInBudget": null,
  "enableRollover": null,
  "rolloverFromDate": null
}

Get transaction categories

Get transaction categories.

Query String Attributes

filters

nullable object

Apply filters to the list of transaction categories.

id

nullable string

Filter transactions by a transaction category ID.

userId

nullable string

Filter categories by user ID.

name

nullable string

Filter categories by name.

transactionCategoryGroupIds

nullable array of strings

Filter categories by transaction category group IDs.

pagination

nullable object

Pagination options.

pageNumber

nullable number

Page number to fetch, defaults to 1.

pageSize

nullable number

Number of items per page to fetch, defaults to 100.

GET /transaction-categories

import axios from 'axios'

const response = await axios({
  method: 'get',
  url: 'https://api.finwiseapp.io/transaction-categories?filters={"userId":"f472696c-47ac-4873-98cf-2a1069a1cf45"}',
  headers: {
    'Content-Type': 'application/json',
    Authorization: '<YOUR_API_KEY>',
  },
})

RESPONSE

[
  {
    "id": "a00cb43b-ab06-447c-8aeb-527680b20a50",
    "createdAt": "2024-05-01T09:15:16.817Z",
    "updatedAt": "2024-05-01T09:15:16.817Z",
    "name": "Groceries",
    "userId": "f472696c-47ac-4873-98cf-2a1069a1cf45",
    "transactionCategoryGroupId": null,
    "color": null,
    "emoji": "🥙",
    "markTransactionsAsTransfers": null,
    "excludeTransactionsFromBudget": null,
    "consolidateInBudget": null,
    "enableRollover": null,
    "rolloverFromDate": null
  }
]

Delete a transaction category

Delete a transaction category.

Request Body Attributes

reassignToTransactionCategoryId

string

Reassign transactions to this category ID.

DELETE /transaction-categories/:id

import axios from 'axios'

const response = await axios({
  method: 'delete',
  url: 'https://api.finwiseapp.io/transaction-categories/a00cb43b-ab06-447c-8aeb-527680b20a50',
  headers: {
    'Content-Type': 'application/json',
    Authorization: '<YOUR_API_KEY>',
  },
  body: {
    "reassignToTransactionCategoryId": "f904a437-5080-4d8b-b961-5c6e84623701",
  }
})

RESPONSE

{
  "id": "a00cb43b-ab06-447c-8aeb-527680b20a50",
  "createdAt": "2024-05-01T09:15:16.817Z",
  "updatedAt": "2024-05-01T09:15:16.817Z",
  "name": "Groceries",
  "userId": "f472696c-47ac-4873-98cf-2a1069a1cf45",
  "transactionCategoryGroupId": null,
  "color": null,
  "emoji": "🥙",
  "markTransactionsAsTransfers": null,
  "excludeTransactionsFromBudget": null,
  "consolidateInBudget": null,
  "enableRollover": null,
  "rolloverFromDate": null,
  "archivedAt": "2024-04-29T00:03:34"
}

200	OK	Everything worked as expected.
400	Bad Request	The request was unacceptable, often due to missing a required parameter.
401	Unauthorized	No valid API key provided.
402	Request Failed	The parameters were valid but the request failed.
403	Forbidden	The API key doesn’t have permissions to perform the request.
404	Not Found	The requested resource doesn’t exist.
409	Conflict	The request conflicts with another request.
429	Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
5xx	Server Errors	Something went wrong on FinWise’s end. (These are rare.)

POST	/accounts	Create a new account
PATCH	/accounts/:id	Update an account
GET	/accounts	Get a list of accounts
GET	/accounts/:id	Get an account

POST	/account-balances	Create an account balance
GET	/account-balances	Get a list of account balances
GET	/account-balances/aggregated2	Get aggregate account balances
POST	/account-balances/:id/archive	Archive an account balance

POST	/transactions	Create a transaction
GET	/transactions	Get a list of transactions
GET	/transactions/aggregated3	Get aggregated transactions
POST	/transactions/:id/archive	Archive a transaction

POST	/transaction-categories	Create a transaction category
GET	/transaction-categories	Get a list of transaction categories
DELETE	/transaction-categories/:id	Delete a transaction category