NAV Navbar
Examples

General

Introduction

Welcome to the Tink API reference! Tink makes technology that gives financial businesses and customers greater understanding and power over their money. We combine smart data collection and analytics to create rich insights that users can act on. We welcome developers to dive in and start making game-changing new apps, tools and sites using our simple API. This document explains how to work with our API and describes the data that you can access with it.

Before you start working with the Tink API, you must acquire the appropriate credentials as an API customer in order to access the full set of functionality. These credentials provide different levels of permissions, which determines what type of information that can be shared with you. You can read more here.

Message formats

The Tink API is designed around REST at its core, and uses standard HTTP verbs and status codes to communicate requests and response statuses. For the JSON encoded data, properties use camel-case and enum-like string properties have capitalized property values.

String properties are encoded using UTF-8, and date long properties are represented by UNIX Epoch time in milliseconds.

Versioning

The Tink API is versioned using a version identifier in the endpoint URI. The current version of the API is v1 and we expect this to be the case for the foreseeable future. New properties and data models are continuously added to the v1 API, but it will remain backwards compatible with this specification until deprecated.

Please note that obsolete fields that are not listed in this documentation can be present on some of the responses received from the Tink API. These obsolete fields are artifacts of pre-production data models and any API customer should account for the fact that unknown properties can be present.

Status Codes

When doing an HTTP request to the Tink API you will receive an HTTP status code in the server response.

You can expect these ranges of status codes:

Code Range Description
2xx Status codes indicating successfull requests.
4xx The data sent from the client was not sent in a way the Tink servers expects.
5xx An error happend in one of Tink's servers.

Each of the services may list explicit status codes.

Periods

A lot of the data served by the Tink API derived from the either transactional or otherwise date-based information, is in various forms periodized into pre-computed date-based buckets for easy access. Statistics are computed for YEARLY, MONTHLY and MONTHLY_ADJUSTED buckets, which represents different time periods.

As exemplified to the right, most of this is self explanatory, except for MONTHLY_ADJUSTED. The MONTHLY_ADJUSTED buckets adjust for the fact that in many markets, people relate to their financials based on when they receive their salary. Using Sweden as an example, salary is received on the 25th of each month, and using MONTHLY_ADJUSTED each month in Tink includes transactional data from an adjacent calendar month, covering the entire salary cycle.

The MONTHLY_ADJUSTED buckets also account for the fact that salaries are not expedited on non-business days, so if the 25th of a specific month happens to be a Saturday, the period is adjusted to start of on Friday the 24th of the same month instead.

Example

Resolution Period Start date End date
YEARLY 2015 2015-01-01 2015-12-31
MONTHLY 2015-04 2015-04-01 2015-04-31
MONTHLY_ADJUSTED 2015-04 2015-03-25 2015-04-24
DAILY 2015-04-01 2015-04-01 2015-04-01

Categories

The categories that are available for the user to categorize her transactions with, while structurally being a category tree, are available as a flat list of categories with parent/child relationships using their id and parent fields.

Category information is used for the pre-computed statistics, making aggregated spending and income data available for all the different nodes in the category tree. However, a transaction itself, can only be assigned to a leaf category.

Both the INCOME and EXPENSES categories represents users' regular income and spending, while the TRANSFER categories are special in the sense that they represent transfers between accounts (potentially across banks), such as regular bank transfers, credit-card payments, mortgage amortizations and other transactions that should not add to the users' actual spending.

User

The user model represents a unique Tink end-user and includes properties that defines the user, user profile information and user-modifiable settings. The user information can primarily be used whenever a Tink user signs up for a 3rd party service using her Tink account, or when user-modifiable settings, such as locale or currency, are needed in order to display or calculate the correct data in the 3rd party service.

Providers

The provider object is the representation used for financial institutes (banks, credit card institutes, etc.).

Capabilities

The provider of Handelsbanken

{
  "capabilities": ["CHECKING_ACCOUNTS", "SAVINGS_ACCOUNTS", "PAYMENTS"],
  "credentialsType": "MOBILE_BANKID",
  "currency": "SEK",
  "displayDescription": "Mobilt BankID",
  "displayName": "Handelsbanken",
  "fields": ["..."],
  "...": "...",
}

Provider capabilities are a guarantee that the logic to fetch this data has been implemented. The capabilities are available through all /api/v1/providers endpoints as the field capabilities in the JSON response. The available capabilities can be seen below.

Even though a capability is available, there could be cases where the data cannot be refreshed, i.e. there is a problem at the providers api.

Capability Description
CHECKING_ACCOUNTS Implemented logic to fetch checking accounts for this provider.
SAVINGS_ACCOUNTS Implemented logic to fetch savings accounts for this provider.
CREDIT_CARDS Implemented logic to fetch credit cards for this provider.
INVESTMENTS Implemented logic to fetch investments for this provider.
LOANS Implemented logic to fetch loans for this provider.
PAYMENTS Implemented logic to execute payments for this provider.

Credentials

The Provider of Handelsbanken

{
  "name": "handelsbanken-bankid",
  "status": "ENABLED",
  "credentialsType": "MOBILE_BANKID",
  "displayName": "Handelsbanken",
  "fields": [{
    "name": "username",
    "description": "Personnummer",
    "minLength": 12,
    "maxLength": 12,
    "optional": false,
    "...": "..."
  }]
}

POST /api/v1/credentials

{
  "providerName": "handelsbanken-bankid",
  "fields": {
    "username": "198709230000"
  }
}

The credentials object represents the user's connection towards the Provider (most commonly a "bank connection"). The credentials, as it's name implies, holds the information that is required when authenticating towards the Provider.

Adding Credentials to a User

When adding credentials to a User, one POSTs an object with providerName and the fields found on the corresponding Provider. In the handelsbanken-bankid example, there is only one required field. The fields parameter is a key/value map build up of field name as key and the value the user provided for this particular field.

When POSTing this object to /api/v1/credentials, it automatically starts a "refresh" of data towards the specified Provider.

Credentials Status

GET /api/v1/credentials/{id}

{
  "providerName": "handelsbanken-bankid",
  "fields": {
    "username": "198709230000"
  },
  "status": "AUTHENTICATING",
  "statusUpdated": 1500000000000,
  "updated": null
}

A simple example of a CredentialsController

module.exports = function(callbacks) {

  this.callbacks = callbacks;
  this.stopped = false;

  function onUpdatedCredentials(newCredentials) {

    if (this.stopped) {
      return;
    }

    this.credentials = newCredentials;

    switch(this.credentials.status) {
      case 'AWAITING_MOBILE_BANKID_AUTHENTICATION':
        this.callbacks.onAwaitingMobileBankId(this.credentials);
        break;
      case 'AWAITING_SUPPLEMENTAL_INFORMATION':
        this.callbacks.onAwaitingSupplementalInfo(this.credentials);
        break;
      case 'UPDATING':
        this.callbacks.onUpdating(this.credentials);
        break;
      case 'UPDATED':
        this.callbacks.onUpdated(this.credentials);
        break;
      case 'AUTHENTICATION_ERROR':
      case 'TEMPORARY_ERROR':
        this.callbacks.onError(this.credentials);
        break;
      default:
        //Do nothing
        break;
    }
  }

  function onCredentialsResponse(newCredentials) {
    var newStatusUpdated = newCredentials.statusUpdated;
    var prevStatusUpdated = this.credentials.statusUpdated;

    if ((!prevStatusUpdated && newStatusUpdated) || (newStatusUpdated > prevStatusUpdated)) {
      onUpdatedCredentials.call(this, newCredentials);
    }
  }

  this.startAuthentication = function(credentials) {
    this.stopped = false;
    this.credentials = credentials;

    this.intervalRef = setInterval(function() {
      // callback on onCredentialsResponse with new response
      CredentialsService.fetch(this.credentials.getId(), onCredentialsResponse);
    }.bind(this), 1000);
  };

  this.stop = function() {
    this.stopped = true;

    if (this.intervalRef) {
      clearInterval(this.intervalRef);
    }
  };
}

During the refresh of data from a Provider, different statuses can occur. The general idea is that the client should act upon the status if the timestamp statusUpdated is greater than what the client previously had. Updates to credentials can be listened by simply polling the endpoint GET /api/v1/credentials/{id}.

Status Description
CREATED Initial status
AUTHENTICATING When starting the authentication process
AWAITING_MOBILE_BANKID_AUTHENTICATION Trigger for client to prompt the user to open Mobile BankID (Swedish out-of-band authentication app). See information about autostart token below.
AWAITING_SUPPLEMENTAL_INFORMATION Trigger for the client to prompt the user to fill out supplemental information. The fields can be found on credentials parameter supplementalInformation.
AWAITING_THIRD_PARTY_APP_AUTHENTICATION Trigger for the client to prompt the user to open the third party authentication flow (app, web page, etc). See more details below: How to handle AWAITING_THIRD_PARTY_APP_AUTHENTICATION
UPDATING User has been successfully authenticated, now downloading data.
UPDATED Final state: Refresh was successful and data downloaded.
AUTHENTICATION_ERROR Final state: Error during authentication, typically due to bad input. Requires user input to refresh again.
TEMPORARY_ERROR Final state of current refresh. A temporary error occurred when refreshing data, most typically due to some issue on the Provider's side. This error state does not require user input to try again.

Swedish Mobile BankID with Autostart token

Some Swedish providers with credentials type MOBILE_BANKID uses autostart token. The autostart token will be provided as supplemental information. If the credentials status is AWAITING_MOBILE_BANKID_AUTHENTICATION and the supplemental information is not null, the supplemental information is the autostart token. The autostart token will be in the format of a UUID and should be inputted in a deeplink. The deeplink needs to be generated by the client.

The deeplink should have the following format: bankid:///?autostarttoken=[TOKEN]&redirect=[RETURNURL] The preferred way in iOS is the following format: https://app.bankid.com/?autostarttoken=[TOKEN]&redirect=[RETURNURL]

The RETURNURL is a deeplink back to your application. On iOS the RETURNURL must have a value. For all other devices the redirect can be either empty redirect= or null (redirect=null).

For more information see Chapter 3 in BankID Relying part guidelines

How to handle AWAITING_THIRD_PARTY_APP_AUTHENTICATION

If a provider is using third party services in their authentication flow, the client should expect the AWAITING_THIRD_PARTY_APP_AUTHENTICATION status on the credentials object. In order for the aggregation of data to be successful, the system expects the third party authentication flow to be successful as well.

Information about the third party authentication flow can be found in the supplementalInformation parameter, which contains a serialized ThirdPartyAppAuthenticationPayload object.

The ThirdPartyAppAuthenticationPayload contains specific deeplink urls and configuration for each platform (iOS, android).

A simple example of a ThirdPartyAppAuthenticationPayload

{ "android": { "packageName": "...", "requiredMinimumVersion": "...", "intent": "..." }, "ios": { "appStoreUrl": "...", "scheme": "...", "deepLinkUrl": "..." }, "downloadTitle": "...", "downloadMessage": "...", "upgradeTitle": "...", "upgradeMessage": "...", }

Clients dealing with markets outside of Sweden are expected to handle the AWAITING_THIRD_PARTY_APP_AUTHENTICATION status on authentication flows.

Moving on the status AWAITING_MOBILE_BANKID_AUTHENTICATION, used in Sweden, will be deprecated, and the AWAITING_THIRD_PARTY_APP_AUTHENTICATION is going to be used instead. In this case the deeplinks will contain the necessary information to start the bankid app (e.g. autostart token).

Account

When a credentials connection is successfully established, all supported accounts from the financial institution are aggregated and made available in the Tink API.

Opt-in feature (contact us to enable this feature)

Everything described in this part assumes that the Opt-in feature has been enabled.

This feature will give the users a change to choose what accounts they want us to fetch data for. Only accounts that the users has opted in for will be available. Also refreshes will only refresh data for accounts that a users has opted in for.

Create

When creating credentials, the user's input of what accounts to opt-in for is required. This will be notified to the client by the credentials status AWAITING_SUPPLEMENTAL_INFORMATION with the account information available on the credentials parameter supplementalInformation. When the supplemental information has been supplied a refresh of the opted in accounts will be done.

An example of a credentials response with supplemental information for Opt-in

{
  "providerLatency" : 0,
  "id" : "e6d7de4350b54f83a7ccf261e3ae5b5f",
  "providerName" : "handelsbanken-bankid",
  "status" : "AWAITING_SUPPLEMENTAL_INFORMATION",
  "statusUpdated" : 1539691829369,
  "supplementalInformation" : "[{\"description\":\"9999-444444444444 ISK\",\"helpText\":null,\"hint\":null,\"immutable\":false,\"masked\":false,\"maxLength\":null,\"minLength\":null,\"name\":\"9999-444444444444\",\"numeric\":false,\"optional\":false,\"pattern\":\"true/false\",\"patternError\":null,\"value\":\"false\",\"sensitive\":false,\"checkbox\":true,\"additionalInfo\":\"{\\\"accountName\\\":\\\"ISK\\\",\\\"accountType\\\":\\\"INVESTMENT\\\",\\\"balance\\\":123456.0,\\\"holderName\\\":null,\\\"iban\\\":null,\\\"portfolioTypes\\\":[\\\"ISK\\\"]}\"},{\"description\":\"9999-222222222222 Sparkonto\",\"helpText\":null,\"hint\":null,\"immutable\":false,\"masked\":false,\"maxLength\":null,\"minLength\":null,\"name\":\"9999-222222222222\",\"numeric\":false,\"optional\":false,\"pattern\":\"true/false\",\"patternError\":null,\"value\":\"false\",\"sensitive\":false,\"checkbox\":true,\"additionalInfo\":\"{\\\"accountName\\\":\\\"Sparkonto\\\",\\\"accountType\\\":\\\"SAVINGS\\\",\\\"balance\\\":385245.33,\\\"holderName\\\":null,\\\"iban\\\":null}\"},{\"description\":\"9999-333333333333 Bolån\",\"helpText\":null,\"hint\":null,\"immutable\":false,\"masked\":false,\"maxLength\":null,\"minLength\":null,\"name\":\"9999-333333333333\",\"numeric\":false,\"optional\":false,\"pattern\":\"true/false\",\"patternError\":null,\"value\":\"false\",\"sensitive\":false,\"checkbox\":true,\"additionalInfo\":\"{\\\"accountName\\\":\\\"Bolån\\\",\\\"accountType\\\":\\\"LOAN\\\",\\\"balance\\\":-2300000.0,\\\"holderName\\\":null,\\\"iban\\\":null}\"},{\"description\":\"9999-111111111111 Transaktionskonto\",\"helpText\":null,\"hint\":null,\"immutable\":false,\"masked\":false,\"maxLength\":null,\"minLength\":null,\"name\":\"9999-111111111111\",\"numeric\":false,\"optional\":false,\"pattern\":\"true/false\",\"patternError\":null,\"value\":\"false\",\"sensitive\":false,\"checkbox\":true,\"additionalInfo\":\"{\\\"accountName\\\":\\\"Transaktionskonto\\\",\\\"accountType\\\":\\\"CHECKING\\\",\\\"balance\\\":26245.33,\\\"holderName\\\":null,\\\"iban\\\":null}\"}]",
  "type" : "MOBILE_BANKID",
  "userId" : "965ec63c8b5a4743914788f6cafcc564",
  "fields" : {
    "username" : "201212121212"
  },
  "username" : "201212121212",
  "sensitivePayload" : { }
}

Refresh

When doing a refresh only the opted in accounts will be refreshed.

To change what accounts that are opted in the client can trigger a refresh with a query parameter optIn=true. All available accounts will be supplied with supplemental information on the credentials object. The accounts that are already opted in will have value: true, all other accounts will have value: false. When opting in for accounts the backend expects the full new state (no patching). This means that the opted in accounts after the change has been done will be the ones that had value: true in the supplemental information request.

To provide the client with more information about the accounts a serialized JSON object is available on the field additionalInfo.

Key Description
accountName The name of the account.
accountType The account type Tink have set on the account (CHECKING, SAVINGS, INVESTMENT, MORTGAGE, CREDIT_CARD, LOAN, PENSION)
balance The current balance of the account.
holderName The name of the account owner.
iban The international bank account number of the account.
portfolioTypes The types of portfolio an investment account have (ISK, KF, DEPOT, PENSION, OTHER). Present only when the account type is INVESTMENT.

Transaction

An account usually contains multiple transactions (except for certain types of accounts where Tink can't access the underlying transactions, for example, certain INVESTMENT accounts). The transaction model represents any operation on an account, and could represent both the actual credit-card purchase on a CREDIT_CARD account, but also represent the transaction when you paid your credit-card bill. Most commonly, the transactions in an account should represent what the end-user typically regards as a transaction with its amount, description and date, etc.

The payload property can include arbitrary metadata which provided by the financial institution in question that can be used either for deep-linking back to the financial institution's app, for displaying additional information about the transaction, or for backend purposes such as automatic categorization improvement, etc. It can also include metadata generated by Tink, for example transfer transactions that are automatically flagged as transfers based on the identification of the corresponding transaction on the other account and which includes the primary identifier of the peer transaction for easy access.

Searching for Transaction

In the Tink Platform, you either GET one transaction or you Search for Transactions. The Search Service handles querying on multiple parameters as can be seen by the endpoint in the API reference. However, there are also parameters that are parsed from the free text (queryString). All the commands below is typically applied per word in the query and if multiple commands are found, they are concatenated to the Search with AND (OR does not exist).

Query String commands

Type Description Keywords
Tags Searches specifically for transactions with tags. Words starting with '#'.
Amount Span  Searches for transactions within the given amount span. Keywords here depend on the locality of the user. over, under, more than, less than, around
Date/Time Span  Searches for transactions within the given date/time span. Keywords here depend on the locality of the user. weekdays, weekends, today, yesterday, this week/month/year, last week/month/year, week #.
Category Searches specifically for transactions with the specified category. Keywords here depend on the locality of the user. Restaurant, Bar

Statistics

By querying the statistics endpoint, an API customer can select the specific types of data to access. The query should be posted in the request body and you can specify any of the properties available to filter the result set. Defining multiple properties will yield an AND operation, and specifying multiple values of a property will yield an OR operation.

Statistics types

Type description value Description Available resolutions
balances-by-account Primary identifier of an account Balances over time by each account MONTHLY MONTHLY_ADJUSTED
balances-by-account-type-group The type group name Balances over time by each account group MONTHLY MONTHLY_ADJUSTED
expenses-by-category Primary identifier of a category Sum of expenses per period in each category MONTHLY MONTHLY_ADJUSTED YEARLY DAILY WEEKLY
expenses-by-category/by-count Primary identifier of a category Count of expenses per period in each category MONTHLY MONTHLY_ADJUSTED DAILY WEEKLY
income-by-category Primary identifier of a category Sum of Incomes per period in each category MONTHLY MONTHLY_ADJUSTED
income-and-expenses Sum of transactions per period for category type MONTHLY MONTHLY_ADJUSTED YEARLY
left-to-spend The date Takes income minus expenses over time MONTHLY MONTHLY_ADJUSTED
left-to-spend-average The date Average income minus expenses over 6 months MONTHLY MONTHLY_ADJUSTED

Testing Account Aggregation

The Tink Test Providers are static implementations of providers and banks that allow developers to test Tink, without having to enter real bank credentials. Creating credentials with a provider of type: TEST will still utilize all the flows in the Tink ecosystem, but without communicating with an actual provider or bank. There are multiple providers of type: TEST that will emulate different authentication flows and types of data. In order to fetch the test providers through the providers endpoints you would need to add the includeTestProviders=true query parameter. This query parameter will add the test providers in the original provider response, based on your criteria. In case you want to see only test provider configuration, you can add the following query parameters excludeNonTestProviders=true&includeTestProviders=true. You can find more about the test providers here.

Example of a Test Provider

{
    "accessType": "OTHER",
    "capabilities": [
        "LOANS",
        "SAVINGS_ACCOUNTS",
        "INVESTMENTS",
        "CREDIT_CARDS"
    ],
    "credentialsType": "THIRD_PARTY_APP",
    "currency": "SEK",
    "displayName": "Demo Unregulated Third party (successful)",
    "displayDescription": "Third party app",
    "fields": [
        {
            "description": "Username",
            "exposed": true,
            "immutable": true,
            "masked": false,
            "name": "username",
            "numeric": false,
            "optional": false,
            "sensitive": false,
            "checkbox": false,
        }
    ],
    "financialInstituteId": "f128639c-171b-46eb-8eff-219705bcbbcc",
    "financialInstituteName": "Demo",
    "groupDisplayName": "Demo providers",
    "market": "SE",
    "multiFactor": true,
    "name": "se-test-other-third-party-app-successful",
    "passwordHelpText": "To connect your bank, you need to identify yourself using a third party app.",
    "popular": false,
    "status": "ENABLED",
    "transactional": true,
    "type": "TEST"
}
Test Provider Description Capabilities
se-test-open-banking-embedded Requries the user to enter test-credentials in the form of a username and a password. CHECKING_ACCOUNTS
se-test-open-banking-decoupled-successful Will authenticate successful for the correct username. CHECKING_ACCOUNTS
se-test-open-banking-redirect Will run the flow of redirect authentication. CHECKING_ACCOUNTS
se-test-other-password Requries the user to enter test-credentials in the form of a username and a password. SAVINGS_ACCOUNTS, CREDIT_CARDS, LOANS, INVESTMENTS
se-test-other-bankid-successful Will authenticate successful for the correct username. SAVINGS_ACCOUNTS, CREDIT_CARDS, LOANS, INVESTMENTS
se-test-other-bankid-failing-cancelled Will allways fail to authenticate, mimicing the flow when a user cancels the BankID authentication. SAVINGS_ACCOUNTS, CREDIT_CARDS, LOANS, INVESTMENTS
se-test-other-bankid-failing-inprogress Will allways fail to authenticate, mimicing the flow when a user initiates two BankID authentications at the same time. SAVINGS_ACCOUNTS, CREDIT_CARDS, LOANS, INVESTMENTS
se-test-other-bankid-failing-timeout Will allways fail to authenticate, mimicing the flow when the BankID authentication times out. SAVINGS_ACCOUNTS, CREDIT_CARDS, LOANS, INVESTMENTS
se-test-other-multi-supplemental Scenario of an external authentication system, where two separate codes are entered into the system. SAVINGS_ACCOUNTS, CREDIT_CARDS, LOANS, INVESTMENTS
se-test-other-third-party-app-successful Will authenticate successful for the correct username. SAVINGS_ACCOUNTS, CREDIT_CARDS, LOANS, INVESTMENTS
se-test-other-third-party-app-failing-cancelled Will allways fail to authenticate, mimicing the flow when a user cancels the third party app authentication. SAVINGS_ACCOUNTS, CREDIT_CARDS, LOANS, INVESTMENTS
se-test-other-third-party-app-failing-inprogress Will allways fail to authenticate, mimicing the flow when a user initiates two third party app authentications at the same time. SAVINGS_ACCOUNTS, CREDIT_CARDS, LOANS, INVESTMENTS
se-test-other-third-party-app-failing-timeout Will allways fail to authenticate, mimicing the flow when the third party app authentication times out. CHECKING_ACCOUNTS, SAVINGS_ACCOUNTS, CREDIT_CARDS, LOANS, INVESTMENTS
<market>-test-password Requries the user to enter test-credentials in the form of a username and a password. CHECKING_ACCOUNTS, SAVINGS_ACCOUNTS, CREDIT_CARDS, LOANS, INVESTMENTS
<market>-test-multi-supplemental Scenario of an external authentication system, where two separate codes are entered into the system. CHECKING_ACCOUNTS, SAVINGS_ACCOUNTS, CREDIT_CARDS, LOANS, INVESTMENTS
se-test-bankid-successful Will authenticate successful for the correct username. CHECKING_ACCOUNTS, SAVINGS_ACCOUNTS, CREDIT_CARDS, LOANS, INVESTMENTS
se-test-bankid-failing Will allways fail to authenticate. CHECKING_ACCOUNTS, SAVINGS_ACCOUNTS, CREDIT_CARDS, LOANS, INVESTMENTS

During a refresh on a TEST provider, data will be refreshed for: CHECKING, SAVINGS, INVESTMENT, MORTGAGE, LOAN. Demo data will be generated and refreshed by the Tink platform.

To authenticate with the test credentials, populate the fields parameter in the request body. You can read more about the fields here. Furthermore, the test-multi-supplemental provider requires additional supplemental information to authenticate. You can find more information of how to authenticate with supplemental information here.

Provider Name Username Password Supplemental Comments
se-test-open-banking-embedded tink, tink2, tink3 tink-1234, tink-2345, tink-3456 - There are three available credentials to test with; tink, tink2, and tink3. The tink2 and tink3 credentials will only display test data for Savings accounts.
se-test-open-banking-decoupled-successful tink-demo-user - - -
se-test-other-password tink, tink2, tink3 tink-1234, tink-2345, tink-3456 - There are three available credentials to test with; tink, tink2, and tink3. The tink2 and tink3 credentials will only display test data for Savings and Checking accounts.
se-test-other-multi-supplemental tink-test - 1234, 4321 Add the first code for the first prompt, followed by the second code for the second prompt.
se-test-other-bankid-* 18001212XXXX - - This will always fail for the username that starts with 18001212, where XXXX can be any positive four digit integer
se-test-other-third-party-app-* tink-demo-user - - -
<market>-test-password tink, tink2, tink3 tink-1234, tink-2345, tink-3456 - There are three available credentials to test with; tink, tink2, and tink3. The tink2 and tink3 credentials will only display test data for Savings and Checking accounts.
<market>-test-multi-supplemental tink-test - 1234, 4321 Add the first code for the first prompt, followed by the second code for the second prompt.
se-test-bankid-failing 18001212XXXX - - This will always fail for the username that starts with 18001212, where XXXX can be any positive four digit integer
se-test-bankid-successful 18001212XXXX - - This will always succeed for the username that starts with 18001212, where XXXX can be any positive four digit integer

API access with OAuth2

API customers can get access to the Tink API by using the Tink Link app, which uses industry standard OAuth2 authentication methods for transparent and secure access to user data.

NOTE: this does not apply to Enterprise customers.

  1. The end user is taken to tink.se.
  2. The end user chooses a bank, accepts the given scope and authenticates.
  3. An access code is sent back to your application.
  4. With the code, your application can get an API access_token, and fetch the user's bank data from the Tink API.

Currently, end users' data is deleted after a short period of time (24 hours). Creating permanent users in our database is limited to our Enterprise customers, contact us to learn more about it.

Check out our example application at https://demo.tink.com. It's an example of how an API customer could integrate with the Tink API using the Tink Link app, in order to fetch some user bank data.

Permissions

Access to user data is controlled by using OAuth2 security scopes or permissions. Each API customer is configured to have a set of scopes which control the maximum permitted data access. For each end-user authorization process, a subset of those permissions can be requested for the user to authorize. For example, the full possible scope to request could be accounts:read,transactions:read, but for a specific authorization process, it's possible to only request accounts:read.

This setup provides a way for 3rd-party services to selectively request the right set of permissions from the user depending on the use case for the data. If an API customer has access to a broad set of permissions, it's highly recommended to be prudent in which permissions you actually request from the end-user.

Scope Description
user:read Access to user profile data such as e-mail, date of birth, etc.
credentials:read Access to the information describing the user's different bank credentials connected to Tink.
accounts:read Access to all the user's account information, including balances.
transactions:read Access to all the user's transactional data.
investments:read Access to the user's portfolios and underlying financial instruments.
statistics:read Access to all the user's statistics, which can include filters on statistic.type.
identity:read Access to the user's personal information that can be used for identification purposes.

Other non-public security scopes are available for specific partners.

You need an authorization link to be able to send users to Tink Link. To start the OAuth process, you can open the link in your browser. When you later build this into your application, you can simply add a button with this link which will redirect the user, or integrate Tink Link inside an iframe.

Required parameters:

Parameter Description
client_id Your OAuth client ID.
redirect_uri By default, you will have http://localhost:3000/callback as a valid redirect_uri. This is the path that will receive the code. NOTE: no other URI will work unless it's configured in our database, where you can have a set of accepted redirect URIs. For security reasons we require an exact match. To just test that everything works, you don't need to set up anything on this route, but you can of course do that. Also worth noting is that you must use https if using a redirect_uri that is not localhost due to security reasons.
scope The scope parameter can receive multiple scopes separated by a comma. For example: accounts:read,transactions:read,statistics:read,user:read.

Optional parameters:

Parameter Description
input_username If this is provided, the username field will be pre-filled. If not, the user can type it in. Providing this in the URL makes most sense if the username is a general username, valid for multiple banks. This could for example be a Personal Identification Number for a specific country or a Social Security Number.
input_provider The unique name of the provider (for example sbab-bankid). If this is provided, the provider will be chosen for the user. If not, the user can choose the provider in a list. If the given parameter is not a valid provider, the user will see an error screen, so make sure you have the correct provider name from this endpoint.
market If omitted, it will default to a default market. However, you can provide a market code here and the list of providers will show the available providers for that market. For example, &market=DK would show Danish providers. You can read more about the available markets here.
locale If omitted, the default locale will be used (en_US). We also support Swedish sv_SE.
state Optional, but highly recommended parameter that's useful in preventing Cross-site Request Forgery (CSRF) attacks. The application provides a randomised state value to Tink Link at initiation, and that value will be sent back verbatim to the callback URL after a successful grant. The application can then verify the returned value to make sure the request came from the application itself.
iframe Should be used if Tink Link is embedded inside an iframe. If the parameter is set to iframe=true, the redirect with the authentication code will be replaced by a postMessage to the parent. Note that iframe embedding is limited to our Premium customers. For more information, contact api-support@tink.se.

When you're done, your link will look something like this:

https://oauth.tink.se/0.4/authorize/?client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:3000/callback&scope=accounts:read,transactions:read,statistics:read,user:read

Note that you can add optional parameters here, such as market and locale. You can read more about how to get started with Tink Link here.

Authorization response

When the OAuth process is done, you will get a response with the result. This will either be a success or an error. The response will be delivered to the specified redirect_uri. For premium customers using iframe mode, the response will be delivered as a postMessage to the parent. The parameters will be sent in the url query.

Success Callback

Redirect mode

The following table describes the parameters in the success response when using redirect mode.

Parameter Description
code The authorization code to be exchanged for an access_token.

Example success response (redirect mode)

https://your-domain.com/oauth/callback?code=6915ab99857fec1e6f2f6c078

Iframe mode

The following table describes the parameters in the success response when using iframe mode.

Parameter Description
type The authorization code to be exchanged for an access_token. Will always be code
data The data that represents the type. Will always be the code.

Example success response (iframe mode)

{
    "type": "code",
    "data": "6915ab99857fec1e6f2f6c078"
}

Error Callback

Redirect mode

The following table describes the parameters in the error response when using redirect mode

Parameter Description
error An enumerable defined below in Error Statuses.
message A message for developers describing the error.
credentials ID for the credentials object. Only sent in an AUTHENTICATION_ERROR

Example error response (redirect mode)

https://your-domain.com/oauth/callback?error=USER_CANCELLED&message=The%20user%20cancelled%20the%20authentication

Iframe mode

The following table describes the parameters in the error response when using iframe mode

Parameter Description
type A type of error. One of error or Credentials
error The error object. Has parameters status, message and userMessage
data The data related to the error. The Credentials object in case of AUTHENTICATION_ERROR

Example error response (iframe mode)

{
    "type": "error",
    "error": {
        "status": "USER_CANCELLED",
        "message": "The user cancelled the authentication"
    }
}

Error Statuses

Status Description
BAD_REQUEST The authorization link was incorrectly configured.
USER_CANCELLED The user cancelled the authorization flow.
AUTHENTICATION_ERROR The end user was not successfully authenticated to its financial service. Further information will be given by the status and statusPayload of the Credentials object found in the data parameter.
INTERNAL_ERROR A temporary error within the Tink services. Please try again soon.

Exchange access tokens

Once you have received the authorization code in the redirect URI, you can use that code to exchange it for an access_token. This must be done using the client secret, which you received with your client_id.

POST /oauth/token (get access token)

$ curl -v -X POST https://api.tink.com/api/v1/oauth/token \
-d 'code=1a513b99126ade1e7718135019fd119a' \
-d 'client_id=YOUR_CLIENT_ID' \
-d 'client_secret=YOUR_CLIENT_SECRET' \
-d 'grant_type=authorization_code'

{
    "access_token": "78b0525677c7414e8b202c48be57f3da",
    "token_type": "bearer",
    "expires_in": 7200,
    "refresh_token": "33f10ce3cb1941b8a274af53da03f361",
    "scope": "accounts:read,statistics:read,transactions:read,user:read"
}

If you provided the correct code, client_id and secret, you should get a successful response with an access_token and a refresh_token.

If you get an error here, such as 401 Unauthorized, this could have multiple reasons. It could for example be an invalid secret or an expired code. The code is short-lived, so generate a new one and try again.

As hinted by the expiry time of the access token, access tokens can expire after a set amount of time. When an access token has expired, endpoints that require access tokens will respond with 401 Unauthorized. The access token will then need to be refreshed by the API customer for continued access. This is done with the refresh_token in a standard OAuth2 fashion using the same endpoint as used when exchanging the authorization code for an access token.

POST /oauth/token (refresh the token)

$ curl -v -X POST https://api.tink.com/api/v1/oauth/token \
-d 'refresh_token=33f10ce3cb1941b8a274af53da03f361' \
-d 'client_id=YOUR_CLIENT_ID' \
-d 'client_secret=YOUR_CLIENT_SECRET' \
-d 'grant_type=refresh_token'

You will then get a similar response as in the previous request.

NOTE: Since a user's data is only stored for 24 hours, an access_token can't be used to fetch the data when the data has been removed. Using a refresh_token won't help, since the data is gone from our systems. This means that a refresh_token is only valid during 24 hours after the initial authentication of a user.

Access user data

Once you have a valid access token, you can use that to access user data using the Tink API. The access token is used as a bearer token in the HTTP Authorization header, such as Authorization: Bearer <access token>. More information about how the Tink API works can be found in the API-reference section.

Since we requested an accounts:read scope, we should now be able to read the user's accounts.

GET /accounts/list (get the user's accounts)

$ curl -v https://api.tink.com/api/v1/accounts/list -H 'Authorization: Bearer 78b0525677c7414e8b202c48be57f3da'

You should then get a JSON response with an account list.

We also requested transactions:read and statistics:read. This means that you can also fetch transaction data and statistics data.

For more information about how to query data from our API, check the rest of the API documentation!

POST /statistics/query (get the user's statistics)

$ curl -v -X POST https://api.tink.com/api/v1/statistics/query \
-d '{"description": null, "padResultUntilToday": true, "resolution": "MONTHLY_ADJUSTED", "types": ["expenses-by-category"]}' \
-H "Content-Type: application/json" \
-H 'Authorization: Bearer 78b0525677c7414e8b202c48be57f3da' 

POST /search (get some transactions)

$ curl -v -X POST https://api.tink.com/api/v1/search \
-d '{"limit":10}' \
-H "Content-Type: application/json" \
-H 'Authorization: Bearer 78b0525677c7414e8b202c48be57f3da'

Error status codes

All endpoints that require a valid access token can respond with the following HTTP error status codes:

Status code Description
401 Possible reasons include missing Authorization: Bearer <access token> HTTP header and expired access token.
403 The access token is missing a required scope.

API Reference

Account

An account could either be a debit account, a credit card, a loan or mortgage.

Parameter Description
accountExclusion
type: string
required: true
Indicate features this account should be excluded from. Possible values are: NONE: No features are excluded from this account, PFM_DATA: Categorization and Personal Finance Management Features, like statistics and activities are excluded, PFM_AND_SEARCH: Categorization and Personal Finance Management Features are excluded, and transactions belonging to this account are not searchable. This is the equivalent of the, now deprecated, boolean flag 'excluded', AGGREGATION: No data will be aggregated for this account and, all data associated with the account is removed (except account name and account number). This property can be updated in a update account request.. Values: AGGREGATION, PFM_AND_SEARCH, PFM_DATA, NONE
accountNumber
type: string
required: true
The account number of the account. The format of the account numbers may differ between account types and banks. This property can be updated in a update account request.
balance
type: number
required: true
The current balance of the account. The definition of the balance property differ between account types. SAVINGS: the balance represent the actual amount of cash in the account, INVESTMENT: the balance represents the value of the investments connected to this accounts including any available cash, MORTGAGE: the balance represents the loan debt outstanding from this account, CREDIT_CARD: the balance represent the outstanding balance on the account, it does not include any available credit or purchasing power the user has with the credit provider.
closed
type: boolean
required: false
credentialsId
type: string
required: true
The internal identifier of the credentials that the account belongs to.
currencyDenominatedBalance
type: CurrencyDenominatedAmount
required: false
The current balance of the account. The definition of the balance property differ between account types. SAVINGS: the balance represent the actual amount of cash in the account, INVESTMENT: the balance represents the value of the investments connected to this accounts including any available cash, MORTGAGE: the balance represents the loan debt outstanding from this account, CREDIT_CARD: the balance represent the outstanding balance on the account, it does not include any available credit or purchasing power the user has with the credit provider. The balance is represented as a scale and unscaled value together with the ISO 4217 currency code of the amount.
details
type: AccountDetails
required: false
Details contains information only applicable for accounts of the types loans and mortgages. All banks do not offer detail information about their loan and mortgages therefore will details not be present on all accounts of the types loan and mortgages.
excluded
type: boolean
required: true
Indicates if the user has excluded the account. Categorization and PFM Features are excluded, and transactions belonging to this account are not searchable. This property can be updated in a update account request.
favored
type: boolean
required: true
Indicates if the user has favored the account. This property can be updated in a update account request.
financialInstitutionId
type: string
required: false
(PSD2 change - Not yet implemented) - A unique identifier to group accounts belonging the same financial institution. Available for aggregated accounts only.
flags
type: string
required: false
A list of flags specifying attributes on an account. Values: BUSINESS, MANDATE
holderName
type: string
required: false
The name of the account holder
id
type: string
required: true
The internal identifier of account.
identifiers
type: string
required: false
All possible ways to uniquely identify this Account. An se-identifier is built up like: se://{clearingnumber}{accountnumber}
name
type: string
required: true
The display name of the account. This property can be updated in a update account request.
ownership
type: number
required: true
The ownership ratio indicating how much of the account is owned by the user. The ownership determine the percentage of the amounts on transactions belonging to this account, that should be attributed to the user when statistics are calculated. This property can be updated in a update account request.
transferDestinations
type: array[TransferDestination]
required: false
The destinations this Account can transfer money to, be that payment or bank transfer recipients. This field is only populated if account data is requested via GET /transfer/accounts.
type
type: string
required: true
The type of the account. This property can be updated in a update account request.. Values: CHECKING, SAVINGS, INVESTMENT, MORTGAGE, CREDIT_CARD, LOAN, PENSION, OTHER, EXTERNAL

CurrencyDenominatedAmount

Parameter Description
currencyCode
type: string
required: true
The ISO 4217 currency code of the amount
scale
type: integer
required: true
The scale of the amount.
unscaledValue
type: integer
required: true
The unscaled value of the amount

AccountDetails

Parameter Description
interest
type: number
required: false
Interest of the account. Applicable for loans and savings accounts.
nextDayOfTermsChange
type: number
required: false
A timestamp of the next day of terms change of the account. Applicable for loans.
numMonthsBound
type: integer
required: false
Populated if available. Describes how many months the interest rate is bound.
type
type: string
required: false
Account subtype. Values: MORTGAGE, BLANCO, MEMBERSHIP, VEHICLE, LAND, STUDENT, OTHER

TransferDestination

Parameter Description
balance
type: number
required: false
The balance of the account. Will only be populated for accounts that is owned by the user.
displayAccountNumber
type: string
required: false
A display formatted alpha-numeric string of the destination account/payment recipient number.
displayBankName
type: string
required: false
The name of the bank where this destination resides. Will not be populated for payment destinations.
matchesMultiple
type: boolean
required: false
Indicates whether this TransferDestination matches multiple destinations. If true, the uri will be a regular expression, for instance "se-pg://.+" meaning that the source account can make PG payments.
name
type: string
required: false
The name of the destination if one exists.
type
type: string
required: false
The account type of the destination. Will be EXTERNAL for all destinations not owned by the user.. Values: CHECKING, SAVINGS, INVESTMENT, CREDIT_CARD, LOAN, EXTERNAL
uri
type: string
required: false
The uri used to describe this destination.

List accounts

Returns an object with a list of the authenticated user's accounts. GET /api/v1/accounts/list

Response Example

{
  "accounts": [
    {
      "accountExclusion": "string",
      "accountNumber": "1234-123456789",
      "balance": 34567,
      "closed": false,
      "credentialsId": "6e68cc6287704273984567b3300c5822",
      "currencyDenominatedBalance": {
        "currencyCode": "EUR",
        "scale": 2,
        "unscaledValue": 1050
      },
      "details": {
        "interest": 0,
        "nextDayOfTermsChange": "string",
        "numMonthsBound": 0,
        "type": "string"
      },
      "excluded": null,
      "favored": null,
      "financialInstitutionId": "6e68cc6287704273984567b3300c5822",
      "flags": "[\"MANDATE\"]",
      "holderName": "Thomas Alan Waits",
      "id": "a6bb87e57a8c4dd4874b241471a2b9e8",
      "identifiers": "[\"se://9999111111111111\"]",
      "name": "My account",
      "ownership": 0,
      "transferDestinations": [
        {
          "balance": 0,
          "displayAccountNumber": "902090-0",
          "displayBankName": null,
          "matchesMultiple": null,
          "name": "Barncancerfonden",
          "type": "EXTERNAL",
          "uri": "se-pg://9020900"
        }
      ],
      "type": "string"
    }
  ]
}

Response: AccountListResponse

Parameter Description
accounts
type: array[Account]
required: false
A list of accounts

Account

Parameter Description
accountExclusion
type: string
required: true
Indicate features this account should be excluded from. Possible values are: NONE: No features are excluded from this account, PFM_DATA: Categorization and Personal Finance Management Features, like statistics and activities are excluded, PFM_AND_SEARCH: Categorization and Personal Finance Management Features are excluded, and transactions belonging to this account are not searchable. This is the equivalent of the, now deprecated, boolean flag 'excluded', AGGREGATION: No data will be aggregated for this account and, all data associated with the account is removed (except account name and account number). This property can be updated in a update account request.. Values: AGGREGATION, PFM_AND_SEARCH, PFM_DATA, NONE
accountNumber
type: string
required: true
The account number of the account. The format of the account numbers may differ between account types and banks. This property can be updated in a update account request.
balance
type: number
required: true
The current balance of the account. The definition of the balance property differ between account types. SAVINGS: the balance represent the actual amount of cash in the account, INVESTMENT: the balance represents the value of the investments connected to this accounts including any available cash, MORTGAGE: the balance represents the loan debt outstanding from this account, CREDIT_CARD: the balance represent the outstanding balance on the account, it does not include any available credit or purchasing power the user has with the credit provider.
closed
type: boolean
required: false
credentialsId
type: string
required: true
The internal identifier of the credentials that the account belongs to.
currencyDenominatedBalance
type: CurrencyDenominatedAmount
required: false
The current balance of the account. The definition of the balance property differ between account types. SAVINGS: the balance represent the actual amount of cash in the account, INVESTMENT: the balance represents the value of the investments connected to this accounts including any available cash, MORTGAGE: the balance represents the loan debt outstanding from this account, CREDIT_CARD: the balance represent the outstanding balance on the account, it does not include any available credit or purchasing power the user has with the credit provider. The balance is represented as a scale and unscaled value together with the ISO 4217 currency code of the amount.
details
type: AccountDetails
required: false
Details contains information only applicable for accounts of the types loans and mortgages. All banks do not offer detail information about their loan and mortgages therefore will details not be present on all accounts of the types loan and mortgages.
excluded
type: boolean
required: true
Indicates if the user has excluded the account. Categorization and PFM Features are excluded, and transactions belonging to this account are not searchable. This property can be updated in a update account request.
favored
type: boolean
required: true
Indicates if the user has favored the account. This property can be updated in a update account request.
financialInstitutionId
type: string
required: false
(PSD2 change - Not yet implemented) - A unique identifier to group accounts belonging the same financial institution. Available for aggregated accounts only.
flags
type: string
required: false
A list of flags specifying attributes on an account. Values: BUSINESS, MANDATE
holderName
type: string
required: false
The name of the account holder
id
type: string
required: true
The internal identifier of account.
identifiers
type: string
required: false
All possible ways to uniquely identify this Account. An se-identifier is built up like: se://{clearingnumber}{accountnumber}
name
type: string
required: true
The display name of the account. This property can be updated in a update account request.
ownership
type: number
required: true
The ownership ratio indicating how much of the account is owned by the user. The ownership determine the percentage of the amounts on transactions belonging to this account, that should be attributed to the user when statistics are calculated. This property can be updated in a update account request.
transferDestinations
type: array[TransferDestination]
required: false
The destinations this Account can transfer money to, be that payment or bank transfer recipients. This field is only populated if account data is requested via GET /transfer/accounts.
type
type: string
required: true
The type of the account. This property can be updated in a update account request.. Values: CHECKING, SAVINGS, INVESTMENT, MORTGAGE, CREDIT_CARD, LOAN, PENSION, OTHER, EXTERNAL

CurrencyDenominatedAmount

Parameter Description
currencyCode
type: string
required: true
The ISO 4217 currency code of the amount
scale
type: integer
required: true
The scale of the amount.
unscaledValue
type: integer
required: true
The unscaled value of the amount

AccountDetails

Parameter Description
interest
type: number
required: false
Interest of the account. Applicable for loans and savings accounts.
nextDayOfTermsChange
type: number
required: false
A timestamp of the next day of terms change of the account. Applicable for loans.
numMonthsBound
type: integer
required: false
Populated if available. Describes how many months the interest rate is bound.
type
type: string
required: false
Account subtype. Values: MORTGAGE, BLANCO, MEMBERSHIP, VEHICLE, LAND, STUDENT, OTHER

TransferDestination

Parameter Description
balance
type: number
required: false
The balance of the account. Will only be populated for accounts that is owned by the user.
displayAccountNumber
type: string
required: false
A display formatted alpha-numeric string of the destination account/payment recipient number.
displayBankName
type: string
required: false
The name of the bank where this destination resides. Will not be populated for payment destinations.
matchesMultiple
type: boolean
required: false
Indicates whether this TransferDestination matches multiple destinations. If true, the uri will be a regular expression, for instance "se-pg://.+" meaning that the source account can make PG payments.
name
type: string
required: false
The name of the destination if one exists.
type
type: string
required: false
The account type of the destination. Will be EXTERNAL for all destinations not owned by the user.. Values: CHECKING, SAVINGS, INVESTMENT, CREDIT_CARD, LOAN, EXTERNAL
uri
type: string
required: false
The uri used to describe this destination.

Credentials

The credentials model represents users connected providers from where financial data is accessed.

Parameter Description
fields
type: object
required: true
This is a key-value map of Field name and value found on the Provider to which the credentials belongs to. This parameter is required when creating credentials.
id
type: string
required: false
The unique identifier of the credentials.
providerName
type: string
required: true
The provider (financial institution) that the credentials is connected to.
sessionExpiryDate
type: number
required: false
(PSD2 change - Not yet implemented) - Indicates when the session of credentials with access type OPEN_BANKING will expire. After this date automatic refreshes will not be possible without new authentication from the user.
status
type: string
required: false
The status indicates the state of the credentials. For some states there are actions which need to be performed on the credentials.. Values: CREATED, AUTHENTICATING, AWAITING_MOBILE_BANKID_AUTHENTICATION, AWAITING_SUPPLEMENTAL_INFORMATION, UPDATING, UPDATED, AUTHENTICATION_ERROR, TEMPORARY_ERROR, PERMANENT_ERROR, AWAITING_THIRD_PARTY_APP_AUTHENTICATION, DELETED, SESSION_EXPIRED
statusPayload
type: string
required: false
A user-friendly message connected to the status. Could be an error message or text describing what is currently going on in the refresh process.
statusUpdated
type: number
required: false
A timestamp of when the credentials' status was last modified.
supplementalInformation
type: string
required: false
A key-value structure to handle if status of credentials are AWAITING_SUPPLEMENTAL_INFORMATION or AWAITING_THIRD_PARTY_APP_AUTHENTICATION.
type
type: string
required: false
Indicates how Tink authenticates the user to the financial institution.. Values: PASSWORD, MOBILE_BANKID, KEYFOB, THIRD_PARTY_APP
updated
type: number
required: false
A timestamp of when the credentials was the last time in status UPDATED.
userId
type: string
required: false
The id of the user that the credentials belongs to.

List credentials

List all credentials for the user. GET /api/v1/credentials/list

Response Example

{
  "credentials": [
    {
      "fields": {
        "username": "198410045701"
      },
      "id": "6e68cc6287704273984567b3300c5822",
      "providerName": "handelsbanken-bankid",
      "sessionExpiryDate": 1493379467000,
      "status": "UPDATED",
      "statusPayload": "Analyzed 1,200 out of 1,200 transactions.",
      "statusUpdated": 1493379467000,
      "supplementalInformation": null,
      "type": "MOBILE_BANKID",
      "updated": 1493379467000,
      "userId": "c4ae034f96c740da91ae00022ddcac4d"
    }
  ]
}

Response: CredentialsListResponse

Parameter Description
credentials
type: array[Credentials]
required: false
A list of credentials

Credentials

Parameter Description
fields
type: object
required: true
This is a key-value map of Field name and value found on the Provider to which the credentials belongs to. This parameter is required when creating credentials.
id
type: string
required: false
The unique identifier of the credentials.
providerName
type: string
required: true
The provider (financial institution) that the credentials is connected to.
sessionExpiryDate
type: number
required: false
(PSD2 change - Not yet implemented) - Indicates when the session of credentials with access type OPEN_BANKING will expire. After this date automatic refreshes will not be possible without new authentication from the user.
status
type: string
required: false
The status indicates the state of the credentials. For some states there are actions which need to be performed on the credentials.. Values: CREATED, AUTHENTICATING, AWAITING_MOBILE_BANKID_AUTHENTICATION, AWAITING_SUPPLEMENTAL_INFORMATION, UPDATING, UPDATED, AUTHENTICATION_ERROR, TEMPORARY_ERROR, PERMANENT_ERROR, AWAITING_THIRD_PARTY_APP_AUTHENTICATION, DELETED, SESSION_EXPIRED
statusPayload
type: string
required: false
A user-friendly message connected to the status. Could be an error message or text describing what is currently going on in the refresh process.
statusUpdated
type: number
required: false
A timestamp of when the credentials' status was last modified.
supplementalInformation
type: string
required: false
A key-value structure to handle if status of credentials are AWAITING_SUPPLEMENTAL_INFORMATION or AWAITING_THIRD_PARTY_APP_AUTHENTICATION.
type
type: string
required: false
Indicates how Tink authenticates the user to the financial institution.. Values: PASSWORD, MOBILE_BANKID, KEYFOB, THIRD_PARTY_APP
updated
type: number
required: false
A timestamp of when the credentials was the last time in status UPDATED.
userId
type: string
required: false
The id of the user that the credentials belongs to.

Get credentials

Gets credentials by id. GET /api/v1/credentials/{id}

Parameters

Parameter Description
id
required: true
The internal identifier of the credentials to get

Response Example

{
  "fields": {
    "username": "198410045701"
  },
  "id": "6e68cc6287704273984567b3300c5822",
  "providerName": "handelsbanken-bankid",
  "sessionExpiryDate": 1493379467000,
  "status": "UPDATED",
  "statusPayload": "Analyzed 1,200 out of 1,200 transactions.",
  "statusUpdated": 1493379467000,
  "supplementalInformation": null,
  "type": "MOBILE_BANKID",
  "updated": 1493379467000,
  "userId": "c4ae034f96c740da91ae00022ddcac4d"
}

Response: Credentials

Parameter Description
fields
type: object
required: true
This is a key-value map of Field name and value found on the Provider to which the credentials belongs to. This parameter is required when creating credentials.
id
type: string
required: false
The unique identifier of the credentials.
providerName
type: string
required: true
The provider (financial institution) that the credentials is connected to.
sessionExpiryDate
type: number
required: false
(PSD2 change - Not yet implemented) - Indicates when the session of credentials with access type OPEN_BANKING will expire. After this date automatic refreshes will not be possible without new authentication from the user.
status
type: string
required: false
The status indicates the state of the credentials. For some states there are actions which need to be performed on the credentials.. Values: CREATED, AUTHENTICATING, AWAITING_MOBILE_BANKID_AUTHENTICATION, AWAITING_SUPPLEMENTAL_INFORMATION, UPDATING, UPDATED, AUTHENTICATION_ERROR, TEMPORARY_ERROR, PERMANENT_ERROR, AWAITING_THIRD_PARTY_APP_AUTHENTICATION, DELETED, SESSION_EXPIRED
statusPayload
type: string
required: false
A user-friendly message connected to the status. Could be an error message or text describing what is currently going on in the refresh process.
statusUpdated
type: number
required: false
A timestamp of when the credentials' status was last modified.
supplementalInformation
type: string
required: false
A key-value structure to handle if status of credentials are AWAITING_SUPPLEMENTAL_INFORMATION or AWAITING_THIRD_PARTY_APP_AUTHENTICATION.
type
type: string
required: false
Indicates how Tink authenticates the user to the financial institution.. Values: PASSWORD, MOBILE_BANKID, KEYFOB, THIRD_PARTY_APP
updated
type: number
required: false
A timestamp of when the credentials was the last time in status UPDATED.
userId
type: string
required: false
The id of the user that the credentials belongs to.
Status Code Description
200 The credentials was successfully returned.
404 The credentials could not be found.

Migrate existing credentials to PSD2

Will migrate existing credentials to a PSD2 credentials. Will return the both the old and the new credentials. PUT /api/v1/credentials/{id}/migrate

Parameters

Parameter Description
id
required: true
The internal identifier of the credentials to migrate
Status Code Description
200 The credentials was successfully migrated.
404 The credentials could not be found.

Get QR-code.

QR-code for authentication flows such as Mobile BankID as base64 encoded PNG. Includes 'data:image/png;base64,'. GET /api/v1/credentials/{id}/qr

Parameters

Parameter Description
id
required: true

Response: text/plain

The qr code was successfully returned. Status Code | Description --------- | --------------- 200 | The qr code was successfully returned. 400 | The payload does not pass validation. 404 | Could not find the autostarttoken.

Identity

The identity model represents personal information of a user which can be used to identify the person. To get as much identity data as possible the information is collected per provider.

Parameter Description
dateOfBirth
type: string
required: false
Date of birth of the user. The date will follow ISO 8601 with format yyyy-MM-dd.
name
type: string
required: false
Full name of the user
providerName
type: string
required: false
The provider from where the data was collected.
ssn
type: string
required: false
Social security number of the user.

List all available identity data

Lists the available identity data from each provider for a user. GET /api/v1/identities

Response Example

{
  "availableIdentityData": [
    {
      "dateOfBirth": "1970-01-01",
      "name": "Jane Doe",
      "providerName": "se-bankname-bankid",
      "ssn": "19700101-1234"
    }
  ]
}

Response: IdentityListResponse

Parameter Description
availableIdentityData
type: array[Identity]
required: false
A list of all available identity data for the user

Identity

Parameter Description
dateOfBirth
type: string
required: false
Date of birth of the user. The date will follow ISO 8601 with format yyyy-MM-dd.
name
type: string
required: false
Full name of the user
providerName
type: string
required: false
The provider from where the data was collected.
ssn
type: string
required: false
Social security number of the user.

Provider

The provider model represents financial institutions to where Tink can connect. It specifies how Tink accesses the financial institution, metadata about the financialinstitution, and what financial information that can be accessed.

Parameter Description
accessType
type: string
required: true
(PSD2 change - Not yet implemented) - What Tink uses to access the data.. Values: OPEN_BANKING, OTHER
authenticationFlow
type: string
required: true
(PSD2 change - Not yet implemented) - What type of authentication flow used to access the data.. Values: EMBEDDED, REDIRECT, DECOUPLED
capabilities
type: array[string]
required: true
Indicates what this provider is capable of, in terms of financial data it can aggregate and if it can execute payments.
credentialsType
type: string
required: true
When creating a new credential connected to the provider this will be the credentials type.. Values: PASSWORD, MOBILE_BANKID, KEYFOB, THIRD_PARTY_APP
currency
type: string
required: true
The default currency of the provider.
displayDescription
type: string
required: false
Short displayable description of the authentication type used.
displayName
type: string
required: true
The display name of the provider.
fields
type: array[Field]
required: true
List of fields which need to be provided when creating a credential connected to the provider.
financialInstitutionId
type: string
required: true
(PSD2 change - Not yet implemented) - A unique identifier to group providers belonging the same financial institution.
financialInstitutionName
type: string
required: true
(PSD2 change - Not yet implemented) - The name of the financial institution.
groupDisplayName
type: string
required: false
A display name for providers which are branches of a bigger group.
images
type: ImageUrls
required: false
market
type: string
required: true
The market of the provider. Each provider is unique per market.
multiFactor
type: boolean
required: true
Indicates if the provider requires multi-factor authentication.
name
type: string
required: true
The unique identifier of the provider. This is used when creating new credentials.
passwordHelpText
type: string
required: false
Short description of how to authenticate when creating a new credential for connected to the provider.
popular
type: boolean
required: true
Indicates if the provider is popular. This is normally set to true for the biggest financial institutions on a market.
status
type: string
required: true
Indicates the current status of the provider. It is only possible to perform credentials create or refresh actions on providers which are enabled.. Values: ENABLED, TEMPORARY_DISABLED, DISABLED
transactional
type: boolean
required: true
Indicates if Tink can aggregate transactions for this provider.
type
type: string
required: true
Indicates what type of financial institution the provider represents.. Values: BANK, CREDIT_CARD, BROKER, TEST, OTHER

Field

Parameter Description
additionalInfo
type: string
required: false
A serialized JSON containing additional information that could be useful
checkbox
type: boolean
required: false
Display boolean value as checkbox
defaultValue
type: string
required: false
description
type: string
required: false
helpText
type: string
required: false
Text displayed next to the input field
hint
type: string
required: false
Gray text in the input view (Similar to a placeholder)
immutable
type: boolean
required: false
masked
type: boolean
required: false
Controls whether or not the field should be shown masked, like a password field
maxLength
type: integer
required: false
minLength
type: integer
required: false
name
type: string
required: false
numeric
type: boolean
required: false
optional
type: boolean
required: false
options
type: array[string]
required: false
A list of options where the user should select one
pattern
type: string
required: false
patternError
type: string
required: false
sensitive
type: boolean
required: false
value
type: string
required: false

ImageUrls

Parameter Description
banner
type: string
required: false
icon
type: string
required: false

List providers

Lists all providers. GET /api/v1/providers

Query Parameters

Parameter Description
capability
required: false
Use the capability to only list providers with a specific capability. If no capability the provider response will not be filtered on capability. Values: UNKNOWN, TRANSFERS, MORTGAGE_AGGREGATION, CHECKING_ACCOUNTS, SAVINGS_ACCOUNTS, CREDIT_CARDS, INVESTMENTS, LOANS, PAYMENTS, MORTGAGE_LOAN, IDENTITY_DATA
includeTestProviders
required: false
Defaults to false. If set to true, Providers of TEST type will be added in the response list.
excludeNonTestProviders
required: false
Defaults to false. If set to true, Providers of type different than TEST will be removed from the response list.

Response Example

{
  "providers": [
    {
      "accessType": "OPEN_BANKING",
      "authenticationFlow": "REDIRECT",
      "capabilities": [
        "string",
        "string"
      ],
      "credentialsType": "THIRD_PARTY_APP",
      "currency": "SEK",
      "displayDescription": "Bink authentication app",
      "displayName": "Bink",
      "fields": [
        {
          "additionalInfo": "string",
          "checkbox": false,
          "defaultValue": "string",
          "description": "string",
          "helpText": "Enter your username",
          "hint": "YYYYMMDD-NNNN",
          "immutable": false,
          "masked": false,
          "maxLength": 0,
          "minLength": 0,
          "name": "string",
          "numeric": false,
          "optional": false,
          "options": [
            "string",
            "string"
          ],
          "pattern": "string",
          "patternError": "string",
          "sensitive": false,
          "value": "string"
        }
      ],
      "financialInstitutionId": "01234567-1234-1234-1234-123456789123",
      "financialInstitutionName": "Bink",
      "groupDisplayName": "Bink Corp.",
      "images": {
        "banner": "string",
        "icon": "string"
      },
      "market": "SE",
      "multiFactor": null,
      "name": "se-bink-thirdpartyapp",
      "passwordHelpText": "Use the same password as you would in your bank's mobile app.",
      "popular": null,
      "status": "ENABLED",
      "transactional": null,
      "type": "BANK"
    }
  ]
}

Response: ProviderListResponse

Parameter Description
providers
type: array[Provider]
required: false

Provider

Parameter Description
accessType
type: string
required: true
(PSD2 change - Not yet implemented) - What Tink uses to access the data.. Values: OPEN_BANKING, OTHER
authenticationFlow
type: string
required: true
(PSD2 change - Not yet implemented) - What type of authentication flow used to access the data.. Values: EMBEDDED, REDIRECT, DECOUPLED
capabilities
type: array[string]
required: true
Indicates what this provider is capable of, in terms of financial data it can aggregate and if it can execute payments.
credentialsType
type: string
required: true
When creating a new credential connected to the provider this will be the credentials type.. Values: PASSWORD, MOBILE_BANKID, KEYFOB, THIRD_PARTY_APP
currency
type: string
required: true
The default currency of the provider.
displayDescription
type: string
required: false
Short displayable description of the authentication type used.
displayName
type: string
required: true
The display name of the provider.
fields
type: array[Field]
required: true
List of fields which need to be provided when creating a credential connected to the provider.
financialInstitutionId
type: string
required: true
(PSD2 change - Not yet implemented) - A unique identifier to group providers belonging the same financial institution.
financialInstitutionName
type: string
required: true
(PSD2 change - Not yet implemented) - The name of the financial institution.
groupDisplayName
type: string
required: false
A display name for providers which are branches of a bigger group.
images
type: ImageUrls
required: false
market
type: string
required: true
The market of the provider. Each provider is unique per market.
multiFactor
type: boolean
required: true
Indicates if the provider requires multi-factor authentication.
name
type: string
required: true
The unique identifier of the provider. This is used when creating new credentials.
passwordHelpText
type: string
required: false
Short description of how to authenticate when creating a new credential for connected to the provider.
popular
type: boolean
required: true
Indicates if the provider is popular. This is normally set to true for the biggest financial institutions on a market.
status
type: string
required: true
Indicates the current status of the provider. It is only possible to perform credentials create or refresh actions on providers which are enabled.. Values: ENABLED, TEMPORARY_DISABLED, DISABLED
transactional
type: boolean
required: true
Indicates if Tink can aggregate transactions for this provider.
type
type: string
required: true
Indicates what type of financial institution the provider represents.. Values: BANK, CREDIT_CARD, BROKER, TEST, OTHER

Field

Parameter Description
additionalInfo
type: string
required: false
A serialized JSON containing additional information that could be useful
checkbox
type: boolean
required: false
Display boolean value as checkbox
defaultValue
type: string
required: false
description
type: string
required: false
helpText
type: string
required: false
Text displayed next to the input field
hint
type: string
required: false
Gray text in the input view (Similar to a placeholder)
immutable
type: boolean
required: false
masked
type: boolean
required: false
Controls whether or not the field should be shown masked, like a password field
maxLength
type: integer
required: false
minLength
type: integer
required: false
name
type: string
required: false
numeric
type: boolean
required: false
optional
type: boolean
required: false
options
type: array[string]
required: false
A list of options where the user should select one
pattern
type: string
required: false
patternError
type: string
required: false
sensitive
type: boolean
required: false
value
type: string
required: false

ImageUrls

Parameter Description
banner
type: string
required: false
icon
type: string
required: false

List markets

Lists all markets where there are providers available. GET /api/v1/providers/markets

Header Parameters

Parameter Description
X-Tink-OAuth-Client-ID
required: false
The OAuth2 Client ID

Response Example

{
  "markets": [
    "string",
    "string"
  ]
}

Response: ProviderMarketListResponse

Parameter Description
markets
type: array[string]
required: false

List providers for a specified market

Lists all providers for a specified market. GET /api/v1/providers/{market}

Parameters

Parameter Description
market
required: true
SE for Swedish market

Header Parameters

Parameter Description
X-Tink-OAuth-Client-ID
required: false
The OAuth2 Client ID
Accept-Language
required: false
Language to translate to.

Query Parameters

Parameter Description
includeTestProviders
required: false
Defaults to false. If set to true, Providers of TEST type will be added in the response list.
excludeNonTestProviders
required: false
Defaults to false. If set to true, Providers of type different than TEST will be removed from the response list.
capability
required: false
Use the capability to only list providers with a specific capability. If no capability the provider response will not be filtered on capability. Values: UNKNOWN, TRANSFERS, MORTGAGE_AGGREGATION, CHECKING_ACCOUNTS, SAVINGS_ACCOUNTS, CREDIT_CARDS, INVESTMENTS, LOANS, PAYMENTS, MORTGAGE_LOAN, IDENTITY_DATA

Response Example

{
  "providers": [
    {
      "accessType": "OPEN_BANKING",
      "authenticationFlow": "REDIRECT",
      "capabilities": [
        "string",
        "string"
      ],
      "credentialsType": "THIRD_PARTY_APP",
      "currency": "SEK",
      "displayDescription": "Bink authentication app",
      "displayName": "Bink",
      "fields": [
        {
          "additionalInfo": "string",
          "checkbox": false,
          "defaultValue": "string",
          "description": "string",
          "helpText": "Enter your username",
          "hint": "YYYYMMDD-NNNN",
          "immutable": false,
          "masked": false,
          "maxLength": 0,
          "minLength": 0,
          "name": "string",
          "numeric": false,
          "optional": false,
          "options": [
            "string",
            "string"
          ],
          "pattern": "string",
          "patternError": "string",
          "sensitive": false,
          "value": "string"
        }
      ],
      "financialInstitutionId": "01234567-1234-1234-1234-123456789123",
      "financialInstitutionName": "Bink",
      "groupDisplayName": "Bink Corp.",
      "images": {
        "banner": "string",
        "icon": "string"
      },
      "market": "SE",
      "multiFactor": null,
      "name": "se-bink-thirdpartyapp",
      "passwordHelpText": "Use the same password as you would in your bank's mobile app.",
      "popular": null,
      "status": "ENABLED",
      "transactional": null,
      "type": "BANK"
    }
  ]
}

Response: ProviderListResponse

Parameter Description
providers
type: array[Provider]
required: false

Provider

Parameter Description
accessType
type: string
required: true
(PSD2 change - Not yet implemented) - What Tink uses to access the data.. Values: OPEN_BANKING, OTHER
authenticationFlow
type: string
required: true
(PSD2 change - Not yet implemented) - What type of authentication flow used to access the data.. Values: EMBEDDED, REDIRECT, DECOUPLED
capabilities
type: array[string]
required: true
Indicates what this provider is capable of, in terms of financial data it can aggregate and if it can execute payments.
credentialsType
type: string
required: true
When creating a new credential connected to the provider this will be the credentials type.. Values: PASSWORD, MOBILE_BANKID, KEYFOB, THIRD_PARTY_APP
currency
type: string
required: true
The default currency of the provider.
displayDescription
type: string
required: false
Short displayable description of the authentication type used.
displayName
type: string
required: true
The display name of the provider.
fields
type: array[Field]
required: true
List of fields which need to be provided when creating a credential connected to the provider.
financialInstitutionId
type: string
required: true
(PSD2 change - Not yet implemented) - A unique identifier to group providers belonging the same financial institution.
financialInstitutionName
type: string
required: true
(PSD2 change - Not yet implemented) - The name of the financial institution.
groupDisplayName
type: string
required: false
A display name for providers which are branches of a bigger group.
images
type: ImageUrls
required: false
market
type: string
required: true
The market of the provider. Each provider is unique per market.
multiFactor
type: boolean
required: true
Indicates if the provider requires multi-factor authentication.
name
type: string
required: true
The unique identifier of the provider. This is used when creating new credentials.
passwordHelpText
type: string
required: false
Short description of how to authenticate when creating a new credential for connected to the provider.
popular
type: boolean
required: true
Indicates if the provider is popular. This is normally set to true for the biggest financial institutions on a market.
status
type: string
required: true
Indicates the current status of the provider. It is only possible to perform credentials create or refresh actions on providers which are enabled.. Values: ENABLED, TEMPORARY_DISABLED, DISABLED
transactional
type: boolean
required: true
Indicates if Tink can aggregate transactions for this provider.
type
type: string
required: true
Indicates what type of financial institution the provider represents.. Values: BANK, CREDIT_CARD, BROKER, TEST, OTHER

Field

Parameter Description
additionalInfo
type: string
required: false
A serialized JSON containing additional information that could be useful
checkbox
type: boolean
required: false
Display boolean value as checkbox
defaultValue
type: string
required: false
description
type: string
required: false
helpText
type: string
required: false
Text displayed next to the input field
hint
type: string
required: false
Gray text in the input view (Similar to a placeholder)
immutable
type: boolean
required: false
masked
type: boolean
required: false
Controls whether or not the field should be shown masked, like a password field
maxLength
type: integer
required: false
minLength
type: integer
required: false
name
type: string
required: false
numeric
type: boolean
required: false
optional
type: boolean
required: false
options
type: array[string]
required: false
A list of options where the user should select one
pattern
type: string
required: false
patternError
type: string
required: false
sensitive
type: boolean
required: false
value
type: string
required: false

ImageUrls

Parameter Description
banner
type: string
required: false
icon
type: string
required: false

Budget Service

List budgets

List all budgets for the user. Returns 500 Internal Server Error for any unspecified error. GET /api/v1/budgets

Query Parameters

Parameter Description
includeArchived
required: false
Whether to include archived budgets or not in the response.

Response Example

{
  "budgetSpecifications": [
    {
      "amount": {
        "currencyCode": "EUR",
        "scale": 2,
        "unscaledValue": 1050
      },
      "archived": null,
      "description": "Spend less on coffee so that I can travel around the world.",
      "filter": {
        "accounts": [
          {
            "id": "325ee4ccf579450ca59d89ee54fa7e40"
          }
        ],
        "categories": [
          {
            "code": "expenses:food.coffee"
          }
        ],
        "freeTextQuery": "Monmouth Coffee",
        "tags": [
          {
            "key": "coffee"
          }
        ]
      },
      "id": "e2b746ed27c542ce846a8d693474df21",
      "name": "Coffee budget",
      "oneOffPeriodicity": {
        "end": 1552395986,
        "start": 1549976786
      },
      "periodicityType": "ONE_OFF",
      "recurringPeriodicity": {
        "periodUnit": "WEEK"
      }
    }
  ]
}

Response: ListBudgetSpecificationsResponse

Parameter Description
budgetSpecifications
type: array[BudgetSpecification]
required: false
List of budgets.

BudgetSpecification

Parameter Description
amount
type: CurrencyDenominatedAmount
required: false
The target amount for Budget.
archived
type: boolean
required: false
Indicates if the budget has state archived or not.
description
type: string
required: false
The description of the Budget.
filter
type: Filter
required: false
The filter defining the budget and which transactions that is included in it. The configured fields of the filter are applied as logical and operator (intersection).
id
type: string
required: false
The id of the Budget.
name
type: string
required: false
The name of the Budget.
oneOffPeriodicity
type: OneOffPeriodicity
required: false
Periodicity configuration for a ONE_OFF budget.
periodicityType
type: string
required: false
Tells whether the budget is recurring or one off type. Using this field it's possible to see which of the field recurringPeriodicity or oneOffPeriodicity is set.. Values: ONE_OFF, RECURRING
recurringPeriodicity
type: RecurringPeriodicity
required: false
Periodicity configuration for a RECURRING budget.

CurrencyDenominatedAmount

Parameter Description
currencyCode
type: string
required: true
The ISO 4217 currency code of the amount
scale
type: integer
required: true
The scale of the amount.
unscaledValue
type: integer
required: true
The unscaled value of the amount

Filter

Parameter Description
accounts
type: array[BudgetFilterAccount]
required: false
List of included accounts. Applied as logical or (union).
categories
type: array[BudgetFilterCategory]
required: false
List of included categories. Applied as logical or (union).
freeTextQuery
type: string
required: false
Query for a partial transaction description match.
tags
type: array[BudgetFilterTag]
required: false
List of included tags. Applied as logical or (union).

BudgetFilterAccount

Parameter Description
id
type: string
required: false
The account id.

BudgetFilterCategory

Parameter Description
code
type: string
required: false
The category code.

BudgetFilterTag

Parameter Description
key
type: string
required: false
The tag key.

OneOffPeriodicity

Parameter Description
end
type: number
required: true
Budget end expressed as UTC epoch timestamp.
start
type: number
required: true
Budget start expressed as UTC epoch timestamp.

RecurringPeriodicity

Parameter Description
periodUnit
type: string
required: true
Recurring periodicity unit.. Values: WEEK, MONTH, YEAR

Create one-off budget

Creates a budget for a specific date interval. Returns 400 Bad Request if any of the request parameters is incorrect or missing. Returns 500 Internal Server Error for any unspecified error. POST /api/v1/budgets/one-off

Request Example

{
  "amount": {
    "currencyCode": "EUR",
    "scale": 2,
    "unscaledValue": 1050
  },
  "description": "Spend less on coffee so that I can travel around the world.",
  "filter": {
    "accounts": [
      {
        "id": "325ee4ccf579450ca59d89ee54fa7e40"
      }
    ],
    "categories": [
      {
        "code": "expenses:food.coffee"
      }
    ],
    "freeTextQuery": "Monmouth Coffee",
    "tags": [
      {
        "key": "coffee"
      }
    ]
  },
  "name": "Coffee budget",
  "oneOffPeriodicity": {
    "end": 1552395986,
    "start": 1549976786
  }
}

Request Body: CreateOneOffBudgetRequest

The one off budget to be created.

Parameter Description
amount
type: CurrencyDenominatedAmount
required: true
The target amount for Budget.
description
type: string
required: false
The description of the Budget.
filter
type: Filter
required: true
The filter defining the budget and which transactions that is included in it. The configured fields of the filter are applied as logical and operator (intersection).
name
type: string
required: true
The name of the Budget.
oneOffPeriodicity
type: OneOffPeriodicity
required: true
Periodicity configuration for the one off budget.

CurrencyDenominatedAmount

Parameter Description
currencyCode
type: string
required: true
The ISO 4217 currency code of the amount
scale
type: integer
required: true
The scale of the amount.
unscaledValue
type: integer
required: true
The unscaled value of the amount

Filter

Parameter Description
accounts
type: array[BudgetFilterAccount]
required: false
List of included accounts. Applied as logical or (union).
categories
type: array[BudgetFilterCategory]
required: false
List of included categories. Applied as logical or (union).
freeTextQuery
type: string
required: false
Query for a partial transaction description match.
tags
type: array[BudgetFilterTag]
required: false
List of included tags. Applied as logical or (union).

BudgetFilterAccount

Parameter Description
id
type: string
required: false
The account id.

BudgetFilterCategory

Parameter Description
code
type: string
required: false
The category code.

BudgetFilterTag

Parameter Description
key
type: string
required: false
The tag key.

OneOffPeriodicity

Parameter Description
end
type: number
required: true
Budget end expressed as UTC epoch timestamp.
start
type: number
required: true
Budget start expressed as UTC epoch timestamp.

Response Example

{
  "budgetSpecification": {
    "amount": {
      "currencyCode": "EUR",
      "scale": 2,
      "unscaledValue": 1050
    },
    "archived": null,
    "description": "Spend less on coffee so that I can travel around the world.",
    "filter": {
      "accounts": [
        {
          "id": "325ee4ccf579450ca59d89ee54fa7e40"
        }
      ],
      "categories": [
        {
          "code": "expenses:food.coffee"
        }
      ],
      "freeTextQuery": "Monmouth Coffee",
      "tags": [
        {
          "key": "coffee"
        }
      ]
    },
    "id": "e2b746ed27c542ce846a8d693474df21",
    "name": "Coffee budget",
    "oneOffPeriodicity": {
      "end": 1552395986,
      "start": 1549976786
    },
    "periodicityType": "ONE_OFF",
    "recurringPeriodicity": {
      "periodUnit": "WEEK"
    }
  }
}

Response: CreateBudgetResponse

Parameter Description
budgetSpecification
type: BudgetSpecification
required: false
The created budget.

BudgetSpecification

Parameter Description
amount
type: CurrencyDenominatedAmount
required: false
The target amount for Budget.
archived
type: boolean
required: false
Indicates if the budget has state archived or not.
description
type: string
required: false
The description of the Budget.
filter
type: Filter
required: false
The filter defining the budget and which transactions that is included in it. The configured fields of the filter are applied as logical and operator (intersection).
id
type: string
required: false
The id of the Budget.
name
type: string
required: false
The name of the Budget.
oneOffPeriodicity
type: OneOffPeriodicity
required: false
Periodicity configuration for a ONE_OFF budget.
periodicityType
type: string
required: false
Tells whether the budget is recurring or one off type. Using this field it's possible to see which of the field recurringPeriodicity or oneOffPeriodicity is set.. Values: ONE_OFF, RECURRING
recurringPeriodicity
type: RecurringPeriodicity
required: false
Periodicity configuration for a RECURRING budget.

CurrencyDenominatedAmount

Parameter Description
currencyCode
type: string
required: true
The ISO 4217 currency code of the amount
scale
type: integer
required: true
The scale of the amount.
unscaledValue
type: integer
required: true
The unscaled value of the amount

Filter

Parameter Description
accounts
type: array[BudgetFilterAccount]
required: false
List of included accounts. Applied as logical or (union).
categories
type: array[BudgetFilterCategory]
required: false
List of included categories. Applied as logical or (union).
freeTextQuery
type: string
required: false
Query for a partial transaction description match.
tags
type: array[BudgetFilterTag]
required: false
List of included tags. Applied as logical or (union).

BudgetFilterAccount

Parameter Description
id
type: string
required: false
The account id.

BudgetFilterCategory

Parameter Description
code
type: string
required: false
The category code.

BudgetFilterTag

Parameter Description
key
type: string
required: false
The tag key.

OneOffPeriodicity

Parameter Description
end
type: number
required: true
Budget end expressed as UTC epoch timestamp.
start
type: number
required: true
Budget start expressed as UTC epoch timestamp.

RecurringPeriodicity

Parameter Description
periodUnit
type: string
required: true
Recurring periodicity unit.. Values: WEEK, MONTH, YEAR

Create recurring budget

Creates a recurring budget with a set periodicity.Returns 400 Bad Request if any of the request parameters is incorrect or missing. Returns 500 Internal Server Error for any unspecified error. POST /api/v1/budgets/recurring

Request Example

{
  "amount": {
    "currencyCode": "EUR",
    "scale": 2,
    "unscaledValue": 1050
  },
  "description": "Spend less on coffee so that I can travel around the world.",
  "filter": {
    "accounts": [
      {
        "id": "325ee4ccf579450ca59d89ee54fa7e40"
      }
    ],
    "categories": [
      {
        "code": "expenses:food.coffee"
      }
    ],
    "freeTextQuery": "Monmouth Coffee",
    "tags": [
      {
        "key": "coffee"
      }
    ]
  },
  "name": "Coffee budget",
  "recurringPeriodicity": {
    "periodUnit": "WEEK"
  }
}

Request Body: CreateRecurringBudgetRequest

The recurring budget to be created.

Parameter Description
amount
type: CurrencyDenominatedAmount
required: true
The target amount for Budget.
description
type: string
required: false
The description of the Budget.
filter
type: Filter
required: true
The filter defining the budget and which transactions that is included in it. The configured fields of the filter are applied as logical and operator (intersection).
name
type: string
required: true
The name of the Budget.
recurringPeriodicity
type: RecurringPeriodicity
required: true
Periodicity configuration for the recurring budget.

CurrencyDenominatedAmount

Parameter Description
currencyCode
type: string
required: true
The ISO 4217 currency code of the amount
scale
type: integer
required: true
The scale of the amount.
unscaledValue
type: integer
required: true
The unscaled value of the amount

Filter

Parameter Description
accounts
type: array[BudgetFilterAccount]
required: false
List of included accounts. Applied as logical or (union).
categories
type: array[BudgetFilterCategory]
required: false
List of included categories. Applied as logical or (union).
freeTextQuery
type: string
required: false
Query for a partial transaction description match.
tags
type: array[BudgetFilterTag]
required: false
List of included tags. Applied as logical or (union).

BudgetFilterAccount

Parameter Description
id
type: string
required: false
The account id.

BudgetFilterCategory

Parameter Description
code
type: string
required: false
The category code.

BudgetFilterTag

Parameter Description
key
type: string
required: false
The tag key.

RecurringPeriodicity

Parameter Description
periodUnit
type: string
required: true
Recurring periodicity unit.. Values: WEEK, MONTH, YEAR

Response Example

{
  "budgetSpecification": {
    "amount": {
      "currencyCode": "EUR",
      "scale": 2,
      "unscaledValue": 1050
    },
    "archived": null,
    "description": "Spend less on coffee so that I can travel around the world.",
    "filter": {
      "accounts": [
        {
          "id": "325ee4ccf579450ca59d89ee54fa7e40"
        }
      ],
      "categories": [
        {
          "code": "expenses:food.coffee"
        }
      ],
      "freeTextQuery": "Monmouth Coffee",
      "tags": [
        {
          "key": "coffee"
        }
      ]
    },
    "id": "e2b746ed27c542ce846a8d693474df21",
    "name": "Coffee budget",
    "oneOffPeriodicity": {
      "end": 1552395986,
      "start": 1549976786
    },
    "periodicityType": "ONE_OFF",
    "recurringPeriodicity": {
      "periodUnit": "WEEK"
    }
  }
}

Response: CreateBudgetResponse

Parameter Description
budgetSpecification
type: BudgetSpecification
required: false
The created budget.

BudgetSpecification

Parameter Description
amount
type: CurrencyDenominatedAmount
required: false
The target amount for Budget.
archived
type: boolean
required: false
Indicates if the budget has state archived or not.
description
type: string
required: false
The description of the Budget.
filter
type: Filter
required: false
The filter defining the budget and which transactions that is included in it. The configured fields of the filter are applied as logical and operator (intersection).
id
type: string
required: false
The id of the Budget.
name
type: string
required: false
The name of the Budget.
oneOffPeriodicity
type: OneOffPeriodicity
required: false
Periodicity configuration for a ONE_OFF budget.
periodicityType
type: string
required: false
Tells whether the budget is recurring or one off type. Using this field it's possible to see which of the field recurringPeriodicity or oneOffPeriodicity is set.. Values: ONE_OFF, RECURRING
recurringPeriodicity
type: RecurringPeriodicity
required: false
Periodicity configuration for a RECURRING budget.

CurrencyDenominatedAmount

Parameter Description
currencyCode
type: string
required: true
The ISO 4217 currency code of the amount
scale
type: integer
required: true
The scale of the amount.
unscaledValue
type: integer
required: true
The unscaled value of the amount

Filter

Parameter Description
accounts
type: array[BudgetFilterAccount]
required: false
List of included accounts. Applied as logical or (union).
categories
type: array[BudgetFilterCategory]
required: false
List of included categories. Applied as logical or (union).
freeTextQuery
type: string
required: false
Query for a partial transaction description match.
tags
type: array[BudgetFilterTag]
required: false
List of included tags. Applied as logical or (union).

BudgetFilterAccount

Parameter Description
id
type: string
required: false
The account id.

BudgetFilterCategory

Parameter Description
code
type: string
required: false
The category code.

BudgetFilterTag

Parameter Description
key
type: string
required: false
The tag key.

OneOffPeriodicity

Parameter Description
end
type: number
required: true
Budget end expressed as UTC epoch timestamp.
start
type: number
required: true
Budget start expressed as UTC epoch timestamp.

RecurringPeriodicity

Parameter Description
periodUnit
type: string
required: true
Recurring periodicity unit.. Values: WEEK, MONTH, YEAR

List budgets with summaries

List all budgets for the user including current period for each budget. Returns 500 Internal Server Error for any unspecified error. GET /api/v1/budgets/summaries

Query Parameters

Parameter Description
includeArchived
required: false
Whether to include archived budgets or not in the response.

Response Example

{
  "budgetSummaries": [
    {
      "budgetPeriods": {
        "end": 1552395986,
        "spentAmount": {
          "currencyCode": "EUR",
          "scale": 2,
          "unscaledValue": 1050
        },
        "start": 1549976786
      },
      "budgetSpecification": {
        "amount": {
          "currencyCode": "EUR",
          "scale": 2,
          "unscaledValue": 1050
        },
        "archived": null,
        "description": "Spend less on coffee so that I can travel around the world.",
        "filter": {
          "accounts": [
            {
              "id": "325ee4ccf579450ca59d89ee54fa7e40"
            }
          ],
          "categories": [
            {
              "code": "expenses:food.coffee"
            }
          ],
          "freeTextQuery": "Monmouth Coffee",
          "tags": [
            {
              "key": "coffee"
            }
          ]
        },
        "id": "e2b746ed27c542ce846a8d693474df21",
        "name": "Coffee budget",
        "oneOffPeriodicity": {
          "end": 1552395986,
          "start": 1549976786
        },
        "periodicityType": "ONE_OFF",
        "recurringPeriodicity": {
          "periodUnit": "WEEK"
        }
      }
    }
  ]
}

Response: ListBudgetSummariesResponse

Parameter Description
budgetSummaries
type: array[BudgetSummary]
required: false
List of budget summaries.

BudgetSummary

Parameter Description
budgetPeriods
type: BudgetPeriod
required: false
The current running period.
budgetSpecification
type: BudgetSpecification
required: false
The budget.

BudgetPeriod

Parameter Description
end
type: number
required: false
Period end expressed as UTC epoch timestamp.
spentAmount
type: CurrencyDenominatedAmount
required: false
Period spent amount.
start
type: number
required: false
Period start expressed as UTC epoch timestamp.

CurrencyDenominatedAmount

Parameter Description
currencyCode
type: string
required: true
The ISO 4217 currency code of the amount
scale
type: integer
required: true
The scale of the amount.
unscaledValue
type: integer
required: true
The unscaled value of the amount

BudgetSpecification

Parameter Description
amount
type: CurrencyDenominatedAmount
required: false
The target amount for Budget.
archived
type: boolean
required: false
Indicates if the budget has state archived or not.
description
type: string
required: false
The description of the Budget.
filter
type: Filter
required: false
The filter defining the budget and which transactions that is included in it. The configured fields of the filter are applied as logical and operator (intersection).
id
type: string
required: false
The id of the Budget.
name
type: string
required: false
The name of the Budget.
oneOffPeriodicity
type: OneOffPeriodicity
required: false
Periodicity configuration for a ONE_OFF budget.
periodicityType
type: string
required: false
Tells whether the budget is recurring or one off type. Using this field it's possible to see which of the field recurringPeriodicity or oneOffPeriodicity is set.. Values: ONE_OFF, RECURRING
recurringPeriodicity
type: RecurringPeriodicity
required: false
Periodicity configuration for a RECURRING budget.

Filter

Parameter Description
accounts
type: array[BudgetFilterAccount]
required: false
List of included accounts. Applied as logical or (union).
categories
type: array[BudgetFilterCategory]
required: false
List of included categories. Applied as logical or (union).
freeTextQuery
type: string
required: false
Query for a partial transaction description match.
tags
type: array[BudgetFilterTag]
required: false
List of included tags. Applied as logical or (union).

BudgetFilterAccount

Parameter Description
id
type: string
required: false
The account id.

BudgetFilterCategory

Parameter Description
code
type: string
required: false
The category code.

BudgetFilterTag

Parameter Description
key
type: string
required: false
The tag key.

OneOffPeriodicity

Parameter Description
end
type: number
required: true
Budget end expressed as UTC epoch timestamp.
start
type: number
required: true
Budget start expressed as UTC epoch timestamp.

RecurringPeriodicity

Parameter Description
periodUnit
type: string
required: true
Recurring periodicity unit.. Values: WEEK, MONTH, YEAR

Delete budget

Deletes the specified budget. Returns 404 Not Found if the budget does not exist. Returns 400 Bad Request if any of the request parameters is incorrect or missing. Returns 500 Internal Server Error for any unspecified error. DELETE /api/v1/budgets/{id}

Parameters

Parameter Description
id
required: true
The id of the budget.

Update budget

Updates the specified budget. Returns 404 Not Found if the budget does not exist. Returns 400 Bad Request if any of the request parameters is incorrect or missing. Returns 500 Internal Server Error for any unspecified error. PUT /api/v1/budgets/{id}

Request Example

{
  "amount": {
    "currencyCode": "EUR",
    "scale": 2,
    "unscaledValue": 1050
  },
  "description": "Spend less on coffee so that I can travel around the world.",
  "filter": {
    "accounts": [
      {
        "id": "325ee4ccf579450ca59d89ee54fa7e40"
      }
    ],
    "categories": [
      {
        "code": "expenses:food.coffee"
      }
    ],
    "freeTextQuery": "Monmouth Coffee",
    "tags": [
      {
        "key": "coffee"
      }
    ]
  },
  "name": "Coffee budget",
  "oneOffPeriodicity": {
    "end": 1552395986,
    "start": 1549976786
  },
  "periodicityType": "ONE_OFF",
  "recurringPeriodicity": {
    "periodUnit": "WEEK"
  }
}

Parameters

Parameter Description
id
required: true
The id of the budget.

Request Body: UpdateBudgetRequest

The modified budget to be applied.

Parameter Description
amount
type: CurrencyDenominatedAmount
required: true
The target amount for Budget.
description
type: string
required: false
The description of the Budget.
filter
type: Filter
required: true
The filter defining the budget and which transactions that is included in it. The configured fields of the filter are applied as logical and operator (intersection).
name
type: string
required: true
The name of the Budget.
oneOffPeriodicity
type: OneOffPeriodicity
required: false
Periodicity configuration for a ONE_OFF budget. Required if periodicityType is set to ONE_OFF.
periodicityType
type: string
required: true
Tells whether the budget is recurring or one off type. Using this field it's possible to see which of the field recurringPeriodicity or oneOffPeriodicity is set.. Values: ONE_OFF, RECURRING
recurringPeriodicity
type: RecurringPeriodicity
required: false
Periodicity configuration for a RECURRING budget. Required if periodicityType is set to RECURRING.

CurrencyDenominatedAmount

Parameter Description
currencyCode
type: string
required: true
The ISO 4217 currency code of the amount
scale
type: integer
required: true
The scale of the amount.
unscaledValue
type: integer
required: true
The unscaled value of the amount

Filter

Parameter Description
accounts
type: array[BudgetFilterAccount]
required: false
List of included accounts. Applied as logical or (union).
categories
type: array[BudgetFilterCategory]
required: false
List of included categories. Applied as logical or (union).
freeTextQuery
type: string
required: false
Query for a partial transaction description match.
tags
type: array[BudgetFilterTag]
required: false
List of included tags. Applied as logical or (union).

BudgetFilterAccount

Parameter Description
id
type: string
required: false
The account id.

BudgetFilterCategory

Parameter Description
code
type: string
required: false
The category code.

BudgetFilterTag

Parameter Description
key
type: string
required: false
The tag key.

OneOffPeriodicity

Parameter Description
end
type: number
required: true
Budget end expressed as UTC epoch timestamp.
start
type: number
required: true
Budget start expressed as UTC epoch timestamp.

RecurringPeriodicity

Parameter Description
periodUnit
type: string
required: true
Recurring periodicity unit.. Values: WEEK, MONTH, YEAR

Response Example

{
  "budgetSpecification": {
    "amount": {
      "currencyCode": "EUR",
      "scale": 2,
      "unscaledValue": 1050
    },
    "archived": null,
    "description": "Spend less on coffee so that I can travel around the world.",
    "filter": {
      "accounts": [
        {
          "id": "325ee4ccf579450ca59d89ee54fa7e40"
        }
      ],
      "categories": [
        {
          "code": "expenses:food.coffee"
        }
      ],
      "freeTextQuery": "Monmouth Coffee",
      "tags": [
        {
          "key": "coffee"
        }
      ]
    },
    "id": "e2b746ed27c542ce846a8d693474df21",
    "name": "Coffee budget",
    "oneOffPeriodicity": {
      "end": 1552395986,
      "start": 1549976786
    },
    "periodicityType": "ONE_OFF",
    "recurringPeriodicity": {
      "periodUnit": "WEEK"
    }
  }
}

Response: UpdateBudgetResponse

Parameter Description
budgetSpecification
type: BudgetSpecification
required: false
The updated budget.

BudgetSpecification

Parameter Description
amount
type: CurrencyDenominatedAmount
required: false
The target amount for Budget.
archived
type: boolean
required: false
Indicates if the budget has state archived or not.
description
type: string
required: false
The description of the Budget.
filter
type: Filter
required: false
The filter defining the budget and which transactions that is included in it. The configured fields of the filter are applied as logical and operator (intersection).
id
type: string
required: false
The id of the Budget.
name
type: string
required: false
The name of the Budget.
oneOffPeriodicity
type: OneOffPeriodicity
required: false
Periodicity configuration for a ONE_OFF budget.
periodicityType
type: string
required: false
Tells whether the budget is recurring or one off type. Using this field it's possible to see which of the field recurringPeriodicity or oneOffPeriodicity is set.. Values: ONE_OFF, RECURRING
recurringPeriodicity
type: RecurringPeriodicity
required: false
Periodicity configuration for a RECURRING budget.

CurrencyDenominatedAmount

Parameter Description
currencyCode
type: string
required: true
The ISO 4217 currency code of the amount
scale
type: integer
required: true
The scale of the amount.
unscaledValue
type: integer
required: true
The unscaled value of the amount

Filter

Parameter Description
accounts
type: array[BudgetFilterAccount]
required: false
List of included accounts. Applied as logical or (union).
categories
type: array[BudgetFilterCategory]
required: false
List of included categories. Applied as logical or (union).
freeTextQuery
type: string
required: false
Query for a partial transaction description match.
tags
type: array[BudgetFilterTag]
required: false
List of included tags. Applied as logical or (union).

BudgetFilterAccount

Parameter Description
id
type: string
required: false
The account id.

BudgetFilterCategory

Parameter Description
code
type: string
required: false
The category code.

BudgetFilterTag

Parameter Description
key
type: string
required: false
The tag key.

OneOffPeriodicity

Parameter Description
end
type: number
required: true
Budget end expressed as UTC epoch timestamp.
start
type: number
required: true
Budget start expressed as UTC epoch timestamp.

RecurringPeriodicity

Parameter Description
periodUnit
type: string
required: true
Recurring periodicity unit.. Values: WEEK, MONTH, YEAR

Archive budget

Archives the specified budget.Returns 404 Not Found if the budget does not exist. Returns 400 Bad Request if any of the request parameters is incorrect or missing. Returns 500 Internal Server Error for any unspecified error. PUT /api/v1/budgets/{id}/archive

Parameters

Parameter Description
id
required: true
The id of the budget.

Response Example

{
  "budgetSpecification": {
    "amount": {
      "currencyCode": "EUR",
      "scale": 2,
      "unscaledValue": 1050
    },
    "archived": null,
    "description": "Spend less on coffee so that I can travel around the world.",
    "filter": {
      "accounts": [
        {
          "id": "325ee4ccf579450ca59d89ee54fa7e40"
        }
      ],
      "categories": [
        {
          "code": "expenses:food.coffee"
        }
      ],
      "freeTextQuery": "Monmouth Coffee",
      "tags": [
        {
          "key": "coffee"
        }
      ]
    },
    "id": "e2b746ed27c542ce846a8d693474df21",
    "name": "Coffee budget",
    "oneOffPeriodicity": {
      "end": 1552395986,
      "start": 1549976786
    },
    "periodicityType": "ONE_OFF",
    "recurringPeriodicity": {
      "periodUnit": "WEEK"
    }
  }
}

Response: ArchiveBudgetResponse

Parameter Description
budgetSpecification
type: BudgetSpecification
required: false
The archived budget.

BudgetSpecification

Parameter Description
amount
type: CurrencyDenominatedAmount
required: false
The target amount for Budget.
archived
type: boolean
required: false
Indicates if the budget has state archived or not.
description
type: string
required: false
The description of the Budget.
filter
type: Filter
required: false
The filter defining the budget and which transactions that is included in it. The configured fields of the filter are applied as logical and operator (intersection).
id
type: string
required: false
The id of the Budget.
name
type: string
required: false
The name of the Budget.
oneOffPeriodicity
type: OneOffPeriodicity
required: false
Periodicity configuration for a ONE_OFF budget.
periodicityType
type: string
required: false
Tells whether the budget is recurring or one off type. Using this field it's possible to see which of the field recurringPeriodicity or oneOffPeriodicity is set.. Values: ONE_OFF, RECURRING
recurringPeriodicity
type: RecurringPeriodicity
required: false
Periodicity configuration for a RECURRING budget.

CurrencyDenominatedAmount

Parameter Description
currencyCode
type: string
required: true
The ISO 4217 currency code of the amount
scale
type: integer
required: true
The scale of the amount.
unscaledValue
type: integer
required: true
The unscaled value of the amount

Filter

Parameter Description
accounts
type: array[BudgetFilterAccount]
required: false
List of included accounts. Applied as logical or (union).
categories
type: array[BudgetFilterCategory]
required: false
List of included categories. Applied as logical or (union).
freeTextQuery
type: string
required: false
Query for a partial transaction description match.
tags
type: array[BudgetFilterTag]
required: false
List of included tags. Applied as logical or (union).

BudgetFilterAccount

Parameter Description
id
type: string
required: false
The account id.

BudgetFilterCategory

Parameter Description
code
type: string
required: false
The category code.

BudgetFilterTag

Parameter Description
key
type: string
required: false
The tag key.

OneOffPeriodicity

Parameter Description
end
type: number
required: true
Budget end expressed as UTC epoch timestamp.
start
type: number
required: true
Budget start expressed as UTC epoch timestamp.

RecurringPeriodicity

Parameter Description
periodUnit
type: string
required: true
Recurring periodicity unit.. Values: WEEK, MONTH, YEAR

Get budget details

Get the specified budget and its periods within the start and end dates. The date parameters are inclusive, thus specifying a date in the middle of a period will include the complete period amounts. Returns 404 Not Found if the budget does not exist. Returns 400 Bad Request if any of the request parameters is incorrect or missing. Returns 500 Internal Server Error for any unspecified error. GET /api/v1/budgets/{id}/details

Parameters

Parameter Description
id
required: true
The id of the budget.

Query Parameters

Parameter Description
start
required: false
Date within the first period expressed as UTC epoch timestamp.
end
required: false
Date within the last period expressed as UTC epoch timestamp.

Response Example

{
  "averageSpentAmount": {
    "currencyCode": "EUR",
    "scale": 2,
    "unscaledValue": 1050
  },
  "budgetPeriods": [
    {
      "end": 1552395986,
      "spentAmount": {
        "currencyCode": "EUR",
        "scale": 2,
        "unscaledValue": 1050
      },
      "start": 1549976786
    }
  ],
  "budgetSpecification": {
    "amount": {
      "currencyCode": "EUR",
      "scale": 2,
      "unscaledValue": 1050
    },
    "archived": null,
    "description": "Spend less on coffee so that I can travel around the world.",
    "filter": {
      "accounts": [
        {
          "id": "325ee4ccf579450ca59d89ee54fa7e40"
        }
      ],
      "categories": [
        {
          "code": "expenses:food.coffee"
        }
      ],
      "freeTextQuery": "Monmouth Coffee",
      "tags": [
        {
          "key": "coffee"
        }
      ]
    },
    "id": "e2b746ed27c542ce846a8d693474df21",
    "name": "Coffee budget",
    "oneOffPeriodicity": {
      "end": 1552395986,
      "start": 1549976786
    },
    "periodicityType": "ONE_OFF",
    "recurringPeriodicity": {
      "periodUnit": "WEEK"
    }
  },
  "end": 1552395986,
  "start": 1549976786,
  "totalSpentAmount": {
    "currencyCode": "EUR",
    "scale": 2,
    "unscaledValue": 1050
  }
}

Response: BudgetDetailsResponse

Parameter Description
averageSpentAmount
type: CurrencyDenominatedAmount
required: false
Average period spending for the listed periods.
budgetPeriods
type: array[BudgetPeriod]
required: false
List of budget periods.
budgetSpecification
type: BudgetSpecification
required: false
The budget.
end
type: number
required: false
Last period end expressed as UTC epoch timestamp.
start
type: number
required: false
First period start expressed as UTC epoch timestamp.
totalSpentAmount
type: CurrencyDenominatedAmount
required: false
Total amount spent within the listed periods.

CurrencyDenominatedAmount

Parameter Description
currencyCode
type: string
required: true
The ISO 4217 currency code of the amount
scale
type: integer
required: true
The scale of the amount.
unscaledValue
type: integer
required: true
The unscaled value of the amount

BudgetPeriod

Parameter Description
end
type: number
required: false
Period end expressed as UTC epoch timestamp.
spentAmount
type: CurrencyDenominatedAmount
required: false
Period spent amount.
start
type: number
required: false
Period start expressed as UTC epoch timestamp.

BudgetSpecification

Parameter Description
amount
type: CurrencyDenominatedAmount
required: false
The target amount for Budget.
archived
type: boolean
required: false
Indicates if the budget has state archived or not.
description
type: string
required: false
The description of the Budget.
filter
type: Filter
required: false
The filter defining the budget and which transactions that is included in it. The configured fields of the filter are applied as logical and operator (intersection).
id
type: string
required: false
The id of the Budget.
name
type: string
required: false
The name of the Budget.
oneOffPeriodicity
type: OneOffPeriodicity
required: false
Periodicity configuration for a ONE_OFF budget.
periodicityType
type: string
required: false
Tells whether the budget is recurring or one off type. Using this field it's possible to see which of the field recurringPeriodicity or oneOffPeriodicity is set.. Values: ONE_OFF, RECURRING
recurringPeriodicity
type: RecurringPeriodicity
required: false
Periodicity configuration for a RECURRING budget.

Filter

Parameter Description
accounts
type: array[BudgetFilterAccount]
required: false
List of included accounts. Applied as logical or (union).
categories
type: array[BudgetFilterCategory]
required: false
List of included categories. Applied as logical or (union).
freeTextQuery
type: string
required: false
Query for a partial transaction description match.
tags
type: array[BudgetFilterTag]
required: false
List of included tags. Applied as logical or (union).

BudgetFilterAccount

Parameter Description
id
type: string
required: false
The account id.

BudgetFilterCategory

Parameter Description
code
type: string
required: false
The category code.

BudgetFilterTag

Parameter Description
key
type: string
required: false
The tag key.

OneOffPeriodicity

Parameter Description
end
type: number
required: true
Budget end expressed as UTC epoch timestamp.
start
type: number
required: true
Budget start expressed as UTC epoch timestamp.

RecurringPeriodicity

Parameter Description
periodUnit
type: string
required: true
Recurring periodicity unit.. Values: WEEK, MONTH, YEAR

Get budget transactions

List all transactions for the specified budget within the start and end date. The date parameters are inclusive. Returns 404 Not Found if the budget does not exist. Returns 400 Bad Request if any of the request parameters is incorrect or missing. Returns 500 Internal Server Error for any unspecified error. GET /api/v1/budgets/{id}/transactions

Parameters

Parameter Description
id
required: true
The id of the budget.

Query Parameters

Parameter Description
start
required: true
Query start date expressed as UTC epoch timestamp.
end
required: true
Query end date expressed as UTC epoch timestamp.

Response Example

{
  "transactions": [
    {
      "accountId": "325ee4ccf579450ca59d89ee54fa7e40",
      "amount": {
        "currencyCode": "EUR",
        "scale": 2,
        "unscaledValue": 1050
      },
      "categoryCode": "expenses:food.coffee",
      "date": 1549976786,
      "description": "Monmouth Coffee Company",
      "dispensableAmount": {
        "currencyCode": "EUR",
        "scale": 2,
        "unscaledValue": 1050
      },
      "id": "e2b746ed27c542ce846a8d693474df21"
    }
  ]
}

Response: BudgetTransactionsResponse

Parameter Description
transactions
type: array[BudgetTransaction]
required: false
List of transactions for a budget.

BudgetTransaction

Parameter Description
accountId
type: string
required: false
The id of the account this transaction belongs to.
amount
type: CurrencyDenominatedAmount
required: false
The transaction amount.
categoryCode
type: string
required: false
Category code.
date
type: number
required: false
Date of the transaction.
description
type: string
required: false
Description of the transaction.
dispensableAmount
type: CurrencyDenominatedAmount
required: false
The dispensable amount. This amount will e.g. be reduced if the account it belongs to has ownership set to 50%.
id
type: string
required: false
The id of the transaction.

CurrencyDenominatedAmount

Parameter Description
currencyCode
type: string
required: true
The ISO 4217 currency code of the amount
scale
type: integer
required: true
The scale of the amount.
unscaledValue
type: integer
required: true
The unscaled value of the amount

Category Service

List categories for a given locale.

Returns all categories for the given locale. The locale is either taken from the authenticated user or from a query parameter, if no user is authenticated. If no user and no query parameter is given, a default locale is used. GET /api/v1/categories

Query Parameters

Parameter Description
locale
required: false
The locale for which to fetch categories.

Response Example

[
  {
    "code": "expenses:food.restaurants",
    "defaultChild": null,
    "id": "7e88d58188ee49749adca59e152324b6",
    "parent": "067fa4c769774ae980435c76be328c0b",
    "primaryName": "Food & Drinks",
    "searchTerms": "food,lunch,snacks",
    "secondaryName": "Restaurants",
    "sortOrder": 45,
    "type": "EXPENSES",
    "typeName": "Expenses"
  }
]

Response: array[Category]

Parameter Description
code
type: string
required: true
Machine readable category code.
defaultChild
type: boolean
required: true
Indicates if this is the default child to be used when categorizing to a primary level category.
id
type: string
required: true
The internal identifier of the category, referenced by e.g. a transaction.
parent
type: string
required: false
The parent internal identifier of this category, or null.
primaryName
type: string
required: false
The primary name of this category.
searchTerms
type: string
required: false
Used by search engine to find transaction with this category.
secondaryName
type: string
required: false
The secondary name of this category.
sortOrder
type: integer
required: true
Sort order for nicer display for the user.
type
type: string
required: true
Type of the category.. Values: INCOME, EXPENSES, TRANSFERS
typeName
type: string
required: true
Type name of the category.

Investment Service

List all the investments for a user.

Returns an object with a list of the authenticated user's portfolios and corresponding financial instruments. GET /api/v1/investments

Query Parameters

Parameter Description
portfolioType
required: false
The portfolio types to select from aggregated investment data. Multiple types are allowed and are passed as: portfolioType=type1&portfolioType=type2. If omitted, everything is selected. Values: ISK, KF, DEPOT, PENSION, OTHER

Response Example

{
  "portfolios": [
    {
      "accountId": "1d764c9f9141434aa23485c03561428d",
      "cashValue": 123,
      "id": "4c72494cc67f472f9f0ec2072600fe93",
      "instruments": [
        {
          "averageAcquisitionPrice": 53,
          "currency": "SEK",
          "id": "50c3e10233ed4048bd48f3a55b5d062a",
          "isin": "US0378331005",
          "marketPlace": "NASDAQ",
          "marketValue": 22917,
          "name": "Apple Inc.",
          "portfolioId": "01f21bc10f2b46abb9b25fccd3dc64eb",
          "price": 76,
          "profit": 6894,
          "quantity": 300,
          "ticker": "AAPL",
          "type": "STOCK",
          "userId": "a52e9890520d4ec38cc0d4526a4cdcbe"
        }
      ],
      "totalProfit": 48673,
      "totalValue": 231924,
      "type": "DEPOT",
      "userId": "a52e9890520d4ec38cc0d4526a4cdcbe"
    }
  ]
}

Response: InvestmentResponse

Parameter Description
portfolios
type: array[Portfolio]
required: false
A list of the user's portfolios.

Portfolio

Parameter Description
accountId
type: string
required: false
The internal identifier of the account which has the portfolio.
cashValue
type: number
required: false
The funds, on this portfolio, available for purchasing instruments, or to be transferred away.
id
type: string
required: false
The internal identifier of the portfolio.
instruments
type: array[Instrument]
required: false
The instruments which this portfolio holds.
totalProfit
type: number
required: false
The total profit of the entire portfolio. This includes both historical (real) profit, and current (potential) profit.
totalValue
type: number
required: false
The total current value of the entire portfolio and all its underlying instruments.
type
type: string
required: false
The type of the portfolio.. Values: ISK, KF, DEPOT, PENSION, OTHER
userId
type: string
required: false
The internal identifier of the user which owns the portfolio.

Instrument

Parameter Description
averageAcquisitionPrice
type: number
required: false
An instrument can be traded multiple times and this is the average acquisition price calculated over all trades.
currency
type: string
required: false
The currency that the instrument is traded in.
id
type: string
required: false
The internal identifier of the instrument.
isin
type: string
required: false
An International Securities Identification Number (ISIN) uniquely identifies a security.
marketPlace
type: string
required: false
The market where the instrument is traded.
marketValue
type: number
required: false
The current market value of the whole instrument. That is, not for a single share but for the entire instrument.
name
type: string
required: false
The name of the instrument, which can be different on different markets.
portfolioId
type: string
required: false
The internal identifier of the portfolio which the instrument belongs to.
price
type: number
required: false
The current market price for one share of the instrument.
profit
type: number
required: false
The total profit for this instrument over all trades.
quantity
type: number
required: false
The number of underlying shares that the user owns of this instrument.
ticker
type: string
required: false
A ticker symbol is an abbreviation used to uniquely identify a stock on a particular stock market.
type
type: string
required: false
The instrument type.. Values: FUND, STOCK, OTHER
userId
type: string
required: false
The internal identifier of the user which owns the instrument.

Loan Service

Get loans

Get all the loans for a user. GET /api/v1/loans

Response Example

{
  "loans": [
    {
      "accountId": "string",
      "amortized": 0,
      "balance": 0,
      "credentialsId": "string",
      "id": "string",
      "initialBalance": 0,
      "initialDate": "string",
      "interest": 0,
      "loanDetails": {
        "accountId": "string",
        "applicants": [
          "string",
          "string"
        ],
        "coApplicant": false,
        "loanSecurity": "string"
      },
      "loanNumber": "string",
      "monthlyAmortization": 0,
      "name": "string",
      "nextDayOfTermsChange": "string",
      "numMonthsBound": 0,
      "providerName": "string",
      "serializedLoanResponse": "string",
      "type": "string",
      "updated": "string",
      "userId": "string",
      "userModifiedType": false
    }
  ],
  "totalLoanAmount": 0,
  "weightedAverageInterestRate": 0
}

Response: LoanResponse

Parameter Description
loans
type: array[Loan]
required: false
totalLoanAmount
type: number
required: false
weightedAverageInterestRate
type: number
required: false

Loan

Parameter Description
accountId
type: string
required: false
amortized
type: number
required: false
balance
type: number
required: false
credentialsId
type: string
required: false
id
type: string
required: false
initialBalance
type: number
required: false
initialDate
type: number
required: false
interest
type: number
required: false
loanDetails
type: LoanDetails
required: false
loanNumber
type: string
required: false
monthlyAmortization
type: number
required: false
name
type: string
required: false
nextDayOfTermsChange
type: number
required: false
numMonthsBound
type: integer
required: false
providerName
type: string
required: false
serializedLoanResponse
type: string
required: false
type
type: string
required: false
updated
type: number
required: false
userId
type: string
required: false
userModifiedType
type: boolean
required: false

LoanDetails

Parameter Description
accountId
type: string
required: false
applicants
type: array[string]
required: false
coApplicant
type: boolean
required: false
loanSecurity
type: string
required: false

List loan events

Lists events that affect the properties of a loan such as interest rate changes. GET /api/v1/loans/events

Response Example

{
  "loanEvents": [
    {
      "accountId": "string",
      "balance": 0,
      "credentials": "string",
      "interest": 0,
      "interestRateChange": 0,
      "loanType": "string",
      "nextDayOfTermsChange": "string",
      "properties": "",
      "provider": "string",
      "timestamp": "string",
      "title": "string",
      "type": "string"
    }
  ]
}

Response: LoanEventsResponse

Parameter Description
loanEvents
type: array[LoanEvent]
required: false

LoanEvent

Parameter Description
accountId
type: string
required: false
balance
type: number
required: false
credentials
type: string
required: false
interest
type: number
required: false
interestRateChange
type: number
required: false
loanType
type: string
required: false
nextDayOfTermsChange
type: number
required: false
properties
type: object
required: false
provider
type: string
required: false
timestamp
type: number
required: false
title
type: string
required: false
type
type: string
required: false

List loan history

Lists historical rates and balances for all loans as well as weighted average calculations for all loans together. GET /api/v1/loans/timelines

Response Example

{
  "loanTimelines": [
    {
      "accountId": "string",
      "balanceTimeline": [
        {
          "date": "string",
          "value": 0
        }
      ],
      "interestRateTimeline": [
        {
          "date": "string",
          "value": 0
        }
      ]
    }
  ],
  "weightedAverageTimeline": [
    {
      "key": "string",
      "value": 0
    }
  ]
}

Response: LoanTimelineResponse

Parameter Description
loanTimelines
type: array[LoanTimeline]
required: false
weightedAverageTimeline
type: array[KVPairStringDouble]
required: false

LoanTimeline

Parameter Description
accountId
type: string
required: false
balanceTimeline
type: array[TemporalValueDouble]
required: false
interestRateTimeline
type: array[TemporalValueDouble]
required: false

TemporalValueDouble

Parameter Description
date
type: number
required: false
value
type: number
required: false

KVPairStringDouble

Parameter Description
key
type: string
required: false
value
type: number
required: false

Monitoring Service

Health check

Returns ok while the Tink API isn't experiencing unexpected disturbances. Returns 503 Service Unavailable if the server is closing down and 500 Internal Server Error for any other error. GET /api/v1/monitoring/healthy

Response: text/plain

successful operation

Ping

Checks the current status of a Tink service and returns pong if the specified service is running. GET /api/v1/monitoring/ping

Query Parameters

Parameter Description
service
required: false
Forwards the ping to another service ("aggregation", "main" and "system"). Defaults to "main". Values: aggregation, system, main

Response: text/plain

successful operation

OAuth Service

Create an authorization for the given user id with requested scopes.

Returns the authorization code. POST /api/v1/oauth/authorization-grant

Form Request Example

NOTE: This data is sent as application/x-www-form-urlencoded, but shown here in json for brevity.

{
  "external_user_id": "256ae77fcbda4bc2b8d0ba94d9c3423d",
  "scope": "accounts:read,transactions:read",
  "user_id": "256ae77fcbda4bc2b8d0ba94d9c3423c"
}

Form Parameters

Parameter Description
user_id
required: true
The User ID
external_user_id
required: false
The external user ID
scope
required: true
The requested OAuth scopes

Response Example

{
  "code": "c50cd6960a6f44ffb701ef60fafa7761"
}

Response: OAuth2AuthorizeResponse

Parameter Description
code
type: string
required: true
The authorization code.

Get an authorization token

Exchange an authorization code or a refresh token for authorization tokens. The authorization tokens are used to access API resources on the end-user's behalf. POST /api/v1/oauth/token

Form Request Example

NOTE: This data is sent as application/x-www-form-urlencoded, but shown here in json for brevity.

{
  "client_id": "256ae77fcbda4bc2b8d0ba94d9c3423c",
  "client_secret": "bdb8477398074160901ce1c8dd5b7848",
  "code": "c50cd6960a6f44ffb701ef60fafa7761",
  "grant_type": "authorization_code",
  "refresh_token": "c45d4e0daea9440aacf3b2aea66f46a8",
  "scope": "user:create,authorization:grant"
}

Form Parameters

Parameter Description
client_id
required: true
The OAuth client ID.
client_secret
required: true
The client secret of your third-party application.
grant_type
required: true
The grant type. Values: authorization_code, refresh_token, client_credentials
code
required: false
The one-time code that was returned from the authorization flow. Can be omitted if refresh token is used.
refresh_token
required: false
The refresh token to be used to get a new access token. Can be omitted if code is used.
scope
required: false
The requested scope when using client credentials.

Response Example

{
  "access_token": "3084989d7eb94d58995217807441bdf4",
  "expires_in": 7200,
  "id_hint": "John Doe",
  "refresh_token": "8bc289f2dd94440bb4561c55e1903845",
  "scope": "transactions:read,accounts:read",
  "token_type": "bearer"
}

Response: OAuth2AuthenticationTokenResponse

Parameter Description
access_token
type: string
required: true
The access token that can be used to access an API resource.
expires_in
type: integer
required: true
The amount of time in seconds for the expiration of the token.
id_hint
type: string
required: false
Human readable information about the identity of user
refresh_token
type: string
required: true
The refresh token that can be used to get a new access token.
scope
type: string
required: true
The scope valid for the returned token.
token_type
type: string
required: true
The type of authorization token returned.

Search Service

Query transactions

Returns a response containing transaction and their corresponding statistics matching the query. POST /api/v1/search

Request Example

{
  "accounts": [
    "87fa44ec11c4426e889a963add92b69e"
  ],
  "categories": [
    "953c4eda24554a61a9653a479e70fc96"
  ],
  "credentials": [
    "18bb1f4636894f3bba8ddcd567d22fbd"
  ],
  "endDate": 1455740874875,
  "externalIds": [
    "953c4eda24554a61a9653a479e70fc96"
  ],
  "includeUpcoming": false,
  "limit": 20,
  "offset": 20,
  "order": "ASC",
  "queryString": "Food this week",
  "sort": "DATE",
  "startDate": 1455740874875
}

Request Body: SearchQuery

The search query.

Parameter Description
accounts
type: array[string]
required: false
A list of account IDs to filter by.
categories
type: array[string]
required: false
A list of category IDs to filter by. Could either be leaf node categories, such as the category ID corresponding to expenses:food.restaurants, or groups of categories, such as the category ID corresponding to expenses:food.
credentials
type: array[string]
required: false
A list of credential IDs to filter by.
endDate
type: number
required: false
The end date of the result.
externalIds
type: array[string]
required: false
A list of external IDs to filter by.
includeUpcoming
type: boolean
required: false
Indicates if result should include upcoming transactions.
limit
type: integer
required: false
The limit for the result, used for paging.
offset
type: integer
required: false
The offset for the result, used for paging.
order
type: string
required: false
The order of the result.. Values: ASC, DESC
queryString
type: string
required: false
The string query.
sort
type: string
required: false
The sort order of the result.. Values: SCORE, DATE, ACCOUNT, DESCRIPTION, AMOUNT, CATEGORY
startDate
type: number
required: false
The start date of the result.

Response Example

{
  "count": 110,
  "net": 1288,
  "periodAmounts": [
    {
      "key": "string",
      "value": 0
    }
  ],
  "query": {
    "accounts": [
      "87fa44ec11c4426e889a963add92b69e"
    ],
    "categories": [
      "953c4eda24554a61a9653a479e70fc96"
    ],
    "credentials": [
      "18bb1f4636894f3bba8ddcd567d22fbd"
    ],
    "endDate": 1455740874875,
    "externalIds": [
      "953c4eda24554a61a9653a479e70fc96"
    ],
    "includeUpcoming": false,
    "limit": 20,
    "offset": 20,
    "order": "ASC",
    "queryString": "Food this week",
    "sort": "DATE",
    "startDate": 1455740874875
  },
  "results": [
    {
      "budget": {
        "budgetedAmount": 0,
        "categoryId": "string",
        "currentAmount": 0,
        "historicalAmounts": [
          {
            "description": "fe9e199c2ca94c12baf1f3eb4a4122de",
            "payload": "690667930d7e4f2ba0d9aa5f7d2a1941",
            "period": "2014-12-15",
            "resolution": "DAILY",
            "type": "expenses-by-category",
            "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
            "value": 1298
          }
        ],
        "id": "string",
        "suggestedAmount": 0,
        "userId": "string"
      },
      "transaction": {
        "accountId": "3fe2d96efacd4dc5994404a950f238a9",
        "amount": 34,
        "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
        "categoryType": "EXPENSES",
        "credentialsId (Deprecated)": "65bc7a41a66e4ad1aad199bbfb3c5098",
        "currencyDenominatedAmount": {
          "currencyCode": "EUR",
          "scale": 2,
          "unscaledValue": 1050
        },
        "currencyDenominatedOriginalAmount": {
          "currencyCode": "EUR",
          "scale": 2,
          "unscaledValue": 1050
        },
        "date": 1455740874875,
        "description": "Stadium Sergelg Stockholm",
        "dispensableAmount": 0,
        "id": "79c6c9c27d6e42489e888e08d27205a1",
        "lastModified": 1455740874875,
        "merchantId": "ba3f9312fa7d442abde61ca419877fbf",
        "notes": "Delicious #cake #wedding",
        "originalAmount": 34,
        "originalDate": 1455740874875,
        "originalDescription": "Stadium Sergelg Stockholm",
        "partnerPayload": {},
        "parts": [
          {
            "amount": 34,
            "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
            "counterpartDescription": "Stadium Sergelg Stockholm",
            "counterpartId": "79c6c9c27d6e42489e888e08d27205a1",
            "counterpartTransactionAmount": 0,
            "counterpartTransactionId": "d030a7b0840547428aa2fd07026e9a77",
            "date": 1455740874875,
            "id": "7303ff128531463bbed358bbf9e23f31",
            "lastModified": 1455740874875
          }
        ],
        "payload": {},
        "pending": false,
        "timestamp": 1464543093494,
        "type": "CREDIT_CARD",
        "upcoming": false,
        "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
        "userModified": false
      },
      "type": "TRANSACTION"
    }
  ]
}

Response: SearchResponse

Parameter Description
count
type: integer
required: true
Number of results returned.
net
type: number
required: true
The transaction amount net of the result. Will only include the amounts from transactions which has the same currency as the user to who they belong.
periodAmounts
type: array[StringDoublePair]
required: true
Key value object holding periods and statistics values for result with the period specified in query.
query
type: SearchQuery
required: true
The query executed.
results
type: array[SearchResult]
required: true
The search result.

StringDoublePair

Parameter Description
key
type: string
required: false
value
type: number
required: false

SearchQuery

Parameter Description
accounts
type: array[string]
required: false
A list of account IDs to filter by.
categories
type: array[string]
required: false
A list of category IDs to filter by. Could either be leaf node categories, such as the category ID corresponding to expenses:food.restaurants, or groups of categories, such as the category ID corresponding to expenses:food.
credentials
type: array[string]
required: false
A list of credential IDs to filter by.
endDate
type: number
required: false
The end date of the result.
externalIds
type: array[string]
required: false
A list of external IDs to filter by.
includeUpcoming
type: boolean
required: false
Indicates if result should include upcoming transactions.
limit
type: integer
required: false
The limit for the result, used for paging.
offset
type: integer
required: false
The offset for the result, used for paging.
order
type: string
required: false
The order of the result.. Values: ASC, DESC
queryString
type: string
required: false
The string query.
sort
type: string
required: false
The sort order of the result.. Values: SCORE, DATE, ACCOUNT, DESCRIPTION, AMOUNT, CATEGORY
startDate
type: number
required: false
The start date of the result.

SearchResult

Parameter Description
budget
type: Budget
required: false
transaction
type: Transaction
required: false
The transactions resulting from the query.
type
type: string
required: true
The search type.. Values: STATEMENT, TRANSACTION, CATEGORY, BUDGET, GOAL, SUGGESTION

Budget

Parameter Description
budgetedAmount
type: number
required: false
categoryId
type: string
required: false
currentAmount
type: number
required: false
historicalAmounts
type: array[Statistic]
required: false
id
type: string
required: false
suggestedAmount
type: number
required: false
userId
type: string
required: false

Statistic

Parameter Description
description
type: string
required: true
Identifier of the data the statistic represents.
payload
type: string
required: false
Secondary identifier of the data the statistic represent.
period
type: string
required: true
The statistic's period, depends on its resolution. One of: year, month, week or day. Format: '2014', '2014-02', '2014:45' or '2014-02-12'
resolution
type: string
required: true
Resolution for the statistics.. Values: DAILY, MONTHLY, MONTHLY_ADJUSTED, YEARLY, ALL, WEEKLY
type
type: string
required: true
The statistic's type.
userId
type: string
required: true
The internal identifier of the user that the statistics belongs to.
value
type: number
required: true
The value of the statistics for this type, period, and description.

Transaction

Parameter Description
accountId
type: string
required: true
The internal identifier of the account that the transaction belongs to.
amount
type: number
required: true
The amount of the transaction. This can be modified by the user.
categoryId
type: string
required: true
The category of the transaction. This can be modified by the user.
categoryType
type: string
required: true
The category type of the transaction.. Values: INCOME, EXPENSES, TRANSFERS
credentialsId (Deprecated)
type: string
required: true
The internal identifier of the credentials that the transaction belongs to. This is deprecated. This information can be accessed through the account. Account can be located with the transactions accountId.
currencyDenominatedAmount
type: CurrencyDenominatedAmount
required: false
The amount of the transaction represented as a scale and unscaled value together with the ISO 4217 currency code of the amount. The amount can be modified by the user but not the currency code.
currencyDenominatedOriginalAmount
type: CurrencyDenominatedAmount
required: false
The original amount that was received from the provider, before the user changed it. The amount is represented as a scale and unscaled value together with the ISO 4217 currency code of the amount.
date
type: number
required: true
The date the transaction was executed. This can be modified by the user.
description
type: string
required: true
The description of the transaction. This can be modified by the user.
dispensableAmount
type: number
required: false
The dispensable amount of the transaction.
id
type: string
required: true
The internal identifier of the transaction.
lastModified
type: number
required: true
The date the transaction was last modified by the user.
merchantId
type: string
required: false
The internal identifier of the merchant that the transaction belongs to. If available.
notes
type: string
required: true
A free-text field modifiable by the user. Any 'word' (whitespace separated), prefixed with a #, is considered a tag. These tags becomes searchable.
originalAmount
type: number
required: true
The original amount that was received from the provider, before the user changed it.
originalDate
type: number
required: true
The original date that was received from the provider, before the user changed it.
originalDescription
type: string
required: true
The original description that was received from the provider, before the user changed it.
partnerPayload
type: object
required: false
The payload that was previously ingested on the Connector API.
parts
type: array[TransactionPart]
required: false
Transaction parts (Beta). Available if the transaction is divided into more than one part.
payload
type: object
required: false
Meta data about the transaction, in key value format with Strings.
pending
type: boolean
required: true
Indicates if this transaction has been settled or is still pending.
timestamp
type: integer
required: true
The timestamp of when the transaction was first saved to database.
type
type: string
required: true
The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL
upcoming
type: boolean
required: false
Indicates if this is an upcoming transaction not booked yet.
userId
type: string
required: true
The internal identifier of the user that the transaction belongs to.
userModified
type: boolean
required: false

CurrencyDenominatedAmount

Parameter Description
currencyCode
type: string
required: true
The ISO 4217 currency code of the amount
scale
type: integer
required: true
The scale of the amount.
unscaledValue
type: integer
required: true
The unscaled value of the amount

TransactionPart

Parameter Description
amount
type: number
required: true
The amount of the transaction part.
categoryId
type: string
required: true
The category of the transaction part.
counterpartDescription
type: string
required: true
The description of the transaction containing the counterpart.
counterpartId
type: string
required: true
The id of the counterpart. The counterpart is a transaction part in another transaction
counterpartTransactionAmount
type: number
required: false
counterpartTransactionId
type: string
required: true
The id of the transaction containing the counterpart.
date
type: number
required: true
The date the transaction part was created.
id
type: string
required: true
The id of the transaction part.
lastModified
type: number
required: true
The date the transaction part was last modified.
Status Code Description
200 Successful operation.
400 The payload does not pass validation.

Statistics Service

Query statistics

Queries statistics POST /api/v1/statistics/query

Request Example

{
  "description": "fe9e199c2ca94c12baf1f3eb4a4122de",
  "padResultUntilToday": null,
  "periods": [
    "2014-02-11",
    "2014-02-12"
  ],
  "resolution": "DAILY",
  "types": [
    "expenses-by-category"
  ]
}

Request Body: StatisticQuery

The query object

Parameter Description
description
type: string
required: false
Identifier of the data the statistic represents. This could for example be a category ID.
padResultUntilToday
type: boolean
required: false
Indicates if the result should be flat filled until the period of today.
periods
type: array[string]
required: false
Time periods for the statistics: year, month, week or day. Format: '2014', '2014-02', 2014:45 or '2014-02-12'
resolution
type: string
required: false
Resolution for the statistics. Note that monthly statistics will be calculated only with the resolution that the user has in the user settings (MONTHLY, MONTHLY_ADJUSTED), and not for both.. Values: DAILY, MONTHLY, MONTHLY_ADJUSTED, YEARLY, ALL, WEEKLY
types
type: array[string]
required: false
A list of types of statistics. See Statistics for type information.

Response Example

[
  {
    "description": "fe9e199c2ca94c12baf1f3eb4a4122de",
    "payload": "690667930d7e4f2ba0d9aa5f7d2a1941",
    "period": "2014-12-15",
    "resolution": "DAILY",
    "type": "expenses-by-category",
    "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
    "value": 1298
  }
]

Response: array[Statistic]

Parameter Description
description
type: string
required: true
Identifier of the data the statistic represents.
payload
type: string
required: false
Secondary identifier of the data the statistic represent.
period
type: string
required: true
The statistic's period, depends on its resolution. One of: year, month, week or day. Format: '2014', '2014-02', '2014:45' or '2014-02-12'
resolution
type: string
required: true
Resolution for the statistics.. Values: DAILY, MONTHLY, MONTHLY_ADJUSTED, YEARLY, ALL, WEEKLY
type
type: string
required: true
The statistic's type.
userId
type: string
required: true
The internal identifier of the user that the statistics belongs to.
value
type: number
required: true
The value of the statistics for this type, period, and description.
Status Code Description
200 Successful operation.
400 The payload does not pass validation.

Transaction Service

Get one transaction

Returns a transaction matching the requested id GET /api/v1/transactions/{id}

Parameters

Parameter Description
id
required: true
The id of the transaction

Response Example

{
  "accountId": "3fe2d96efacd4dc5994404a950f238a9",
  "amount": 34,
  "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
  "categoryType": "EXPENSES",
  "credentialsId (Deprecated)": "65bc7a41a66e4ad1aad199bbfb3c5098",
  "currencyDenominatedAmount": {
    "currencyCode": "EUR",
    "scale": 2,
    "unscaledValue": 1050
  },
  "currencyDenominatedOriginalAmount": {
    "currencyCode": "EUR",
    "scale": 2,
    "unscaledValue": 1050
  },
  "date": 1455740874875,
  "description": "Stadium Sergelg Stockholm",
  "dispensableAmount": 0,
  "id": "79c6c9c27d6e42489e888e08d27205a1",
  "lastModified": 1455740874875,
  "merchantId": "ba3f9312fa7d442abde61ca419877fbf",
  "notes": "Delicious #cake #wedding",
  "originalAmount": 34,
  "originalDate": 1455740874875,
  "originalDescription": "Stadium Sergelg Stockholm",
  "partnerPayload": {},
  "parts": [
    {
      "amount": 34,
      "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
      "counterpartDescription": "Stadium Sergelg Stockholm",
      "counterpartId": "79c6c9c27d6e42489e888e08d27205a1",
      "counterpartTransactionAmount": 0,
      "counterpartTransactionId": "d030a7b0840547428aa2fd07026e9a77",
      "date": 1455740874875,
      "id": "7303ff128531463bbed358bbf9e23f31",
      "lastModified": 1455740874875
    }
  ],
  "payload": {},
  "pending": false,
  "timestamp": 1464543093494,
  "type": "CREDIT_CARD",
  "upcoming": false,
  "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
  "userModified": false
}

Response: Transaction

Parameter Description
accountId
type: string
required: true
The internal identifier of the account that the transaction belongs to.
amount
type: number
required: true
The amount of the transaction. This can be modified by the user.
categoryId
type: string
required: true
The category of the transaction. This can be modified by the user.
categoryType
type: string
required: true
The category type of the transaction.. Values: INCOME, EXPENSES, TRANSFERS
credentialsId (Deprecated)
type: string
required: true
The internal identifier of the credentials that the transaction belongs to. This is deprecated. This information can be accessed through the account. Account can be located with the transactions accountId.
currencyDenominatedAmount
type: CurrencyDenominatedAmount
required: false
The amount of the transaction represented as a scale and unscaled value together with the ISO 4217 currency code of the amount. The amount can be modified by the user but not the currency code.
currencyDenominatedOriginalAmount
type: CurrencyDenominatedAmount
required: false
The original amount that was received from the provider, before the user changed it. The amount is represented as a scale and unscaled value together with the ISO 4217 currency code of the amount.
date
type: number
required: true
The date the transaction was executed. This can be modified by the user.
description
type: string
required: true
The description of the transaction. This can be modified by the user.
dispensableAmount
type: number
required: false
The dispensable amount of the transaction.
id
type: string
required: true
The internal identifier of the transaction.
lastModified
type: number
required: true
The date the transaction was last modified by the user.
merchantId
type: string
required: false
The internal identifier of the merchant that the transaction belongs to. If available.
notes
type: string
required: true
A free-text field modifiable by the user. Any 'word' (whitespace separated), prefixed with a #, is considered a tag. These tags becomes searchable.
originalAmount
type: number
required: true
The original amount that was received from the provider, before the user changed it.
originalDate
type: number
required: true
The original date that was received from the provider, before the user changed it.
originalDescription
type: string
required: true
The original description that was received from the provider, before the user changed it.
partnerPayload
type: object
required: false
The payload that was previously ingested on the Connector API.
parts
type: array[TransactionPart]
required: false
Transaction parts (Beta). Available if the transaction is divided into more than one part.
payload
type: object
required: false
Meta data about the transaction, in key value format with Strings.
pending
type: boolean
required: true
Indicates if this transaction has been settled or is still pending.
timestamp
type: integer
required: true
The timestamp of when the transaction was first saved to database.
type
type: string
required: true
The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL
upcoming
type: boolean
required: false
Indicates if this is an upcoming transaction not booked yet.
userId
type: string
required: true
The internal identifier of the user that the transaction belongs to.
userModified
type: boolean
required: false

CurrencyDenominatedAmount

Parameter Description
currencyCode
type: string
required: true
The ISO 4217 currency code of the amount
scale
type: integer
required: true
The scale of the amount.
unscaledValue
type: integer
required: true
The unscaled value of the amount

TransactionPart

Parameter Description
amount
type: number
required: true
The amount of the transaction part.
categoryId
type: string
required: true
The category of the transaction part.
counterpartDescription
type: string
required: true
The description of the transaction containing the counterpart.
counterpartId
type: string
required: true
The id of the counterpart. The counterpart is a transaction part in another transaction
counterpartTransactionAmount
type: number
required: false
counterpartTransactionId
type: string
required: true
The id of the transaction containing the counterpart.
date
type: number
required: true
The date the transaction part was created.
id
type: string
required: true
The id of the transaction part.
lastModified
type: number
required: true
The date the transaction part was last modified.
Status Code Description
200 Successful operation.
404 Transaction not found.

Get counterpart suggestions (Beta)

Returns suggestions for potential counterpart expenses for a reimbursement. GET /api/v1/transactions/{id}/link/suggest

Parameters

Parameter Description
id
required: true
The id of the transaction to get suggestions for

Query Parameters

Parameter Description
limit
required: false
Max number of suggestions returned. Values: Between 0 and 100.

Response Example

{
  "limit": 0,
  "suggestedCounterpartTransactions": [
    {
      "accountId": "3fe2d96efacd4dc5994404a950f238a9",
      "amount": 34,
      "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
      "categoryType": "EXPENSES",
      "credentialsId (Deprecated)": "65bc7a41a66e4ad1aad199bbfb3c5098",
      "currencyDenominatedAmount": {
        "currencyCode": "EUR",
        "scale": 2,
        "unscaledValue": 1050
      },
      "currencyDenominatedOriginalAmount": {
        "currencyCode": "EUR",
        "scale": 2,
        "unscaledValue": 1050
      },
      "date": 1455740874875,
      "description": "Stadium Sergelg Stockholm",
      "dispensableAmount": 0,
      "id": "79c6c9c27d6e42489e888e08d27205a1",
      "lastModified": 1455740874875,
      "merchantId": "ba3f9312fa7d442abde61ca419877fbf",
      "notes": "Delicious #cake #wedding",
      "originalAmount": 34,
      "originalDate": 1455740874875,
      "originalDescription": "Stadium Sergelg Stockholm",
      "partnerPayload": {},
      "parts": [
        {
          "amount": 34,
          "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
          "counterpartDescription": "Stadium Sergelg Stockholm",
          "counterpartId": "79c6c9c27d6e42489e888e08d27205a1",
          "counterpartTransactionAmount": 0,
          "counterpartTransactionId": "d030a7b0840547428aa2fd07026e9a77",
          "date": 1455740874875,
          "id": "7303ff128531463bbed358bbf9e23f31",
          "lastModified": 1455740874875
        }
      ],
      "payload": {},
      "pending": false,
      "timestamp": 1464543093494,
      "type": "CREDIT_CARD",
      "upcoming": false,
      "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
      "userModified": false
    }
  ],
  "transactionId": "string"
}

Response: TransactionLinkSuggestionResponse

Parameter Description
limit
type: integer
required: false
The maximum amount of suggestions requested to be returned.
suggestedCounterpartTransactions
type: array[Transaction]
required: false
Suggested counterpart transactions.
transactionId
type: string
required: false
The id of the transaction to find suggestions for.

Transaction

Parameter Description
accountId
type: string
required: true
The internal identifier of the account that the transaction belongs to.
amount
type: number
required: true
The amount of the transaction. This can be modified by the user.
categoryId
type: string
required: true
The category of the transaction. This can be modified by the user.
categoryType
type: string
required: true
The category type of the transaction.. Values: INCOME, EXPENSES, TRANSFERS
credentialsId (Deprecated)
type: string
required: true
The internal identifier of the credentials that the transaction belongs to. This is deprecated. This information can be accessed through the account. Account can be located with the transactions accountId.
currencyDenominatedAmount
type: CurrencyDenominatedAmount
required: false
The amount of the transaction represented as a scale and unscaled value together with the ISO 4217 currency code of the amount. The amount can be modified by the user but not the currency code.
currencyDenominatedOriginalAmount
type: CurrencyDenominatedAmount
required: false
The original amount that was received from the provider, before the user changed it. The amount is represented as a scale and unscaled value together with the ISO 4217 currency code of the amount.
date
type: number
required: true
The date the transaction was executed. This can be modified by the user.
description
type: string
required: true
The description of the transaction. This can be modified by the user.
dispensableAmount
type: number
required: false
The dispensable amount of the transaction.
id
type: string
required: true
The internal identifier of the transaction.
lastModified
type: number
required: true
The date the transaction was last modified by the user.
merchantId
type: string
required: false
The internal identifier of the merchant that the transaction belongs to. If available.
notes
type: string
required: true
A free-text field modifiable by the user. Any 'word' (whitespace separated), prefixed with a #, is considered a tag. These tags becomes searchable.
originalAmount
type: number
required: true
The original amount that was received from the provider, before the user changed it.
originalDate
type: number
required: true
The original date that was received from the provider, before the user changed it.
originalDescription
type: string
required: true
The original description that was received from the provider, before the user changed it.
partnerPayload
type: object
required: false
The payload that was previously ingested on the Connector API.
parts
type: array[TransactionPart]
required: false
Transaction parts (Beta). Available if the transaction is divided into more than one part.
payload
type: object
required: false
Meta data about the transaction, in key value format with Strings.
pending
type: boolean
required: true
Indicates if this transaction has been settled or is still pending.
timestamp
type: integer
required: true
The timestamp of when the transaction was first saved to database.
type
type: string
required: true
The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL
upcoming
type: boolean
required: false
Indicates if this is an upcoming transaction not booked yet.
userId
type: string
required: true
The internal identifier of the user that the transaction belongs to.
userModified
type: boolean
required: false

CurrencyDenominatedAmount

Parameter Description
currencyCode
type: string
required: true
The ISO 4217 currency code of the amount
scale
type: integer
required: true
The scale of the amount.
unscaledValue
type: integer
required: true
The unscaled value of the amount

TransactionPart

Parameter Description
amount
type: number
required: true
The amount of the transaction part.
categoryId
type: string
required: true
The category of the transaction part.
counterpartDescription
type: string
required: true
The description of the transaction containing the counterpart.
counterpartId
type: string
required: true
The id of the counterpart. The counterpart is a transaction part in another transaction
counterpartTransactionAmount
type: number
required: false
counterpartTransactionId
type: string
required: true
The id of the transaction containing the counterpart.
date
type: number
required: true
The date the transaction part was created.
id
type: string
required: true
The id of the transaction part.
lastModified
type: number
required: true
The date the transaction part was last modified.
Status Code Description
200 The suggestions were successfully returned.
400 The transaction id or suggest limit was invalid.
404 The transaction was not found.

Link two transactions, creating a transaction part for each transaction and netting out the amounts. The transactions are required to have different signs (i.e. one income and one expense). If one transaction is -300 and the other is +100, the common disposable amount is 100. POST /api/v1/transactions/{id}/link/{counterpartTransactionId}

Request Example

{
  "amount": -90
}

Parameters

Parameter Description
id
required: true
The id of the first transaction to link.
counterpartTransactionId
required: true
The id of the other transaction (the counterpart) to link.

Request Body: LinkTransactionsRequest

Object holding the required amount for transaction linking

Parameter Description
amount
type: number
required: false
The amount of the transaction part. Must be same sign as the transaction. If not specified the common disposable amount will be used.

Response Example

{
  "counterpartTransaction": {
    "accountId": "3fe2d96efacd4dc5994404a950f238a9",
    "amount": 34,
    "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
    "categoryType": "EXPENSES",
    "credentialsId (Deprecated)": "65bc7a41a66e4ad1aad199bbfb3c5098",
    "currencyDenominatedAmount": {
      "currencyCode": "EUR",
      "scale": 2,
      "unscaledValue": 1050
    },
    "currencyDenominatedOriginalAmount": {
      "currencyCode": "EUR",
      "scale": 2,
      "unscaledValue": 1050
    },
    "date": 1455740874875,
    "description": "Stadium Sergelg Stockholm",
    "dispensableAmount": 0,
    "id": "79c6c9c27d6e42489e888e08d27205a1",
    "lastModified": 1455740874875,
    "merchantId": "ba3f9312fa7d442abde61ca419877fbf",
    "notes": "Delicious #cake #wedding",
    "originalAmount": 34,
    "originalDate": 1455740874875,
    "originalDescription": "Stadium Sergelg Stockholm",
    "partnerPayload": {},
    "parts": [
      {
        "amount": 34,
        "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
        "counterpartDescription": "Stadium Sergelg Stockholm",
        "counterpartId": "79c6c9c27d6e42489e888e08d27205a1",
        "counterpartTransactionAmount": 0,
        "counterpartTransactionId": "d030a7b0840547428aa2fd07026e9a77",
        "date": 1455740874875,
        "id": "7303ff128531463bbed358bbf9e23f31",
        "lastModified": 1455740874875
      }
    ],
    "payload": {},
    "pending": false,
    "timestamp": 1464543093494,
    "type": "CREDIT_CARD",
    "upcoming": false,
    "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
    "userModified": false
  },
  "transaction": {
    "accountId": "3fe2d96efacd4dc5994404a950f238a9",
    "amount": 34,
    "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
    "categoryType": "EXPENSES",
    "credentialsId (Deprecated)": "65bc7a41a66e4ad1aad199bbfb3c5098",
    "currencyDenominatedAmount": {
      "currencyCode": "EUR",
      "scale": 2,
      "unscaledValue": 1050
    },
    "currencyDenominatedOriginalAmount": {
      "currencyCode": "EUR",
      "scale": 2,
      "unscaledValue": 1050
    },
    "date": 1455740874875,
    "description": "Stadium Sergelg Stockholm",
    "dispensableAmount": 0,
    "id": "79c6c9c27d6e42489e888e08d27205a1",
    "lastModified": 1455740874875,
    "merchantId": "ba3f9312fa7d442abde61ca419877fbf",
    "notes": "Delicious #cake #wedding",
    "originalAmount": 34,
    "originalDate": 1455740874875,
    "originalDescription": "Stadium Sergelg Stockholm",
    "partnerPayload": {},
    "parts": [
      {
        "amount": 34,
        "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
        "counterpartDescription": "Stadium Sergelg Stockholm",
        "counterpartId": "79c6c9c27d6e42489e888e08d27205a1",
        "counterpartTransactionAmount": 0,
        "counterpartTransactionId": "d030a7b0840547428aa2fd07026e9a77",
        "date": 1455740874875,
        "id": "7303ff128531463bbed358bbf9e23f31",
        "lastModified": 1455740874875
      }
    ],
    "payload": {},
    "pending": false,
    "timestamp": 1464543093494,
    "type": "CREDIT_CARD",
    "upcoming": false,
    "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
    "userModified": false
  }
}

Response: LinkTransactionsResponse

Parameter Description
counterpartTransaction
type: Transaction
required: true
The counterpart transaction.
transaction
type: Transaction
required: true
The primary transaction.

Transaction

Parameter Description
accountId
type: string
required: true
The internal identifier of the account that the transaction belongs to.
amount
type: number
required: true
The amount of the transaction. This can be modified by the user.
categoryId
type: string
required: true
The category of the transaction. This can be modified by the user.
categoryType
type: string
required: true
The category type of the transaction.. Values: INCOME, EXPENSES, TRANSFERS
credentialsId (Deprecated)
type: string
required: true
The internal identifier of the credentials that the transaction belongs to. This is deprecated. This information can be accessed through the account. Account can be located with the transactions accountId.
currencyDenominatedAmount
type: CurrencyDenominatedAmount
required: false
The amount of the transaction represented as a scale and unscaled value together with the ISO 4217 currency code of the amount. The amount can be modified by the user but not the currency code.
currencyDenominatedOriginalAmount
type: CurrencyDenominatedAmount
required: false
The original amount that was received from the provider, before the user changed it. The amount is represented as a scale and unscaled value together with the ISO 4217 currency code of the amount.
date
type: number
required: true
The date the transaction was executed. This can be modified by the user.
description
type: string
required: true
The description of the transaction. This can be modified by the user.
dispensableAmount
type: number
required: false
The dispensable amount of the transaction.
id
type: string
required: true
The internal identifier of the transaction.
lastModified
type: number
required: true
The date the transaction was last modified by the user.
merchantId
type: string
required: false
The internal identifier of the merchant that the transaction belongs to. If available.
notes
type: string
required: true
A free-text field modifiable by the user. Any 'word' (whitespace separated), prefixed with a #, is considered a tag. These tags becomes searchable.
originalAmount
type: number
required: true
The original amount that was received from the provider, before the user changed it.
originalDate
type: number
required: true
The original date that was received from the provider, before the user changed it.
originalDescription
type: string
required: true
The original description that was received from the provider, before the user changed it.
partnerPayload
type: object
required: false
The payload that was previously ingested on the Connector API.
parts
type: array[TransactionPart]
required: false
Transaction parts (Beta). Available if the transaction is divided into more than one part.
payload
type: object
required: false
Meta data about the transaction, in key value format with Strings.
pending
type: boolean
required: true
Indicates if this transaction has been settled or is still pending.
timestamp
type: integer
required: true
The timestamp of when the transaction was first saved to database.
type
type: string
required: true
The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL
upcoming
type: boolean
required: false
Indicates if this is an upcoming transaction not booked yet.
userId
type: string
required: true
The internal identifier of the user that the transaction belongs to.
userModified
type: boolean
required: false

CurrencyDenominatedAmount

Parameter Description
currencyCode
type: string
required: true
The ISO 4217 currency code of the amount
scale
type: integer
required: true
The scale of the amount.
unscaledValue
type: integer
required: true
The unscaled value of the amount

TransactionPart

Parameter Description
amount
type: number
required: true
The amount of the transaction part.
categoryId
type: string
required: true
The category of the transaction part.
counterpartDescription
type: string
required: true
The description of the transaction containing the counterpart.
counterpartId
type: string
required: true
The id of the counterpart. The counterpart is a transaction part in another transaction
counterpartTransactionAmount
type: number
required: false
counterpartTransactionId
type: string
required: true
The id of the transaction containing the counterpart.
date
type: number
required: true
The date the transaction part was created.
id
type: string
required: true
The id of the transaction part.
lastModified
type: number
required: true
The date the transaction part was last modified.
Status Code Description
200 The transactions were successfully linked and returned.
400 The transaction ids were invalid.
404 The transaction or the counterpart transaction was not found.
409 The transactions were already linked.
412 The transactions had the same signum, the part amount had a signum different from the transaction or the part amount is bigger than the dispensable amount.

Delete transaction part (Beta)

If the part is linked to another transaction, the bilateral link is removed as well (i.e. the counterpart will be removed too, if found). DELETE /api/v1/transactions/{id}/part/{partId}

Parameters

Parameter Description
id
required: true
The id of the transaction to which the part belongs to.
partId
required: true
The part id to delete.

Response Example

{
  "counterpartTransaction": {
    "accountId": "3fe2d96efacd4dc5994404a950f238a9",
    "amount": 34,
    "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
    "categoryType": "EXPENSES",
    "credentialsId (Deprecated)": "65bc7a41a66e4ad1aad199bbfb3c5098",
    "currencyDenominatedAmount": {
      "currencyCode": "EUR",
      "scale": 2,
      "unscaledValue": 1050
    },
    "currencyDenominatedOriginalAmount": {
      "currencyCode": "EUR",
      "scale": 2,
      "unscaledValue": 1050
    },
    "date": 1455740874875,
    "description": "Stadium Sergelg Stockholm",
    "dispensableAmount": 0,
    "id": "79c6c9c27d6e42489e888e08d27205a1",
    "lastModified": 1455740874875,
    "merchantId": "ba3f9312fa7d442abde61ca419877fbf",
    "notes": "Delicious #cake #wedding",
    "originalAmount": 34,
    "originalDate": 1455740874875,
    "originalDescription": "Stadium Sergelg Stockholm",
    "partnerPayload": {},
    "parts": [
      {
        "amount": 34,
        "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
        "counterpartDescription": "Stadium Sergelg Stockholm",
        "counterpartId": "79c6c9c27d6e42489e888e08d27205a1",
        "counterpartTransactionAmount": 0,
        "counterpartTransactionId": "d030a7b0840547428aa2fd07026e9a77",
        "date": 1455740874875,
        "id": "7303ff128531463bbed358bbf9e23f31",
        "lastModified": 1455740874875
      }
    ],
    "payload": {},
    "pending": false,
    "timestamp": 1464543093494,
    "type": "CREDIT_CARD",
    "upcoming": false,
    "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
    "userModified": false
  },
  "transaction": {
    "accountId": "3fe2d96efacd4dc5994404a950f238a9",
    "amount": 34,
    "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
    "categoryType": "EXPENSES",
    "credentialsId (Deprecated)": "65bc7a41a66e4ad1aad199bbfb3c5098",
    "currencyDenominatedAmount": {
      "currencyCode": "EUR",
      "scale": 2,
      "unscaledValue": 1050
    },
    "currencyDenominatedOriginalAmount": {
      "currencyCode": "EUR",
      "scale": 2,
      "unscaledValue": 1050
    },
    "date": 1455740874875,
    "description": "Stadium Sergelg Stockholm",
    "dispensableAmount": 0,
    "id": "79c6c9c27d6e42489e888e08d27205a1",
    "lastModified": 1455740874875,
    "merchantId": "ba3f9312fa7d442abde61ca419877fbf",
    "notes": "Delicious #cake #wedding",
    "originalAmount": 34,
    "originalDate": 1455740874875,
    "originalDescription": "Stadium Sergelg Stockholm",
    "partnerPayload": {},
    "parts": [
      {
        "amount": 34,
        "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
        "counterpartDescription": "Stadium Sergelg Stockholm",
        "counterpartId": "79c6c9c27d6e42489e888e08d27205a1",
        "counterpartTransactionAmount": 0,
        "counterpartTransactionId": "d030a7b0840547428aa2fd07026e9a77",
        "date": 1455740874875,
        "id": "7303ff128531463bbed358bbf9e23f31",
        "lastModified": 1455740874875
      }
    ],
    "payload": {},
    "pending": false,
    "timestamp": 1464543093494,
    "type": "CREDIT_CARD",
    "upcoming": false,
    "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
    "userModified": false
  }
}

Response: DeleteTransactionPartResponse

Parameter Description
counterpartTransaction
type: Transaction
required: false
Counterpart transaction affected due to bilateral link being removed.
transaction
type: Transaction
required: true
The transaction to which the part belonged.

Transaction

Parameter Description
accountId
type: string
required: true
The internal identifier of the account that the transaction belongs to.
amount
type: number
required: true
The amount of the transaction. This can be modified by the user.
categoryId
type: string
required: true
The category of the transaction. This can be modified by the user.
categoryType
type: string
required: true
The category type of the transaction.. Values: INCOME, EXPENSES, TRANSFERS
credentialsId (Deprecated)
type: string
required: true
The internal identifier of the credentials that the transaction belongs to. This is deprecated. This information can be accessed through the account. Account can be located with the transactions accountId.
currencyDenominatedAmount
type: CurrencyDenominatedAmount
required: false
The amount of the transaction represented as a scale and unscaled value together with the ISO 4217 currency code of the amount. The amount can be modified by the user but not the currency code.
currencyDenominatedOriginalAmount
type: CurrencyDenominatedAmount
required: false
The original amount that was received from the provider, before the user changed it. The amount is represented as a scale and unscaled value together with the ISO 4217 currency code of the amount.
date
type: number
required: true
The date the transaction was executed. This can be modified by the user.
description
type: string
required: true
The description of the transaction. This can be modified by the user.
dispensableAmount
type: number
required: false
The dispensable amount of the transaction.
id
type: string
required: true
The internal identifier of the transaction.
lastModified
type: number
required: true
The date the transaction was last modified by the user.
merchantId
type: string
required: false
The internal identifier of the merchant that the transaction belongs to. If available.
notes
type: string
required: true
A free-text field modifiable by the user. Any 'word' (whitespace separated), prefixed with a #, is considered a tag. These tags becomes searchable.
originalAmount
type: number
required: true
The original amount that was received from the provider, before the user changed it.
originalDate
type: number
required: true
The original date that was received from the provider, before the user changed it.
originalDescription
type: string
required: true
The original description that was received from the provider, before the user changed it.
partnerPayload
type: object
required: false
The payload that was previously ingested on the Connector API.
parts
type: array[TransactionPart]
required: false
Transaction parts (Beta). Available if the transaction is divided into more than one part.
payload
type: object
required: false
Meta data about the transaction, in key value format with Strings.
pending
type: boolean
required: true
Indicates if this transaction has been settled or is still pending.
timestamp
type: integer
required: true
The timestamp of when the transaction was first saved to database.
type
type: string
required: true
The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL
upcoming
type: boolean
required: false
Indicates if this is an upcoming transaction not booked yet.
userId
type: string
required: true
The internal identifier of the user that the transaction belongs to.
userModified
type: boolean
required: false

CurrencyDenominatedAmount

Parameter Description
currencyCode
type: string
required: true
The ISO 4217 currency code of the amount
scale
type: integer
required: true
The scale of the amount.
unscaledValue
type: integer
required: true
The unscaled value of the amount

TransactionPart

Parameter Description
amount
type: number
required: true
The amount of the transaction part.
categoryId
type: string
required: true
The category of the transaction part.
counterpartDescription
type: string
required: true
The description of the transaction containing the counterpart.
counterpartId
type: string
required: true
The id of the counterpart. The counterpart is a transaction part in another transaction
counterpartTransactionAmount
type: number
required: false
counterpartTransactionId
type: string
required: true
The id of the transaction containing the counterpart.
date
type: number
required: true
The date the transaction part was created.
id
type: string
required: true
The id of the transaction part.
lastModified
type: number
required: true
The date the transaction part was last modified.
Status Code Description
200 The transaction part was successfully deleted and returned.
400 The transaction id was invalid.
404 The transaction or the transaction part was not found.

Updates an transaction part amount and it's counterpart amount. PUT /api/v1/transactions/{id}/part/{partId}

Request Example

{
  "amount": -90
}

Parameters

Parameter Description
id
required: true
The id of the transaction to which the part belongs to.
partId
required: true
The part id to update.

Request Body: UpdateTransactionLinkRequest

Object holding the required amount for transaction linking

Parameter Description
amount
type: number
required: false
The amount of the transaction part. Must be same sign as the transaction. If not specified the common disposable amount will be used.

Response Example

{
  "counterpartTransaction": {
    "accountId": "3fe2d96efacd4dc5994404a950f238a9",
    "amount": 34,
    "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
    "categoryType": "EXPENSES",
    "credentialsId (Deprecated)": "65bc7a41a66e4ad1aad199bbfb3c5098",
    "currencyDenominatedAmount": {
      "currencyCode": "EUR",
      "scale": 2,
      "unscaledValue": 1050
    },
    "currencyDenominatedOriginalAmount": {
      "currencyCode": "EUR",
      "scale": 2,
      "unscaledValue": 1050
    },
    "date": 1455740874875,
    "description": "Stadium Sergelg Stockholm",
    "dispensableAmount": 0,
    "id": "79c6c9c27d6e42489e888e08d27205a1",
    "lastModified": 1455740874875,
    "merchantId": "ba3f9312fa7d442abde61ca419877fbf",
    "notes": "Delicious #cake #wedding",
    "originalAmount": 34,
    "originalDate": 1455740874875,
    "originalDescription": "Stadium Sergelg Stockholm",
    "partnerPayload": {},
    "parts": [
      {
        "amount": 34,
        "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
        "counterpartDescription": "Stadium Sergelg Stockholm",
        "counterpartId": "79c6c9c27d6e42489e888e08d27205a1",
        "counterpartTransactionAmount": 0,
        "counterpartTransactionId": "d030a7b0840547428aa2fd07026e9a77",
        "date": 1455740874875,
        "id": "7303ff128531463bbed358bbf9e23f31",
        "lastModified": 1455740874875
      }
    ],
    "payload": {},
    "pending": false,
    "timestamp": 1464543093494,
    "type": "CREDIT_CARD",
    "upcoming": false,
    "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
    "userModified": false
  },
  "transaction": {
    "accountId": "3fe2d96efacd4dc5994404a950f238a9",
    "amount": 34,
    "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
    "categoryType": "EXPENSES",
    "credentialsId (Deprecated)": "65bc7a41a66e4ad1aad199bbfb3c5098",
    "currencyDenominatedAmount": {
      "currencyCode": "EUR",
      "scale": 2,
      "unscaledValue": 1050
    },
    "currencyDenominatedOriginalAmount": {
      "currencyCode": "EUR",
      "scale": 2,
      "unscaledValue": 1050
    },
    "date": 1455740874875,
    "description": "Stadium Sergelg Stockholm",
    "dispensableAmount": 0,
    "id": "79c6c9c27d6e42489e888e08d27205a1",
    "lastModified": 1455740874875,
    "merchantId": "ba3f9312fa7d442abde61ca419877fbf",
    "notes": "Delicious #cake #wedding",
    "originalAmount": 34,
    "originalDate": 1455740874875,
    "originalDescription": "Stadium Sergelg Stockholm",
    "partnerPayload": {},
    "parts": [
      {
        "amount": 34,
        "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
        "counterpartDescription": "Stadium Sergelg Stockholm",
        "counterpartId": "79c6c9c27d6e42489e888e08d27205a1",
        "counterpartTransactionAmount": 0,
        "counterpartTransactionId": "d030a7b0840547428aa2fd07026e9a77",
        "date": 1455740874875,
        "id": "7303ff128531463bbed358bbf9e23f31",
        "lastModified": 1455740874875
      }
    ],
    "payload": {},
    "pending": false,
    "timestamp": 1464543093494,
    "type": "CREDIT_CARD",
    "upcoming": false,
    "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
    "userModified": false
  }
}

Response: LinkTransactionsResponse

Parameter Description
counterpartTransaction
type: Transaction
required: true
The counterpart transaction.
transaction
type: Transaction
required: true
The primary transaction.

Transaction

Parameter Description
accountId
type: string
required: true
The internal identifier of the account that the transaction belongs to.
amount
type: number
required: true
The amount of the transaction. This can be modified by the user.
categoryId
type: string
required: true
The category of the transaction. This can be modified by the user.
categoryType
type: string
required: true
The category type of the transaction.. Values: INCOME, EXPENSES, TRANSFERS
credentialsId (Deprecated)
type: string
required: true
The internal identifier of the credentials that the transaction belongs to. This is deprecated. This information can be accessed through the account. Account can be located with the transactions accountId.
currencyDenominatedAmount
type: CurrencyDenominatedAmount
required: false
The amount of the transaction represented as a scale and unscaled value together with the ISO 4217 currency code of the amount. The amount can be modified by the user but not the currency code.
currencyDenominatedOriginalAmount
type: CurrencyDenominatedAmount
required: false
The original amount that was received from the provider, before the user changed it. The amount is represented as a scale and unscaled value together with the ISO 4217 currency code of the amount.
date
type: number
required: true
The date the transaction was executed. This can be modified by the user.
description
type: string
required: true
The description of the transaction. This can be modified by the user.
dispensableAmount
type: number
required: false
The dispensable amount of the transaction.
id
type: string
required: true
The internal identifier of the transaction.
lastModified
type: number
required: true
The date the transaction was last modified by the user.
merchantId
type: string
required: false
The internal identifier of the merchant that the transaction belongs to. If available.
notes
type: string
required: true
A free-text field modifiable by the user. Any 'word' (whitespace separated), prefixed with a #, is considered a tag. These tags becomes searchable.
originalAmount
type: number
required: true
The original amount that was received from the provider, before the user changed it.
originalDate
type: number
required: true
The original date that was received from the provider, before the user changed it.
originalDescription
type: string
required: true
The original description that was received from the provider, before the user changed it.
partnerPayload
type: object
required: false
The payload that was previously ingested on the Connector API.
parts
type: array[TransactionPart]
required: false
Transaction parts (Beta). Available if the transaction is divided into more than one part.
payload
type: object
required: false
Meta data about the transaction, in key value format with Strings.
pending
type: boolean
required: true
Indicates if this transaction has been settled or is still pending.
timestamp
type: integer
required: true
The timestamp of when the transaction was first saved to database.
type
type: string
required: true
The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL
upcoming
type: boolean
required: false
Indicates if this is an upcoming transaction not booked yet.
userId
type: string
required: true
The internal identifier of the user that the transaction belongs to.
userModified
type: boolean
required: false

CurrencyDenominatedAmount

Parameter Description
currencyCode
type: string
required: true
The ISO 4217 currency code of the amount
scale
type: integer
required: true
The scale of the amount.
unscaledValue
type: integer
required: true
The unscaled value of the amount

TransactionPart

Parameter Description
amount
type: number
required: true
The amount of the transaction part.
categoryId
type: string
required: true
The category of the transaction part.
counterpartDescription
type: string
required: true
The description of the transaction containing the counterpart.
counterpartId
type: string
required: true
The id of the counterpart. The counterpart is a transaction part in another transaction
counterpartTransactionAmount
type: number
required: false
counterpartTransactionId
type: string
required: true
The id of the transaction containing the counterpart.
date
type: number
required: true
The date the transaction part was created.
id
type: string
required: true
The id of the transaction part.
lastModified
type: number
required: true
The date the transaction part was last modified.
Status Code Description
200 The transaction part and counter part were successfully updated and returned.
400 The transaction or part id were invalid.
404 The transaction or the transaction part was not found.
412 The transactions had the same signum, the part amount had a signum different from the transaction or the part amount is bigger than the dispensable amount.
500 The transaction part failed to update.

Get similar transactions

Returns an object holding a list of transactions similar to the supplied transaction based on description and a list of statistics summarizing these transactions GET /api/v1/transactions/{id}/similar

Parameters

Parameter Description
id
required: true
The id of the transaction

Query Parameters

Parameter Description
categoryId
required: false
Return similar of this category
includeSelf
required: false
Include the supplied transaction in response

Response Example

{
  "statistics": [
    {
      "description": "fe9e199c2ca94c12baf1f3eb4a4122de",
      "payload": "690667930d7e4f2ba0d9aa5f7d2a1941",
      "period": "2014-12-15",
      "resolution": "DAILY",
      "type": "expenses-by-category",
      "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
      "value": 1298
    }
  ],
  "transactions": [
    {
      "accountId": "3fe2d96efacd4dc5994404a950f238a9",
      "amount": 34,
      "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
      "categoryType": "EXPENSES",
      "credentialsId (Deprecated)": "65bc7a41a66e4ad1aad199bbfb3c5098",
      "currencyDenominatedAmount": {
        "currencyCode": "EUR",
        "scale": 2,
        "unscaledValue": 1050
      },
      "currencyDenominatedOriginalAmount": {
        "currencyCode": "EUR",
        "scale": 2,
        "unscaledValue": 1050
      },
      "date": 1455740874875,
      "description": "Stadium Sergelg Stockholm",
      "dispensableAmount": 0,
      "id": "79c6c9c27d6e42489e888e08d27205a1",
      "lastModified": 1455740874875,
      "merchantId": "ba3f9312fa7d442abde61ca419877fbf",
      "notes": "Delicious #cake #wedding",
      "originalAmount": 34,
      "originalDate": 1455740874875,
      "originalDescription": "Stadium Sergelg Stockholm",
      "partnerPayload": {},
      "parts": [
        {
          "amount": 34,
          "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
          "counterpartDescription": "Stadium Sergelg Stockholm",
          "counterpartId": "79c6c9c27d6e42489e888e08d27205a1",
          "counterpartTransactionAmount": 0,
          "counterpartTransactionId": "d030a7b0840547428aa2fd07026e9a77",
          "date": 1455740874875,
          "id": "7303ff128531463bbed358bbf9e23f31",
          "lastModified": 1455740874875
        }
      ],
      "payload": {},
      "pending": false,
      "timestamp": 1464543093494,
      "type": "CREDIT_CARD",
      "upcoming": false,
      "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
      "userModified": false
    }
  ]
}

Response: SimilarTransactionsResponse

Parameter Description
statistics
type: array[Statistic]
required: true
Statistics of type 'income-and-expenses-and-transfers' for the similar transactions.
transactions
type: array[Transaction]
required: true
List of similar transactions.

Statistic

Parameter Description
description
type: string
required: true
Identifier of the data the statistic represents.
payload
type: string
required: false
Secondary identifier of the data the statistic represent.
period
type: string
required: true
The statistic's period, depends on its resolution. One of: year, month, week or day. Format: '2014', '2014-02', '2014:45' or '2014-02-12'
resolution
type: string
required: true
Resolution for the statistics.. Values: DAILY, MONTHLY, MONTHLY_ADJUSTED, YEARLY, ALL, WEEKLY
type
type: string
required: true
The statistic's type.
userId
type: string
required: true
The internal identifier of the user that the statistics belongs to.
value
type: number
required: true
The value of the statistics for this type, period, and description.

Transaction

Parameter Description
accountId
type: string
required: true
The internal identifier of the account that the transaction belongs to.
amount
type: number
required: true
The amount of the transaction. This can be modified by the user.
categoryId
type: string
required: true
The category of the transaction. This can be modified by the user.
categoryType
type: string
required: true
The category type of the transaction.. Values: INCOME, EXPENSES, TRANSFERS
credentialsId (Deprecated)
type: string
required: true
The internal identifier of the credentials that the transaction belongs to. This is deprecated. This information can be accessed through the account. Account can be located with the transactions accountId.
currencyDenominatedAmount
type: CurrencyDenominatedAmount
required: false
The amount of the transaction represented as a scale and unscaled value together with the ISO 4217 currency code of the amount. The amount can be modified by the user but not the currency code.
currencyDenominatedOriginalAmount
type: CurrencyDenominatedAmount
required: false
The original amount that was received from the provider, before the user changed it. The amount is represented as a scale and unscaled value together with the ISO 4217 currency code of the amount.
date
type: number
required: true
The date the transaction was executed. This can be modified by the user.
description
type: string
required: true
The description of the transaction. This can be modified by the user.
dispensableAmount
type: number
required: false
The dispensable amount of the transaction.
id
type: string
required: true
The internal identifier of the transaction.
lastModified
type: number
required: true
The date the transaction was last modified by the user.
merchantId
type: string
required: false
The internal identifier of the merchant that the transaction belongs to. If available.
notes
type: string
required: true
A free-text field modifiable by the user. Any 'word' (whitespace separated), prefixed with a #, is considered a tag. These tags becomes searchable.
originalAmount
type: number
required: true
The original amount that was received from the provider, before the user changed it.
originalDate
type: number
required: true
The original date that was received from the provider, before the user changed it.
originalDescription
type: string
required: true
The original description that was received from the provider, before the user changed it.
partnerPayload
type: object
required: false
The payload that was previously ingested on the Connector API.
parts
type: array[TransactionPart]
required: false
Transaction parts (Beta). Available if the transaction is divided into more than one part.
payload
type: object
required: false
Meta data about the transaction, in key value format with Strings.
pending
type: boolean
required: true
Indicates if this transaction has been settled or is still pending.
timestamp
type: integer
required: true
The timestamp of when the transaction was first saved to database.
type
type: string
required: true
The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL
upcoming
type: boolean
required: false
Indicates if this is an upcoming transaction not booked yet.
userId
type: string
required: true
The internal identifier of the user that the transaction belongs to.
userModified
type: boolean
required: false

CurrencyDenominatedAmount

Parameter Description
currencyCode
type: string
required: true
The ISO 4217 currency code of the amount
scale
type: integer
required: true
The scale of the amount.
unscaledValue
type: integer
required: true
The unscaled value of the amount

TransactionPart

Parameter Description
amount
type: number
required: true
The amount of the transaction part.
categoryId
type: string
required: true
The category of the transaction part.
counterpartDescription
type: string
required: true
The description of the transaction containing the counterpart.
counterpartId
type: string
required: true
The id of the counterpart. The counterpart is a transaction part in another transaction
counterpartTransactionAmount
type: number
required: false
counterpartTransactionId
type: string
required: true
The id of the transaction containing the counterpart.
date
type: number
required: true
The date the transaction part was created.
id
type: string
required: true
The id of the transaction part.
lastModified
type: number
required: true
The date the transaction part was last modified.
Status Code Description
200 Successful operation.
404 Transaction not found.

User Service

Get the user

Returns the user object. Note that the password field is not stored in clear text nor populated when getting the user. It's only used for setting the password when registering a new user. GET /api/v1/user

Response Example

{
  "created": "string",
  "flags": [
    "TRANSFERS",
    "TEST_PINK_ONBOARDING"
  ],
  "id": "6e68cc6287704273984567b3300c5822",
  "nationalId": "string",
  "password": "string",
  "profile": {
    "currency": "SEK",
    "locale": "sv_SE",
    "market": "SE",
    "notificationSettings": {
      "balance": false,
      "budget": false,
      "doubleCharge": false,
      "einvoices": false,
      "fraud": false,
      "income": false,
      "largeExpense": false,
      "leftToSpend": false,
      "loanUpdate": false,
      "summaryMonthly": false,
      "summaryWeekly": false,
      "transaction": false,
      "unusualAccount": false,
      "unusualCategory": false
    },
    "periodAdjustedDay": 25,
    "periodMode": "MONTHLY_ADJUSTED",
    "timeZone": "Europe/Stockholm"
  },
  "username": "nisse@manpower.se"
}

Response: User

Parameter Description
created
type: number
required: true
The date when the user was created.
flags
type: array[string]
required: false
The user-specific feature flags assigned to the user.
id
type: string
required: true
The internal identifier of the user.
nationalId
type: string
required: false
password
type: string
required: false
The password of the user (only included at registration).
profile
type: UserProfile
required: true
The configurable profile of the user
username
type: string
required: false
The username (usually email) of the user.

UserProfile

Parameter Description
currency
type: string
required: true
The configured ISO 4217 currency code of the user. This can be modified by the user.
locale
type: string
required: true
The configured locale of the user. This can be modified by the user.
market
type: string
required: true
The primary market/country of the user.
notificationSettings
type: NotificationSettings
required: true
The configured notification settings of the user. This can be modified by the user.
periodAdjustedDay
type: integer
required: true
The configured day of the month to break the adjusted period on. This can be modified by the user.
periodMode
type: string
required: true
The configured monthly period mode of the user. This can be modified by the user.. Values: MONTHLY, MONTHLY_ADJUSTED
timeZone
type: string
required: true
The configured time zone of the user. This can be modified by the user.

NotificationSettings

Parameter Description
balance
type: boolean
required: true
Indicates if the user wants to receive notifications with low or high balances alerts.
budget
type: boolean
required: true
Indicates if the user wants to receive notifications regarding her budgets.
doubleCharge
type: boolean
required: true
Indicates if the user wants to receive notifications with double-charge alerts.
einvoices
type: boolean
required: true
Indicates if the user wants to receive notifications for e-invoices.
fraud
type: boolean
required: true
Indicates if the user wants to receive notifications for ID Control warnings.
income
type: boolean
required: true
Indicates if the user wants to receive notifications when an income is received.
largeExpense
type: boolean
required: true
Indicates if the user wants to receive notifications when a large expense is detected.
leftToSpend
type: boolean
required: true
Indicates if the user wants to receive left to spend notifications.
loanUpdate
type: boolean
required: true
Indicates if the user wants to receive notifications for loan updates.
summaryMonthly
type: boolean
required: true
Indicates if the user wants to receive notifications with monthly summaries.
summaryWeekly
type: boolean
required: true
Indicates if the user wants to receive notifications with weekly summaries.
transaction
type: boolean
required: true
Indicates if the user wants to receive notifications for every transaction.
unusualAccount
type: boolean
required: true
Indicates if the user wants to receive notifications when there is unusual activity on any of her accounts.
unusualCategory
type: boolean
required: true
Indicates if the user wants to receive notifications when she has spend more than usual on something.

Create a new user

Returns the id of the created user. POST /api/v1/user/create

Request Example

{
  "external_user_id": "user_123_abc",
  "locale": "en_US",
  "market": "SE"
}

Request Body: CreateUserRequest

Configuration for new user.

Parameter Description
external_user_id
type: string
required: false
Optional external user id for the created user.
locale
type: string
required: false
Locale for the user. Defaults to default locale for the user's market.
market
type: string
required: true
Market specific code for the user as a ISO 3166-1 country code.

Response Example

{
  "user_id": "6e68cc6287704273984567b3300c5823"
}

Response: CreateUserResponse

Parameter Description
user_id
type: string
required: true
The user id of the created user.
Status Code Description
200 The user was successfully created and returned.
400 The input market and/or locale was invalid.
409 User with the same external id already exists.

Delete user

Completely deletes the currently authenticated user and its data. POST /api/v1/user/delete

Get the user profile

Returns the user profile. GET /api/v1/user/profile

Response Example

{
  "currency": "SEK",
  "locale": "sv_SE",
  "market": "SE",
  "notificationSettings": {
    "balance": false,
    "budget": false,
    "doubleCharge": false,
    "einvoices": false,
    "fraud": false,
    "income": false,
    "largeExpense": false,
    "leftToSpend": false,
    "loanUpdate": false,
    "summaryMonthly": false,
    "summaryWeekly": false,
    "transaction": false,
    "unusualAccount": false,
    "unusualCategory": false
  },
  "periodAdjustedDay": 25,
  "periodMode": "MONTHLY_ADJUSTED",
  "timeZone": "Europe/Stockholm"
}

Response: UserProfile

Parameter Description
currency
type: string
required: true
The configured ISO 4217 currency code of the user. This can be modified by the user.
locale
type: string
required: true
The configured locale of the user. This can be modified by the user.
market
type: string
required: true
The primary market/country of the user.
notificationSettings
type: NotificationSettings
required: true
The configured notification settings of the user. This can be modified by the user.
periodAdjustedDay
type: integer
required: true
The configured day of the month to break the adjusted period on. This can be modified by the user.
periodMode
type: string
required: true
The configured monthly period mode of the user. This can be modified by the user.. Values: MONTHLY, MONTHLY_ADJUSTED
timeZone
type: string
required: true
The configured time zone of the user. This can be modified by the user.

NotificationSettings

Parameter Description
balance
type: boolean
required: true
Indicates if the user wants to receive notifications with low or high balances alerts.
budget
type: boolean
required: true
Indicates if the user wants to receive notifications regarding her budgets.
doubleCharge
type: boolean
required: true
Indicates if the user wants to receive notifications with double-charge alerts.
einvoices
type: boolean
required: true
Indicates if the user wants to receive notifications for e-invoices.
fraud
type: boolean
required: true
Indicates if the user wants to receive notifications for ID Control warnings.
income
type: boolean
required: true
Indicates if the user wants to receive notifications when an income is received.
largeExpense
type: boolean
required: true
Indicates if the user wants to receive notifications when a large expense is detected.
leftToSpend
type: boolean
required: true
Indicates if the user wants to receive left to spend notifications.
loanUpdate
type: boolean
required: true
Indicates if the user wants to receive notifications for loan updates.
summaryMonthly
type: boolean
required: true
Indicates if the user wants to receive notifications with monthly summaries.
summaryWeekly
type: boolean
required: true
Indicates if the user wants to receive notifications with weekly summaries.
transaction
type: boolean
required: true
Indicates if the user wants to receive notifications for every transaction.
unusualAccount
type: boolean
required: true
Indicates if the user wants to receive notifications when there is unusual activity on any of her accounts.
unusualCategory
type: boolean
required: true
Indicates if the user wants to receive notifications when she has spend more than usual on something.

Version Service

Get the version

Gets the current version (build) of the application GET /api/v1/version

Response Example

{
  "commit": "e764d0eed748d6c137c30fc94c7e17544d101ff3",
  "date": 1455740874875,
  "version": "4513"
}

Response: VersionResponse

Parameter Description
commit
type: string
required: true
The last commit of the build
date
type: number
required: true
The date of the build
version
type: string
required: true
The version of the build