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

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 3rd-party API consumer should account for the fact that unknown properties can be present.

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

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}\"},{\"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.

Account

When a credentials connection is successfully established, all supported accounts from the financial institution are aggregated and made available in the Tink API. An account can represent everything from the user’s regular checking account to an investment account with their broker, or their home mortgage as a credit account.

Tink does what it can to try to determine the real type of account, but always defaults to marking the account as a regular CHECKING-account if we can’t figure it out.

The ownership property adheres from the case where a user has selected that she’s sharing the account with someone else. The effect of the ratio is that both the balance of the account, as well as any transactions stemming from the account, are only partly contributing towards the user’s spending and total net-worth when the aggregated statistics are calculated.

The balance property of an account tries to provide a unified concept of balance across the different account types, which the intention to represent the user’s current standing with the financial institution, and not the disposable amount. As an example, on a CHECKING account, the balance represent the actual amount of cash in the account. In the case of a CREDIT_CARD account, the balance is the outstanding balance on the account, and does not include any available credit or purchasing power the user has with the credit provider.

Also worth mentioning, the balance property represents the current balance of the account when the credentials was last updated successfully. Historical account balance information is available through the statistics interface, with a type of balances-by-account and the id of the account as the description of the statistics objects.

The accountExclusion property specifies what products to exclude from an account, the possible values are :

NONE No features are excluded from this account.

PFM_DATA Categorization and PFM Features are excluded.

PFM_AND_SEARCH As above, but transactions belonging to this account are not indexed so they are not searchable. This is the equivalent of the, now deprecated, boolean flag ‘excluded’.

AGGREGATION Upon setting Account Exclusion to “AGGREGATION”, all data beneath the account is removed (except account name and account number). This includes User generated content like categories and tags. Moreover, in any future data refreshes, no data will be stored for the Account. The data removal is irreversible, however, all data, possible to retrieve, will be downloaded again, should the AGGREGATION exclusion be removed from the Account again.

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 operations on an account, and could represent both the actual credit-card purchase on a CREDIT_CARD account, but also represent the transaction when you payed your credit-card bill. Most commonly, the transactions on an account should represent what the end-user typically.

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, 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 consumer 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

Activity (Insight)

Double Charge

{
  "activities": [
    {
      "content": [
        {
          "...": "// A Transaction object (See Transaction Service)"
        },
        {
          "...": "// A Transaction object (See Transaction Service)"
        }
      ],
      "date": 1370685600000,
      "importance": 64.62,
      "key": "double-charge.2013-06-08.b371f9659315e07aa35736b0c30e37f0",
      "message": "You were double-charged by Kungsholmen for 154 kr.",
      "title": "Double charge",
      "type": "double-charge"
    }
  ],
  "count": 1
}

Follow Activity Content

{
  "followItem": {
    "id": "//See Follow Service for FollowItem object"
  }
}

In order to give the user insights in what is going on in her personal finance, Tink runs many calculations every time data is processed and tries to find the most interesting facts from her personal finance. This information in presented via an Activity. Different result could be returned from different times activities are listed. This is since the Tink engine may have detected something of more interest than before and leaves out what before was present. The key property on the activity is persistent between queries if the activity is based on the same data. Hence if an activity with a new key is return it means this is a new unseen activity.

Each activity has a data object serialized in its content property. This can be deserialized based on the type of activity.

Unusual Category Spend Content

{
  "categoryId": "e62864f291e4473c969a67db964d409d",
  "period": "2016-06",
  "data": {
    "2016-04": 398.2,
    "2016-05": 412.7,
    "2016-06": 6342.5
  },
  "dataAverages": {
    "2016-04": 362.8,
    "2016-05": 403.1,
    "2016-06": 450.5
  }
}

Example Activity Types

Activity type content
Double Charge double-charge A list with the two or more transactions.
Follow Activity (Budget) follow/expenses The Follow Item.
Large Expense large-expense or large-expense/multiple The Transaction for a single or a List of Transactions for the grouped Activity.
Left to Spend left-to-spend The differance, Left to spend and average statistics.
Suggest Transcations to Categorize suggest A SuggestTransactionsResponse object.
Unusual Account Balance balance-low or balance-high The account and data points (key/value: period/account-balance).
Unusual Category Spend unusual-category-high or unusual-category-low The category, period (monthly) and data points (key/value: period/category-spend).
Weekly Summary weekly-summary  A lot of data regarding how money was spent during week, and summary of budgets. See example to the right.
Monthly Summary monthly-summary Data regarding how the past month has been for the user. Includes the largest expenses and incomes as well as a left-to-spend graph for the month and the end result. See example to the right.

Left to Spend

{
  "difference": -124,
  "leftToSpend": [
    {
      "description": "//statistics objects",
      "type": "left-to-spend",
      "...": "..."
    }
  ],
  "leftToSpendAverage": [
    {
      "description": "//statistics objects",
      "type": "left-to-spend-average",
      "...": "..."
    }
  ]
}

Suggest Transactions to Categorize

{
  "...": " // A SuggestTransactionsResponse object. See #get-categorization-clusters"
}

Weekly Summary

{
  "expensesAmount": 1234.3,
  "expensesCount": 42,
  "followFeedback": [
    {
      "description": "description",
      "followItems": [
        {
          "...": " // follow item object"
        }
      ],
      "title": "title"
    }
  ],
  "historicalExpenses": [
    {
      "key": "2016:23",
      "value": 2313.3
    }
  ],
  "largestCategories": [
    {
      "amount": 213.3,
      "categoryId": "4959a490e68342b093d4473e1f158163",
      "count": 12
    }
  ],
  "week": 24,
  "historicalExpensesAverage": [
    {
      "key": "1",
      "value": 123
    },
    {
      "key": "2",
      "value": 242
    }
  ],
  "expensesAverageAmount": 2324.2,
  "biggestExpense": {
    "...": " // transaction object"
  },
  "weekEndDate": 1471349422000,
  "weekStartDate": 1471349422000
}

Monthly summary

{
  "activities": [
    {
      "content": {
        "expenses": -3216.09,
        "followFeedback": null,
        "income": 4000.0,
        "largestExpenses": [{ "...": "// List of Transaction objects" }],
        "leftToSpend": [
          {
            "description": "2018-02-01",
            "period": "2018-02",
            "resolution": "MONTHLY",
            "type": "left-to-spend",
            "userId": "431c44ca487543b9a67570dea59d7f9b",
            "value": -10.99
          },
          {
            "description": "2018-02-02",
            "period": "2018-02",
            "resolution": "MONTHLY",
            "type": "left-to-spend",
            "userId": "431c44ca487543b9a67570dea59d7f9b",
            "value": -589.8399999999999
          },
          { "...": "// Daily statistics for the month (See Statistics endpoint)" }
        ],
        "month": 2,
        "largestIncome": [{ "...": "// List of Transaction objects" }],
        "period": "2018-02",
        "largestCategories": [
          {
            "amount": -1000.0,
            "categoryId": "3e7c9ed2bffa404594bf779a147624bf",
            "count": 1,
            "average": -200.0
          },
          {
            "amount": -147.21,
            "categoryId": "67aab60c6ae049909b3f780aba6bd790",
            "count": 9,
            "average": "NaN"
          }
        ],
        "unusualSpending": [
          {
            "amount": -48.25,
            "categoryId": "6465e91b40134388a611b12de3d1d0da",
            "count": 0,
            "average": -33.27166666666666
          },
          {
            "amount": -1000.0,
            "categoryId": "3e7c9ed2bffa404594bf779a147624bf",
            "count": 0,
            "average": -1000.0
          }
        ],
        "expensesAvg": -3403.939999999999
      },
      "date": 1519858799999,
      "importance": 90.0,
      "key": "monthly-summary.2018-02",
      "message": "February was a good month! You earned 78€ more than you spent.",
      "title": "February",
      "type": "monthly-summary"
    }
  ],
  "count": 1
}

Unusually large expense

{
  "activities": [
    {
      "content": {
        "...": "// A Transaction response (See Transaction Service)"
      },
      "date": 1384772400000,
      "importance": 70.0,
      "key": "large-expense.2013-11-18.81905e40c71f4cb9aa42e2b829e29606",
      "message": "There has been an unusually large expense named McDonalds",
      "title": "Large expense",
      "type": "large-expense"
    }
  ],
  "count": 1
}

Transfers

The Tink API makes it possible to make transfers. Tink has defined a transfer as moving money from one account to any destination, no matter if the destination is another bank account or a PG/BG-recipient.

When making a transfer, the client sends in an object, a Transfer, that defines from where, to where and how much that will be transferred. The source account must of course belong to the authenticated user. It’s the destination that decides whether to make a bank transfer or a payment. For instance if the destination is a BG-recipient, then the transfer will become a payment, whereas if the destination is a Swedish account number, the transfer will be become a bank transfer.

Source and Destination accounts or PG/BG-recipients are sent on a special URI format.

Example

Source type Defined by URI format Example
Bank Account 9999 - 123456789 se://{clearingnumber}{accountnumber} se://9999123456789
Tink Account a4692fae219d4f7892262f269a6002f6 tink://{account#id} tink://a4692fae219d4f7892262f269a6002f6
Destination type Defined by URI format Example
Bank Account 9999 - 123456789 se://{clearingnumber}{accountnumber} se://9999123456789
PG Recipient 90 2003-3 se-pg://{pg-recipient} se-pg://9020033
BG Recipient 902-0033 se-bg://{bg-recipient} se-bg://9020033

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. You can find more about the test providers here.

Example of a Test Provider

{
    "name": "test-successful-bankid",
    "credentialsType": "MOBILE_BANKID",
    "currency": "SEK",
    "displayName": "Test BankID",
    "fields": [
        {
            "hint": "YYYYMMDDNNNN",
            "name": "username",
            "numeric": true,
            "pattern": "(19|20)[0-9]{10}",
            "immutable": true,
            "maxLength": 12,
            "minLength": 12,
            "description": "Social security number",
            "patternError": "Please enter a valid social security number."
        }
    ],
    "...": "...",
    "passwordHelpText": "To connect your broker, you need to identify yourself using Mobile BankID.",
    "status": "ENABLED",
    "type": "TEST"
}
Test Provider Description
test-bankid-successful Will authenticate successful for the correct username.
test-bankid-failing Will allways fail to authenticate.
test-password Requries the user to enter test-credentials in the form of a username and a password.
test-multi-supplemental Scenario of an external authentication system, where two separate codes are entered into the system.

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
test-password tink tink1234 -
test-multi-supplemental tink-test - 1234, 4321
test-bankid-failing 180012121212 - -
test-bankid-successful 180012121212 -

Web Hooks

+-----------------+   +-----------+                         +-------+
|    Consumer     |   | Consumer  |                         | Tink  |
| WebHookService  |   |           |                         |       |
+-----------------+   +-----------+                         +-------+
         |                  |                                   |
         |                  | POST /hooks (body: OAuth2Webhook) |
         |                  |---------------------------------->|
         |                  |                                   |
         |                  |                                   |
         |                  |                                   |
         |                  | POST /transfer (body: Transfer)   |
         |                  |---------------------------------->+
         |                  |                                  / \
         |                  |  Newly created SignableOperation \ /
         |                  |<----------------------------------+
         |                  |                                   |
         |                  |                                   |
         |                  |                                   | +---------------------+
         |                  |                                   |-| User signs transfer |
         |                  |                                   | +---------------------+
         |                  |                                   |
         |                  |                                   |
         |            POST {webhook-url} (body: WebHookRequest) |
         |<-----------------------------------------------------|

If you want updates to certain events pushed back to your servers that can be achieved using web hooks. The consumer client will need a special OAuth2 Client scope for creating web hooks for the end user. The web hook flow can be seen in the sequence diagram here on the right. The request made back to the consumer’s web hook service (the given URL) will be a POST request with a WebHookRequest object as the body.

POST /hooks body: OAuth2Webhook

{
    "secret": "{SOME_USER_SPECIFIC_SECRET}",
    "url": "https://www.consumer.com/webhook-receiver/",
    "events": [
        "signable-operation:update"
    ]
}

Request body: WebHookRequest

Parameter Type Description
event String The triggered event.
content Object The content depends on the event. For instance, for a Signable operation event the content object will be a SignableOperation.
webHook OAuth2WebHook The web hook that was created by the consumer. This objects contains the secret for the consumer to compare. See Web Hook Service for more information.

POST {webhook-url}: WebHookRequest

{
    "event": "signable-operation:update",
    "content": {
        "created": 1471349422000,
        "credentialsId": "342220f1e0484c0481b2b468d7fbcfc4",
        "id": "a4516bda6ff545e0aa24e54b859579e0",
        "status": "EXECUTED",
        "statusMessage": "The transfer has been sent to your bank.",
        "type": "TRANSFER",
        "underlyingId": "1e09bab571d84b1cbe8d49c0be9c030f",
        "updated": 1471349422000,
        "userId": "2f37e3ff1e5342b39c41bee3ee73cf8e"
    },
    "webHook": {
        "secret": "{SOME_USER_SPECIFIC_SECRET}",
        "url": "https://www.consumer.com/webhook-receiver/",
        "events": [
            "signable-operation:update"
        ]
    }
}

Restrictions

The service receiving the web hooks must be served over https, and the Tink client will not follow redirects. Furthermore, the domain of the URL needs to be preset in Tink’s backend. It is not possible to automatically set this domain so the consumer needs to contact their Tink contact for this to be set. A consumer can have multiple “authorized” domains preset. These restrictions are done for security reasons.

Events

Event name                                 Description
credentials:create This event is fired upon creating new Credentials
credentials:update This event is fired upon Credentials getting updated. This is fired for user triggered updates (PUT on Credentials Service) as well as async updates of status when user is authenticating towards the Provider.
transaction:create (To be implemented shortly) This event is fired upon a transaction created in the Tink Platform. This is either due to aggregation or via the Connector.
transaction:update This event is fired upon an existing transaction getting updated.
signable-operation:update This event is fired upon an update of the SignableOperation.

API Reference

Account Service

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",
      "details": {
        "interest": 0,
        "nextDayOfTermsChange": "string",
        "numMonthsBound": 0,
        "type": "string"
      },
      "excluded": null,
      "favored": null,
      "flags": "[\"MANDATE\"]",
      "holderName": "Thomas Alan Waits",
      "id": "a6bb87e57a8c4dd4874b241471a2b9e8",
      "identifiers": "[\"se://9999111111111111\"]",
      "name": "Privatkonto",
      "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 Type Required Description
accounts array[Account] A list of accounts

Account

Parameter Type Required Description
accountExclusion string true The type of features to exclude for this account. This can be modified by the user.. Values: AGGREGATION, PFM_AND_SEARCH, PFM_DATA, NONE
accountNumber string true The account number of the account. Not necessarily always a full clearingnumber-accountnumber. It can be formatted differently for different accounts and banks.
balance number true The current balance of the account.
closed boolean
credentialsId string true The internal identifier of the credentials that the account belongs to.
details AccountDetails If available, details are populated.
excluded boolean true Indicates if the user has excluded the account. This can be modified by the user.
favored boolean true Indicates if the user has favored the account. This can be modified by the user.
flags string A list of flags specifying attributes on an account. Values: BUSINESS, MANDATE
holderName string The name of the account holder
id string true The internal identifier of account.
identifiers string All possible ways to uniquely identify this Account. An se-identifier is built up like: se://{clearingnumber}{accountnumber}
name string true The display name of the account. This can be modified by the user.
ownership number true The ownership ratio indicating how much of the account is owned by the user. This is used to determine how much of transactions belonging to this account should be attributed to the user when statistics are calculated. This can be modified by the user.
transferDestinations array[TransferDestination] This field contains all the destinations this Account can transfer money to, be that payment or bank transfer recipients. It will only be populated if getting accounts via GET /transfer/accounts (i.e. not through GET /accounts).
type string true The type of the account. This can be modified by the user.. Values: CHECKING, SAVINGS, INVESTMENT, MORTGAGE, CREDIT_CARD, LOAN, PENSION, OTHER, EXTERNAL

AccountDetails

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

TransferDestination

Parameter Type Required Description
balance number The balance of the account. Will only be populated for accounts that is owned by the user.
displayAccountNumber string A display formatted alpha-numeric string of the destination account/payment recipient number.
displayBankName string The name of the bank where this destination recides. Will not be populated for payment destinations.
matchesMultiple boolean 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 string The name of the destination if one exists.
type string 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 string The uri used to describe this destination.

Update an Account

Updates certain user modifiable properties of an account. Please refer to the body schema to see which properties are modifiable by the user.

PUT /api/v1/accounts/{id}

Request Example

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

Parameters

Parameter Required Description
id true The id of the account

Request Body: Account

The updated account object

Parameter Type Required Description
accountExclusion string true The type of features to exclude for this account. This can be modified by the user.. Values: AGGREGATION, PFM_AND_SEARCH, PFM_DATA, NONE
accountNumber string true The account number of the account. Not necessarily always a full clearingnumber-accountnumber. It can be formatted differently for different accounts and banks.
balance number true The current balance of the account.
closed boolean
credentialsId string true The internal identifier of the credentials that the account belongs to.
details AccountDetails If available, details are populated.
excluded boolean true Indicates if the user has excluded the account. This can be modified by the user.
favored boolean true Indicates if the user has favored the account. This can be modified by the user.
flags string A list of flags specifying attributes on an account. Values: BUSINESS, MANDATE
holderName string The name of the account holder
id string true The internal identifier of account.
identifiers string All possible ways to uniquely identify this Account. An se-identifier is built up like: se://{clearingnumber}{accountnumber}
name string true The display name of the account. This can be modified by the user.
ownership number true The ownership ratio indicating how much of the account is owned by the user. This is used to determine how much of transactions belonging to this account should be attributed to the user when statistics are calculated. This can be modified by the user.
transferDestinations array[TransferDestination] This field contains all the destinations this Account can transfer money to, be that payment or bank transfer recipients. It will only be populated if getting accounts via GET /transfer/accounts (i.e. not through GET /accounts).
type string true The type of the account. This can be modified by the user.. Values: CHECKING, SAVINGS, INVESTMENT, MORTGAGE, CREDIT_CARD, LOAN, PENSION, OTHER, EXTERNAL

AccountDetails

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

TransferDestination

Parameter Type Required Description
balance number The balance of the account. Will only be populated for accounts that is owned by the user.
displayAccountNumber string A display formatted alpha-numeric string of the destination account/payment recipient number.
displayBankName string The name of the bank where this destination recides. Will not be populated for payment destinations.
matchesMultiple boolean 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 string The name of the destination if one exists.
type string 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 string The uri used to describe this destination.

Response Example

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

Response: Account

Parameter Type Required Description
accountExclusion string true The type of features to exclude for this account. This can be modified by the user.. Values: AGGREGATION, PFM_AND_SEARCH, PFM_DATA, NONE
accountNumber string true The account number of the account. Not necessarily always a full clearingnumber-accountnumber. It can be formatted differently for different accounts and banks.
balance number true The current balance of the account.
closed boolean
credentialsId string true The internal identifier of the credentials that the account belongs to.
details AccountDetails If available, details are populated.
excluded boolean true Indicates if the user has excluded the account. This can be modified by the user.
favored boolean true Indicates if the user has favored the account. This can be modified by the user.
flags string A list of flags specifying attributes on an account. Values: BUSINESS, MANDATE
holderName string The name of the account holder
id string true The internal identifier of account.
identifiers string All possible ways to uniquely identify this Account. An se-identifier is built up like: se://{clearingnumber}{accountnumber}
name string true The display name of the account. This can be modified by the user.
ownership number true The ownership ratio indicating how much of the account is owned by the user. This is used to determine how much of transactions belonging to this account should be attributed to the user when statistics are calculated. This can be modified by the user.
transferDestinations array[TransferDestination] This field contains all the destinations this Account can transfer money to, be that payment or bank transfer recipients. It will only be populated if getting accounts via GET /transfer/accounts (i.e. not through GET /accounts).
type string true The type of the account. This can be modified by the user.. Values: CHECKING, SAVINGS, INVESTMENT, MORTGAGE, CREDIT_CARD, LOAN, PENSION, OTHER, EXTERNAL

AccountDetails

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

TransferDestination

Parameter Type Required Description
balance number The balance of the account. Will only be populated for accounts that is owned by the user.
displayAccountNumber string A display formatted alpha-numeric string of the destination account/payment recipient number.
displayBankName string The name of the bank where this destination recides. Will not be populated for payment destinations.
matchesMultiple boolean 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 string The name of the destination if one exists.
type string 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 string The uri used to describe this destination.

Activity Service

Query activities

Queries activities

POST /api/v1/activities/query

Request Example

{
  "endDate": 1455740874875,
  "limit": 10,
  "offset": 0,
  "startDate": 1455740874875,
  "types": [
    "unusual-category-high",
    "unusual-category-low"
  ]
}

Request Body: ActivityQuery

The query.

Parameter Type Required Description
endDate number The end date to be used as a query filter
limit integer The maximum number of activities to return (when paging, 0 indicates no limit).
offset integer The number of activities to skip (when paging).
startDate number The start date to be used as a query filter
types array[string] The set of activity types to be used as a query filter

Response Example

{
  "activities": [
    {
      "content": "{\"categoryId\": \"18bb1f4636894f3bba8ddcd567d22fbd\", \"period\": \"2016-05\", \"data\": [\"2015-01\"...",
      "date": 1455740874875,
      "importance": 62,
      "key": "unusual-category-high.2016-05.18bb1f4636894f3bba8ddcd567d22fbd",
      "message": "You have spent more than usual on restaurants this month.",
      "title": "More than usual",
      "type": "unusual-category-high"
    }
  ],
  "count": 134
}

Response: ActivityQueryResponse

Parameter Type Required Description
activities array[Activity] true The filtered list of activities matching the query
count integer true The total number of activities matching the query

Activity

Parameter Type Required Description
content object true Serialized type dependent object.
date number true Date of the activity.
importance number true Importance compared to other activities 1-100 where 100 is of most importance.
key string true Persistent key per type and content.
message string true The activity message. Used as basis for the corresponding notification.
title string true The activity title. Used as basis for the corresponding notification.
type string true The activity type. Used as basis for the corresponding notification.

Get activity

Get activity

GET /api/v1/activities/{key}

Parameters

Parameter Required Description
key true The key of the activity.

Response Example

{
  "content": "{\"categoryId\": \"18bb1f4636894f3bba8ddcd567d22fbd\", \"period\": \"2016-05\", \"data\": [\"2015-01\"...",
  "date": 1455740874875,
  "importance": 62,
  "key": "unusual-category-high.2016-05.18bb1f4636894f3bba8ddcd567d22fbd",
  "message": "You have spent more than usual on restaurants this month.",
  "title": "More than usual",
  "type": "unusual-category-high"
}

Response: Activity

Parameter Type Required Description
content object true Serialized type dependent object.
date number true Date of the activity.
importance number true Importance compared to other activities 1-100 where 100 is of most importance.
key string true Persistent key per type and content.
message string true The activity message. Used as basis for the corresponding notification.
title string true The activity title. Used as basis for the corresponding notification.
type string true The activity type. Used as basis for the corresponding notification.

Calendar Service

Business days

Get the business days available for this user.

GET /api/v1/calendar/businessdays/{startYear}-{startMonth}

Parameters

Parameter Required Description
startYear true Start year for queried business days
startMonth true Start month for queried business days

Query Parameters

Parameter Required Description
months Number of months queried for, default 1

Response Example

{
  "businessDays": ""
}

Response: BusinessDaysResponse

Parameter Type Required Description
businessDays object

Period details

Get details for supplied period. Will always return resolution MONTHLY. Possible inputs: YYYY, YYYY-MM, YYYY-MM-DD

GET /api/v1/calendar/periods/{period}

Parameters

Parameter Required Description
period true Period to get details for

Response Example

[
  {
    "endDate": 1464739199000,
    "name": "2016-05",
    "resolution": "MONTHLY",
    "startDate": 1462060800000
  }
]

Response: array[Period]

Parameter Type Required Description
endDate number Timestamp at the end of the period
name string
resolution string Resolution for the statistics. . Values: MONTHLY, MONTHLY_ADJUSTED
startDate number Timestamp at the start of the period

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

Credentials Service

Create credentials

Creates the Credentials for the user. The create request will trigger a refresh towards the provider.

POST /api/v1/credentials

Request Example

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

Query Parameters

Parameter Required Description
items The data types to download from aggregated Provider. Multiple items are allowed. If omitted, everything is downloaded.. Values: CHECKING_ACCOUNTS, CHECKING_TRANSACTIONS, SAVING_ACCOUNTS, SAVING_TRANSACTIONS, CREDITCARD_ACCOUNTS, CREDITCARD_TRANSACTIONS, LOAN_ACCOUNTS, LOAN_TRANSACTIONS, INVESTMENT_ACCOUNTS, INVESTMENT_TRANSACTIONS, EINVOICES, TRANSFER_DESTINATIONS

Request Body: Credentials

The credentials to create. Only providerName and fields are required.

Parameter Type Required Description
fields object 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 string The id of the credentials.
providerName string true The provider (financial institute) that the credentials belongs to.
status string The status of 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
statusPayload string 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 number A timestamp of when the credentials’ status was last updated.
supplementalInformation string A key-value structure to handle if status of credentials are AWAITING_SUPPLEMENTAL_INFORMATION.
type string The type of credentials.. Values: PASSWORD, MOBILE_BANKID, KEYFOB, THIRD_PARTY_APP
updated number A timestamp of when the credentials was the last time in status UPDATED.
userId string The id of the user that the credentials belongs to.

Response Example

{
  "fields": {
    "username": "198410045701"
  },
  "id": "6e68cc6287704273984567b3300c5822",
  "providerName": "handelsbanken-bankid",
  "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 Type Required Description
fields object 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 string The id of the credentials.
providerName string true The provider (financial institute) that the credentials belongs to.
status string The status of 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
statusPayload string 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 number A timestamp of when the credentials’ status was last updated.
supplementalInformation string A key-value structure to handle if status of credentials are AWAITING_SUPPLEMENTAL_INFORMATION.
type string The type of credentials.. Values: PASSWORD, MOBILE_BANKID, KEYFOB, THIRD_PARTY_APP
updated number A timestamp of when the credentials was the last time in status UPDATED.
userId string 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",
      "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 Type Required Description
credentials array[Credentials] A list of credentials

Credentials

Parameter Type Required Description
fields object 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 string The id of the credentials.
providerName string true The provider (financial institute) that the credentials belongs to.
status string The status of 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
statusPayload string 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 number A timestamp of when the credentials’ status was last updated.
supplementalInformation string A key-value structure to handle if status of credentials are AWAITING_SUPPLEMENTAL_INFORMATION.
type string The type of credentials.. Values: PASSWORD, MOBILE_BANKID, KEYFOB, THIRD_PARTY_APP
updated number A timestamp of when the credentials was the last time in status UPDATED.
userId string The id of the user that the credentials belongs to.

Delete credentials

Deletes the given credentials.

DELETE /api/v1/credentials/{id}

Parameters

Parameter Required Description
id true The id of the credentials

Get credentials

Gets credentials by id.

GET /api/v1/credentials/{id}

Parameters

Parameter Required Description
id true The id of the credentials

Response Example

{
  "fields": {
    "username": "198410045701"
  },
  "id": "6e68cc6287704273984567b3300c5822",
  "providerName": "handelsbanken-bankid",
  "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 Type Required Description
fields object 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 string The id of the credentials.
providerName string true The provider (financial institute) that the credentials belongs to.
status string The status of 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
statusPayload string 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 number A timestamp of when the credentials’ status was last updated.
supplementalInformation string A key-value structure to handle if status of credentials are AWAITING_SUPPLEMENTAL_INFORMATION.
type string The type of credentials.. Values: PASSWORD, MOBILE_BANKID, KEYFOB, THIRD_PARTY_APP
updated number A timestamp of when the credentials was the last time in status UPDATED.
userId string The id of the user that the credentials belongs to.

Update credentials

Updates the specified credentials.

PUT /api/v1/credentials/{id}

Request Example

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

Parameters

Parameter Required Description
id true The id of the credentials

Request Body: Credentials

The new credentials object

Parameter Type Required Description
fields object 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 string The id of the credentials.
providerName string true The provider (financial institute) that the credentials belongs to.
status string The status of 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
statusPayload string 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 number A timestamp of when the credentials’ status was last updated.
supplementalInformation string A key-value structure to handle if status of credentials are AWAITING_SUPPLEMENTAL_INFORMATION.
type string The type of credentials.. Values: PASSWORD, MOBILE_BANKID, KEYFOB, THIRD_PARTY_APP
updated number A timestamp of when the credentials was the last time in status UPDATED.
userId string The id of the user that the credentials belongs to.

Response Example

{
  "fields": {
    "username": "198410045701"
  },
  "id": "6e68cc6287704273984567b3300c5822",
  "providerName": "handelsbanken-bankid",
  "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 Type Required Description
fields object 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 string The id of the credentials.
providerName string true The provider (financial institute) that the credentials belongs to.
status string The status of 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
statusPayload string 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 number A timestamp of when the credentials’ status was last updated.
supplementalInformation string A key-value structure to handle if status of credentials are AWAITING_SUPPLEMENTAL_INFORMATION.
type string The type of credentials.. Values: PASSWORD, MOBILE_BANKID, KEYFOB, THIRD_PARTY_APP
updated number A timestamp of when the credentials was the last time in status UPDATED.
userId string The id of the user that the credentials belongs to.

Refresh credentials

Refreshes the specified credentials.

POST /api/v1/credentials/{id}/refresh

Parameters

Parameter Required Description
id true The internal identifier of the Credentials object to refresh.

Query Parameters

Parameter Required Description
items The data types to download from aggregated Provider. Multiple items are allowed. If omitted, everything is downloaded.. Values: CHECKING_ACCOUNTS, CHECKING_TRANSACTIONS, SAVING_ACCOUNTS, SAVING_TRANSACTIONS, CREDITCARD_ACCOUNTS, CREDITCARD_TRANSACTIONS, LOAN_ACCOUNTS, LOAN_TRANSACTIONS, INVESTMENT_ACCOUNTS, INVESTMENT_TRANSACTIONS, EINVOICES, TRANSFER_DESTINATIONS
optIn Set to true to trigger an opt-in of accounts before doing the refresh (Contact us if you are interested of this feature).

Add Supplemental Information

Adds supplemental information to an authentication.

POST /api/v1/credentials/{id}/supplemental-information

Request Example

{
  "information": {
    "code": "123456",
    "name2": "value2"
  }
}

Parameters

Parameter Required Description
id true

Request Body: SupplementalInformation

The supplemental information.

Parameter Type Required Description
information object A key-value structure, use “name”:“value” from the fields found in supplementalInformation on the Credentials when status is AWAITING_SUPPLEMENTAL_INFORMATION.

Device Service

List all devices

Lists all devices.

GET /api/v1/devices

Response Example

{
  "devices": [
    {
      "appId": "se.tink.android",
      "created": 1455740874875,
      "deviceName": "Fredrik's iPhone",
      "deviceToken": "51ed6c20-dad6-4270-a4f2-56648f442047",
      "notificationToken": "LRJ2bFzHA1jUIkwayDqxteNsWY3udejkEe9UwRMt12E_R5i...",
      "publicKey": "MIIC7DCCAdQCAQEwDQYJKoZIhvcNAQELBQAwPDE6MDgGA1UEAwwxTXlTUUxfU2Vy...",
      "type": "android",
      "updated": 1455740874875,
      "userAgent": "Tink Mobile/1.7.8 (Android; 4.4.2, LGE Nexus 4)"
    }
  ]
}

Response: DeviceListResponse

Parameter Type Required Description
devices array[Device] true The list of devices

Device

Parameter Type Required Description
appId string true The app ID of the app that registers the device
created number Date when the device was first created
deviceName string true The device name
deviceToken string true A device token, should be unique per device and app
notificationToken string true The APN or GCM token
publicKey string Public key for sending encrypted push notifications to the device
type string true The operating system of the device
updated number Date when the device was last updated
userAgent string true The User-Agent of the device

Delete a device

Deletes the device. Does not require an authenticated user.

DELETE /api/v1/devices/{deviceToken}

Parameters

Parameter Required Description
deviceToken true The (persistent) deviceToken

Update a device

Updates a device for the authenticated user. If the same notificationToken would exist on some another user, it will be removed from that user. If the deviceToken is registered already with a different push token, it will be updated to the latest one.

PUT /api/v1/devices/{deviceToken}

Request Example

{
  "appId": "se.tink.android",
  "created": 1455740874875,
  "deviceName": "Fredrik's iPhone",
  "deviceToken": "51ed6c20-dad6-4270-a4f2-56648f442047",
  "notificationToken": "LRJ2bFzHA1jUIkwayDqxteNsWY3udejkEe9UwRMt12E_R5i...",
  "publicKey": "MIIC7DCCAdQCAQEwDQYJKoZIhvcNAQELBQAwPDE6MDgGA1UEAwwxTXlTUUxfU2Vy...",
  "type": "android",
  "updated": 1455740874875,
  "userAgent": "Tink Mobile/1.7.8 (Android; 4.4.2, LGE Nexus 4)"
}

Parameters

Parameter Required Description
deviceToken true The (persistent) deviceToken

Request Body: Device

The token and some meta data around it

Parameter Type Required Description
appId string true The app ID of the app that registers the device
created number Date when the device was first created
deviceName string true The device name
deviceToken string true A device token, should be unique per device and app
notificationToken string true The APN or GCM token
publicKey string Public key for sending encrypted push notifications to the device
type string true The operating system of the device
updated number Date when the device was last updated
userAgent string true The User-Agent of the device

Get device configuration

Get device configuration based on device token and optionally market code (default market is SE)

GET /api/v1/devices/{deviceToken}/configuration

Parameters

Parameter Required Description
deviceToken true Device token

Query Parameters

Parameter Required Description
desiredMarket Provide market code, e.g. SE, US, NO etc.

Response Example

{
  "flags": [
    "string",
    "string"
  ],
  "markets": [
    {
      "code": "SE",
      "currencies": [
        {
          "code": "SEK",
          "factor": 10,
          "prefixed": false,
          "symbol": "kr"
        }
      ],
      "defaultCurrency": "SEK",
      "defaultLocale": "sv_SE",
      "defaultTimeZone": "Europe/Stockholm",
      "description": "Sweden",
      "gdprLoginMethods": [
        "string",
        "string"
      ],
      "loginMethods": [
        "string",
        "string"
      ],
      "registerMethods": [
        "string",
        "string"
      ],
      "suggested": false
    }
  ]
}

Response: DeviceConfigurationDto

Parameter Type Required Description
flags array[string]
markets array[Market]

Market

Parameter Type Required Description
code string true The ISO 3166-1 alpha-2 country code of the market.. Values: AT, AU, BE, BG, BR, CA, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IN, IT, LU, LV, MT, NL, NO, NZ, PL, PT, RO, SE, SG, SI, SK, UK, US
currencies array[Currency] true The applicable currencies available in the market.
defaultCurrency string true The ISO 4217 code of the default currency.
defaultLocale string true The default locale in the market.
defaultTimeZone string true The default time zone in the market.
description string true The display name of the market
gdprLoginMethods array[string]
loginMethods array[string]
registerMethods array[string]
suggested boolean true Flag to indicate if this is the suggested market for the user.

Currency

Parameter Type Required Description
code string true The ISO 4217 code of the currency.
factor number true An approximate currency conversion factor to inversely scale triggers to the EUR currency.
prefixed boolean true Indicates that the currency symbol should prefix the amount.
symbol string true The symbol of the currency.

Follow Service

Create Follow Item

Creates a follow item.

POST /api/v1/follow

Request Example

{
  "criteria": "{\"targetAmount\":500,\"categoryIds\":[\"c0d99a4058854b8681154ab91c3c5830\"]}",
  "data": {
    "historicalAmounts": [
      {
        "key": "string",
        "value": 0
      }
    ],
    "period": "2017-05",
    "periodAmounts": [
      {
        "key": "string",
        "value": 0
      }
    ],
    "periodProgress": 0,
    "periodTransactions": [
      {
        "accountId": "3fe2d96efacd4dc5994404a950f238a9",
        "amount": 34,
        "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
        "categoryType": "EXPENSES",
        "credentialsId": "65bc7a41a66e4ad1aad199bbfb3c5098",
        "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": {},
        "payload": {},
        "pending": false,
        "timestamp": 1464543093494,
        "type": "CREDIT_CARD",
        "upcoming": false,
        "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
        "userModified": false
      }
    ]
  },
  "id": "e2b746ed27c542ce846a8d693474df21",
  "name": "Coffee budget",
  "type": "EXPENSES"
}

Request Body: FollowItem

The follow item to create

Parameter Type Required Description
criteria string true A serialized json string with the criteria for the Follow Item. For all types of Follow Items, there is the parameter targetAmount that sets the goal of budget/goal. For EXPENSES there is also categoryIds which is an array of category id strings. For SEARCH there is queryString, that is the search query that would be followed. Finally, for SAVINGS there is the string targetPeriod (yyyy-mm) which sets the goal month, and the array of strings accountIds.
data FollowData Returned when getting one FollowItem. Contains statistics for the queried period.
id string The id of the Follow Item.
name string true The name of the Follow Item.
type string true The type of the Follow Item.. Values: EXPENSES, SEARCH, SAVINGS

FollowData

Parameter Type Required Description
historicalAmounts array[StringDoublePair] A list of string-double pairs. Has one value for the sum of expenses (ie. EXPENSES or SEARCH type) or account balance (ie. SAVINGS type) for each previous month period (MONTHLY or MONTHLY_ADJUSTED).
period string The period (yyyy-mm) for which this data belongs to. Period is always MONTHLY or MONTHLY_ADJUSTED.
periodAmounts array[StringDoublePair] A list of string-double pairs. Has one value for the cumulative sum of expenses (ie. EXPENSES or SEARCH type) or account balance (ie. SAVINGS type) for each day in period.
periodProgress number A progress indicator between 0 and 1 of the current period. First day of period is 0 and last day of period is 1.
periodTransactions array[Transaction] A list of transactions that this Follow Item and period consists of.

StringDoublePair

Parameter Type Required Description
key string
value number

Transaction

Parameter Type Required Description
accountId string true The internal identifier of the account that the transaction belongs to.
amount number true The amount of the transaction. This can be modified by the user.
categoryId string true The category of the transaction. This can be modified by the user.
categoryType string true The category type of the transaction.. Values: INCOME, EXPENSES, TRANSFERS
credentialsId string true The internal identifier of the credentials that the transaction belongs to.
date number true The date the transaction was executed. This can be modified by the user.
description string true The description of the transaction. This can be modified by the user.
dispensableAmount number The dispensable amount of the transaction.
id string true The internal identifier of the transaction.
lastModified number true The date the transaction was last modified by the user.
merchantId string The internal identifier of the merchant that the transaction belongs to. If available.
notes string 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 number true The original amount that was received from the provider, before the user changed it.
originalDate number true The original date that was received from the provider, before the user changed it.
originalDescription string true The original description that was received from the provider, before the user changed it.
partnerPayload object The payload that was previously ingested on the Connector API.
payload object Meta data about the transaction, in key value format with Strings.
pending boolean true Indicates if this transaction has been settled or is still pending.
timestamp integer true The timestamp of when the transaction was first saved to database.
type string true The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL
upcoming boolean Indicates if this is an upcoming transaction not booked yet.
userId string true The internal identifier of the user that the transaction belongs to.
userModified boolean

Response Example

{
  "criteria": "{\"targetAmount\":500,\"categoryIds\":[\"c0d99a4058854b8681154ab91c3c5830\"]}",
  "data": {
    "historicalAmounts": [
      {
        "key": "string",
        "value": 0
      }
    ],
    "period": "2017-05",
    "periodAmounts": [
      {
        "key": "string",
        "value": 0
      }
    ],
    "periodProgress": 0,
    "periodTransactions": [
      {
        "accountId": "3fe2d96efacd4dc5994404a950f238a9",
        "amount": 34,
        "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
        "categoryType": "EXPENSES",
        "credentialsId": "65bc7a41a66e4ad1aad199bbfb3c5098",
        "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": {},
        "payload": {},
        "pending": false,
        "timestamp": 1464543093494,
        "type": "CREDIT_CARD",
        "upcoming": false,
        "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
        "userModified": false
      }
    ]
  },
  "id": "e2b746ed27c542ce846a8d693474df21",
  "name": "Coffee budget",
  "type": "EXPENSES"
}

Response: FollowItem

Parameter Type Required Description
criteria string true A serialized json string with the criteria for the Follow Item. For all types of Follow Items, there is the parameter targetAmount that sets the goal of budget/goal. For EXPENSES there is also categoryIds which is an array of category id strings. For SEARCH there is queryString, that is the search query that would be followed. Finally, for SAVINGS there is the string targetPeriod (yyyy-mm) which sets the goal month, and the array of strings accountIds.
data FollowData Returned when getting one FollowItem. Contains statistics for the queried period.
id string The id of the Follow Item.
name string true The name of the Follow Item.
type string true The type of the Follow Item.. Values: EXPENSES, SEARCH, SAVINGS

FollowData

Parameter Type Required Description
historicalAmounts array[StringDoublePair] A list of string-double pairs. Has one value for the sum of expenses (ie. EXPENSES or SEARCH type) or account balance (ie. SAVINGS type) for each previous month period (MONTHLY or MONTHLY_ADJUSTED).
period string The period (yyyy-mm) for which this data belongs to. Period is always MONTHLY or MONTHLY_ADJUSTED.
periodAmounts array[StringDoublePair] A list of string-double pairs. Has one value for the cumulative sum of expenses (ie. EXPENSES or SEARCH type) or account balance (ie. SAVINGS type) for each day in period.
periodProgress number A progress indicator between 0 and 1 of the current period. First day of period is 0 and last day of period is 1.
periodTransactions array[Transaction] A list of transactions that this Follow Item and period consists of.

StringDoublePair

Parameter Type Required Description
key string
value number

Transaction

Parameter Type Required Description
accountId string true The internal identifier of the account that the transaction belongs to.
amount number true The amount of the transaction. This can be modified by the user.
categoryId string true The category of the transaction. This can be modified by the user.
categoryType string true The category type of the transaction.. Values: INCOME, EXPENSES, TRANSFERS
credentialsId string true The internal identifier of the credentials that the transaction belongs to.
date number true The date the transaction was executed. This can be modified by the user.
description string true The description of the transaction. This can be modified by the user.
dispensableAmount number The dispensable amount of the transaction.
id string true The internal identifier of the transaction.
lastModified number true The date the transaction was last modified by the user.
merchantId string The internal identifier of the merchant that the transaction belongs to. If available.
notes string 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 number true The original amount that was received from the provider, before the user changed it.
originalDate number true The original date that was received from the provider, before the user changed it.
originalDescription string true The original description that was received from the provider, before the user changed it.
partnerPayload object The payload that was previously ingested on the Connector API.
payload object Meta data about the transaction, in key value format with Strings.
pending boolean true Indicates if this transaction has been settled or is still pending.
timestamp integer true The timestamp of when the transaction was first saved to database.
type string true The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL
upcoming boolean Indicates if this is an upcoming transaction not booked yet.
userId string true The internal identifier of the user that the transaction belongs to.
userModified boolean

List Follow Items

Lists all follow items. For list Follow Items, no transactions are populated on the Follow Data objects.

GET /api/v1/follow/list

Query Parameters

Parameter Required Description
period The period (yyyy-mm) to fetch data for. Defaults to current month.

Response Example

{
  "followItems": [
    {
      "criteria": "{\"targetAmount\":500,\"categoryIds\":[\"c0d99a4058854b8681154ab91c3c5830\"]}",
      "data": {
        "historicalAmounts": [
          {
            "key": "string",
            "value": 0
          }
        ],
        "period": "2017-05",
        "periodAmounts": [
          {
            "key": "string",
            "value": 0
          }
        ],
        "periodProgress": 0,
        "periodTransactions": [
          {
            "accountId": "3fe2d96efacd4dc5994404a950f238a9",
            "amount": 34,
            "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
            "categoryType": "EXPENSES",
            "credentialsId": "65bc7a41a66e4ad1aad199bbfb3c5098",
            "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": {},
            "payload": {},
            "pending": false,
            "timestamp": 1464543093494,
            "type": "CREDIT_CARD",
            "upcoming": false,
            "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
            "userModified": false
          }
        ]
      },
      "id": "e2b746ed27c542ce846a8d693474df21",
      "name": "Coffee budget",
      "type": "EXPENSES"
    }
  ]
}

Response: FollowItemListResponse

Parameter Type Required Description
followItems array[FollowItem] A list of follow items.

FollowItem

Parameter Type Required Description
criteria string true A serialized json string with the criteria for the Follow Item. For all types of Follow Items, there is the parameter targetAmount that sets the goal of budget/goal. For EXPENSES there is also categoryIds which is an array of category id strings. For SEARCH there is queryString, that is the search query that would be followed. Finally, for SAVINGS there is the string targetPeriod (yyyy-mm) which sets the goal month, and the array of strings accountIds.
data FollowData Returned when getting one FollowItem. Contains statistics for the queried period.
id string The id of the Follow Item.
name string true The name of the Follow Item.
type string true The type of the Follow Item.. Values: EXPENSES, SEARCH, SAVINGS

FollowData

Parameter Type Required Description
historicalAmounts array[StringDoublePair] A list of string-double pairs. Has one value for the sum of expenses (ie. EXPENSES or SEARCH type) or account balance (ie. SAVINGS type) for each previous month period (MONTHLY or MONTHLY_ADJUSTED).
period string The period (yyyy-mm) for which this data belongs to. Period is always MONTHLY or MONTHLY_ADJUSTED.
periodAmounts array[StringDoublePair] A list of string-double pairs. Has one value for the cumulative sum of expenses (ie. EXPENSES or SEARCH type) or account balance (ie. SAVINGS type) for each day in period.
periodProgress number A progress indicator between 0 and 1 of the current period. First day of period is 0 and last day of period is 1.
periodTransactions array[Transaction] A list of transactions that this Follow Item and period consists of.

StringDoublePair

Parameter Type Required Description
key string
value number

Transaction

Parameter Type Required Description
accountId string true The internal identifier of the account that the transaction belongs to.
amount number true The amount of the transaction. This can be modified by the user.
categoryId string true The category of the transaction. This can be modified by the user.
categoryType string true The category type of the transaction.. Values: INCOME, EXPENSES, TRANSFERS
credentialsId string true The internal identifier of the credentials that the transaction belongs to.
date number true The date the transaction was executed. This can be modified by the user.
description string true The description of the transaction. This can be modified by the user.
dispensableAmount number The dispensable amount of the transaction.
id string true The internal identifier of the transaction.
lastModified number true The date the transaction was last modified by the user.
merchantId string The internal identifier of the merchant that the transaction belongs to. If available.
notes string 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 number true The original amount that was received from the provider, before the user changed it.
originalDate number true The original date that was received from the provider, before the user changed it.
originalDescription string true The original description that was received from the provider, before the user changed it.
partnerPayload object The payload that was previously ingested on the Connector API.
payload object Meta data about the transaction, in key value format with Strings.
pending boolean true Indicates if this transaction has been settled or is still pending.
timestamp integer true The timestamp of when the transaction was first saved to database.
type string true The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL
upcoming boolean Indicates if this is an upcoming transaction not booked yet.
userId string true The internal identifier of the user that the transaction belongs to.
userModified boolean

Create multiple Follow Items

Creates multiple Follow Items

POST /api/v1/follow/multiple

Request Example

{
  "criteria": "{\"targetAmount\":500,\"categoryIds\":[\"c0d99a4058854b8681154ab91c3c5830\"]}",
  "data": {
    "historicalAmounts": [
      {
        "key": "string",
        "value": 0
      }
    ],
    "period": "2017-05",
    "periodAmounts": [
      {
        "key": "string",
        "value": 0
      }
    ],
    "periodProgress": 0,
    "periodTransactions": [
      {
        "accountId": "3fe2d96efacd4dc5994404a950f238a9",
        "amount": 34,
        "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
        "categoryType": "EXPENSES",
        "credentialsId": "65bc7a41a66e4ad1aad199bbfb3c5098",
        "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": {},
        "payload": {},
        "pending": false,
        "timestamp": 1464543093494,
        "type": "CREDIT_CARD",
        "upcoming": false,
        "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
        "userModified": false
      }
    ]
  },
  "id": "e2b746ed27c542ce846a8d693474df21",
  "name": "Coffee budget",
  "type": "EXPENSES"
}

Request Body: FollowItem

A list of the follow items to create

Parameter Type Required Description
criteria string true A serialized json string with the criteria for the Follow Item. For all types of Follow Items, there is the parameter targetAmount that sets the goal of budget/goal. For EXPENSES there is also categoryIds which is an array of category id strings. For SEARCH there is queryString, that is the search query that would be followed. Finally, for SAVINGS there is the string targetPeriod (yyyy-mm) which sets the goal month, and the array of strings accountIds.
data FollowData Returned when getting one FollowItem. Contains statistics for the queried period.
id string The id of the Follow Item.
name string true The name of the Follow Item.
type string true The type of the Follow Item.. Values: EXPENSES, SEARCH, SAVINGS

FollowData

Parameter Type Required Description
historicalAmounts array[StringDoublePair] A list of string-double pairs. Has one value for the sum of expenses (ie. EXPENSES or SEARCH type) or account balance (ie. SAVINGS type) for each previous month period (MONTHLY or MONTHLY_ADJUSTED).
period string The period (yyyy-mm) for which this data belongs to. Period is always MONTHLY or MONTHLY_ADJUSTED.
periodAmounts array[StringDoublePair] A list of string-double pairs. Has one value for the cumulative sum of expenses (ie. EXPENSES or SEARCH type) or account balance (ie. SAVINGS type) for each day in period.
periodProgress number A progress indicator between 0 and 1 of the current period. First day of period is 0 and last day of period is 1.
periodTransactions array[Transaction] A list of transactions that this Follow Item and period consists of.

StringDoublePair

Parameter Type Required Description
key string
value number

Transaction

Parameter Type Required Description
accountId string true The internal identifier of the account that the transaction belongs to.
amount number true The amount of the transaction. This can be modified by the user.
categoryId string true The category of the transaction. This can be modified by the user.
categoryType string true The category type of the transaction.. Values: INCOME, EXPENSES, TRANSFERS
credentialsId string true The internal identifier of the credentials that the transaction belongs to.
date number true The date the transaction was executed. This can be modified by the user.
description string true The description of the transaction. This can be modified by the user.
dispensableAmount number The dispensable amount of the transaction.
id string true The internal identifier of the transaction.
lastModified number true The date the transaction was last modified by the user.
merchantId string The internal identifier of the merchant that the transaction belongs to. If available.
notes string 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 number true The original amount that was received from the provider, before the user changed it.
originalDate number true The original date that was received from the provider, before the user changed it.
originalDescription string true The original description that was received from the provider, before the user changed it.
partnerPayload object The payload that was previously ingested on the Connector API.
payload object Meta data about the transaction, in key value format with Strings.
pending boolean true Indicates if this transaction has been settled or is still pending.
timestamp integer true The timestamp of when the transaction was first saved to database.
type string true The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL
upcoming boolean Indicates if this is an upcoming transaction not booked yet.
userId string true The internal identifier of the user that the transaction belongs to.
userModified boolean

Response Example

[
  {
    "criteria": "{\"targetAmount\":500,\"categoryIds\":[\"c0d99a4058854b8681154ab91c3c5830\"]}",
    "data": {
      "historicalAmounts": [
        {
          "key": "string",
          "value": 0
        }
      ],
      "period": "2017-05",
      "periodAmounts": [
        {
          "key": "string",
          "value": 0
        }
      ],
      "periodProgress": 0,
      "periodTransactions": [
        {
          "accountId": "3fe2d96efacd4dc5994404a950f238a9",
          "amount": 34,
          "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
          "categoryType": "EXPENSES",
          "credentialsId": "65bc7a41a66e4ad1aad199bbfb3c5098",
          "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": {},
          "payload": {},
          "pending": false,
          "timestamp": 1464543093494,
          "type": "CREDIT_CARD",
          "upcoming": false,
          "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
          "userModified": false
        }
      ]
    },
    "id": "e2b746ed27c542ce846a8d693474df21",
    "name": "Coffee budget",
    "type": "EXPENSES"
  }
]

Response: array[FollowItem]

Parameter Type Required Description
criteria string true A serialized json string with the criteria for the Follow Item. For all types of Follow Items, there is the parameter targetAmount that sets the goal of budget/goal. For EXPENSES there is also categoryIds which is an array of category id strings. For SEARCH there is queryString, that is the search query that would be followed. Finally, for SAVINGS there is the string targetPeriod (yyyy-mm) which sets the goal month, and the array of strings accountIds.
data FollowData Returned when getting one FollowItem. Contains statistics for the queried period.
id string The id of the Follow Item.
name string true The name of the Follow Item.
type string true The type of the Follow Item.. Values: EXPENSES, SEARCH, SAVINGS

FollowData

Parameter Type Required Description
historicalAmounts array[StringDoublePair] A list of string-double pairs. Has one value for the sum of expenses (ie. EXPENSES or SEARCH type) or account balance (ie. SAVINGS type) for each previous month period (MONTHLY or MONTHLY_ADJUSTED).
period string The period (yyyy-mm) for which this data belongs to. Period is always MONTHLY or MONTHLY_ADJUSTED.
periodAmounts array[StringDoublePair] A list of string-double pairs. Has one value for the cumulative sum of expenses (ie. EXPENSES or SEARCH type) or account balance (ie. SAVINGS type) for each day in period.
periodProgress number A progress indicator between 0 and 1 of the current period. First day of period is 0 and last day of period is 1.
periodTransactions array[Transaction] A list of transactions that this Follow Item and period consists of.

StringDoublePair

Parameter Type Required Description
key string
value number

Transaction

Parameter Type Required Description
accountId string true The internal identifier of the account that the transaction belongs to.
amount number true The amount of the transaction. This can be modified by the user.
categoryId string true The category of the transaction. This can be modified by the user.
categoryType string true The category type of the transaction.. Values: INCOME, EXPENSES, TRANSFERS
credentialsId string true The internal identifier of the credentials that the transaction belongs to.
date number true The date the transaction was executed. This can be modified by the user.
description string true The description of the transaction. This can be modified by the user.
dispensableAmount number The dispensable amount of the transaction.
id string true The internal identifier of the transaction.
lastModified number true The date the transaction was last modified by the user.
merchantId string The internal identifier of the merchant that the transaction belongs to. If available.
notes string 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 number true The original amount that was received from the provider, before the user changed it.
originalDate number true The original date that was received from the provider, before the user changed it.
originalDescription string true The original description that was received from the provider, before the user changed it.
partnerPayload object The payload that was previously ingested on the Connector API.
payload object Meta data about the transaction, in key value format with Strings.
pending boolean true Indicates if this transaction has been settled or is still pending.
timestamp integer true The timestamp of when the transaction was first saved to database.
type string true The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL
upcoming boolean Indicates if this is an upcoming transaction not booked yet.
userId string true The internal identifier of the user that the transaction belongs to.
userModified boolean

Delete Follow Item

Deletes a follow item.

DELETE /api/v1/follow/{id}

Parameters

Parameter Required Description
id true The id of the follow item to delete

Get Follow Item

Gets a follow item on id.

GET /api/v1/follow/{id}

Parameters

Parameter Required Description
id true The id of the follow item

Query Parameters

Parameter Required Description
period The period (yyyy-mm) to fetch data for. Defaults to current month.

Response Example

{
  "criteria": "{\"targetAmount\":500,\"categoryIds\":[\"c0d99a4058854b8681154ab91c3c5830\"]}",
  "data": {
    "historicalAmounts": [
      {
        "key": "string",
        "value": 0
      }
    ],
    "period": "2017-05",
    "periodAmounts": [
      {
        "key": "string",
        "value": 0
      }
    ],
    "periodProgress": 0,
    "periodTransactions": [
      {
        "accountId": "3fe2d96efacd4dc5994404a950f238a9",
        "amount": 34,
        "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
        "categoryType": "EXPENSES",
        "credentialsId": "65bc7a41a66e4ad1aad199bbfb3c5098",
        "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": {},
        "payload": {},
        "pending": false,
        "timestamp": 1464543093494,
        "type": "CREDIT_CARD",
        "upcoming": false,
        "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
        "userModified": false
      }
    ]
  },
  "id": "e2b746ed27c542ce846a8d693474df21",
  "name": "Coffee budget",
  "type": "EXPENSES"
}

Response: FollowItem

Parameter Type Required Description
criteria string true A serialized json string with the criteria for the Follow Item. For all types of Follow Items, there is the parameter targetAmount that sets the goal of budget/goal. For EXPENSES there is also categoryIds which is an array of category id strings. For SEARCH there is queryString, that is the search query that would be followed. Finally, for SAVINGS there is the string targetPeriod (yyyy-mm) which sets the goal month, and the array of strings accountIds.
data FollowData Returned when getting one FollowItem. Contains statistics for the queried period.
id string The id of the Follow Item.
name string true The name of the Follow Item.
type string true The type of the Follow Item.. Values: EXPENSES, SEARCH, SAVINGS

FollowData

Parameter Type Required Description
historicalAmounts array[StringDoublePair] A list of string-double pairs. Has one value for the sum of expenses (ie. EXPENSES or SEARCH type) or account balance (ie. SAVINGS type) for each previous month period (MONTHLY or MONTHLY_ADJUSTED).
period string The period (yyyy-mm) for which this data belongs to. Period is always MONTHLY or MONTHLY_ADJUSTED.
periodAmounts array[StringDoublePair] A list of string-double pairs. Has one value for the cumulative sum of expenses (ie. EXPENSES or SEARCH type) or account balance (ie. SAVINGS type) for each day in period.
periodProgress number A progress indicator between 0 and 1 of the current period. First day of period is 0 and last day of period is 1.
periodTransactions array[Transaction] A list of transactions that this Follow Item and period consists of.

StringDoublePair

Parameter Type Required Description
key string
value number

Transaction

Parameter Type Required Description
accountId string true The internal identifier of the account that the transaction belongs to.
amount number true The amount of the transaction. This can be modified by the user.
categoryId string true The category of the transaction. This can be modified by the user.
categoryType string true The category type of the transaction.. Values: INCOME, EXPENSES, TRANSFERS
credentialsId string true The internal identifier of the credentials that the transaction belongs to.
date number true The date the transaction was executed. This can be modified by the user.
description string true The description of the transaction. This can be modified by the user.
dispensableAmount number The dispensable amount of the transaction.
id string true The internal identifier of the transaction.
lastModified number true The date the transaction was last modified by the user.
merchantId string The internal identifier of the merchant that the transaction belongs to. If available.
notes string 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 number true The original amount that was received from the provider, before the user changed it.
originalDate number true The original date that was received from the provider, before the user changed it.
originalDescription string true The original description that was received from the provider, before the user changed it.
partnerPayload object The payload that was previously ingested on the Connector API.
payload object Meta data about the transaction, in key value format with Strings.
pending boolean true Indicates if this transaction has been settled or is still pending.
timestamp integer true The timestamp of when the transaction was first saved to database.
type string true The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL
upcoming boolean Indicates if this is an upcoming transaction not booked yet.
userId string true The internal identifier of the user that the transaction belongs to.
userModified boolean

Update Follow Item

Updates a follow item. Name and Criteria is updatable.

PUT /api/v1/follow/{id}

Request Example

{
  "criteria": "{\"targetAmount\":500,\"categoryIds\":[\"c0d99a4058854b8681154ab91c3c5830\"]}",
  "data": {
    "historicalAmounts": [
      {
        "key": "string",
        "value": 0
      }
    ],
    "period": "2017-05",
    "periodAmounts": [
      {
        "key": "string",
        "value": 0
      }
    ],
    "periodProgress": 0,
    "periodTransactions": [
      {
        "accountId": "3fe2d96efacd4dc5994404a950f238a9",
        "amount": 34,
        "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
        "categoryType": "EXPENSES",
        "credentialsId": "65bc7a41a66e4ad1aad199bbfb3c5098",
        "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": {},
        "payload": {},
        "pending": false,
        "timestamp": 1464543093494,
        "type": "CREDIT_CARD",
        "upcoming": false,
        "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
        "userModified": false
      }
    ]
  },
  "id": "e2b746ed27c542ce846a8d693474df21",
  "name": "Coffee budget",
  "type": "EXPENSES"
}

Parameters

Parameter Required Description
id true The id of the follow item to update

Request Body: FollowItem

The new follow item

Parameter Type Required Description
criteria string true A serialized json string with the criteria for the Follow Item. For all types of Follow Items, there is the parameter targetAmount that sets the goal of budget/goal. For EXPENSES there is also categoryIds which is an array of category id strings. For SEARCH there is queryString, that is the search query that would be followed. Finally, for SAVINGS there is the string targetPeriod (yyyy-mm) which sets the goal month, and the array of strings accountIds.
data FollowData Returned when getting one FollowItem. Contains statistics for the queried period.
id string The id of the Follow Item.
name string true The name of the Follow Item.
type string true The type of the Follow Item.. Values: EXPENSES, SEARCH, SAVINGS

FollowData

Parameter Type Required Description
historicalAmounts array[StringDoublePair] A list of string-double pairs. Has one value for the sum of expenses (ie. EXPENSES or SEARCH type) or account balance (ie. SAVINGS type) for each previous month period (MONTHLY or MONTHLY_ADJUSTED).
period string The period (yyyy-mm) for which this data belongs to. Period is always MONTHLY or MONTHLY_ADJUSTED.
periodAmounts array[StringDoublePair] A list of string-double pairs. Has one value for the cumulative sum of expenses (ie. EXPENSES or SEARCH type) or account balance (ie. SAVINGS type) for each day in period.
periodProgress number A progress indicator between 0 and 1 of the current period. First day of period is 0 and last day of period is 1.
periodTransactions array[Transaction] A list of transactions that this Follow Item and period consists of.

StringDoublePair

Parameter Type Required Description
key string
value number

Transaction

Parameter Type Required Description
accountId string true The internal identifier of the account that the transaction belongs to.
amount number true The amount of the transaction. This can be modified by the user.
categoryId string true The category of the transaction. This can be modified by the user.
categoryType string true The category type of the transaction.. Values: INCOME, EXPENSES, TRANSFERS
credentialsId string true The internal identifier of the credentials that the transaction belongs to.
date number true The date the transaction was executed. This can be modified by the user.
description string true The description of the transaction. This can be modified by the user.
dispensableAmount number The dispensable amount of the transaction.
id string true The internal identifier of the transaction.
lastModified number true The date the transaction was last modified by the user.
merchantId string The internal identifier of the merchant that the transaction belongs to. If available.
notes string 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 number true The original amount that was received from the provider, before the user changed it.
originalDate number true The original date that was received from the provider, before the user changed it.
originalDescription string true The original description that was received from the provider, before the user changed it.
partnerPayload object The payload that was previously ingested on the Connector API.
payload object Meta data about the transaction, in key value format with Strings.
pending boolean true Indicates if this transaction has been settled or is still pending.
timestamp integer true The timestamp of when the transaction was first saved to database.
type string true The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL
upcoming boolean Indicates if this is an upcoming transaction not booked yet.
userId string true The internal identifier of the user that the transaction belongs to.
userModified boolean

Response Example

{
  "criteria": "{\"targetAmount\":500,\"categoryIds\":[\"c0d99a4058854b8681154ab91c3c5830\"]}",
  "data": {
    "historicalAmounts": [
      {
        "key": "string",
        "value": 0
      }
    ],
    "period": "2017-05",
    "periodAmounts": [
      {
        "key": "string",
        "value": 0
      }
    ],
    "periodProgress": 0,
    "periodTransactions": [
      {
        "accountId": "3fe2d96efacd4dc5994404a950f238a9",
        "amount": 34,
        "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
        "categoryType": "EXPENSES",
        "credentialsId": "65bc7a41a66e4ad1aad199bbfb3c5098",
        "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": {},
        "payload": {},
        "pending": false,
        "timestamp": 1464543093494,
        "type": "CREDIT_CARD",
        "upcoming": false,
        "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
        "userModified": false
      }
    ]
  },
  "id": "e2b746ed27c542ce846a8d693474df21",
  "name": "Coffee budget",
  "type": "EXPENSES"
}

Response: FollowItem

Parameter Type Required Description
criteria string true A serialized json string with the criteria for the Follow Item. For all types of Follow Items, there is the parameter targetAmount that sets the goal of budget/goal. For EXPENSES there is also categoryIds which is an array of category id strings. For SEARCH there is queryString, that is the search query that would be followed. Finally, for SAVINGS there is the string targetPeriod (yyyy-mm) which sets the goal month, and the array of strings accountIds.
data FollowData Returned when getting one FollowItem. Contains statistics for the queried period.
id string The id of the Follow Item.
name string true The name of the Follow Item.
type string true The type of the Follow Item.. Values: EXPENSES, SEARCH, SAVINGS

FollowData

Parameter Type Required Description
historicalAmounts array[StringDoublePair] A list of string-double pairs. Has one value for the sum of expenses (ie. EXPENSES or SEARCH type) or account balance (ie. SAVINGS type) for each previous month period (MONTHLY or MONTHLY_ADJUSTED).
period string The period (yyyy-mm) for which this data belongs to. Period is always MONTHLY or MONTHLY_ADJUSTED.
periodAmounts array[StringDoublePair] A list of string-double pairs. Has one value for the cumulative sum of expenses (ie. EXPENSES or SEARCH type) or account balance (ie. SAVINGS type) for each day in period.
periodProgress number A progress indicator between 0 and 1 of the current period. First day of period is 0 and last day of period is 1.
periodTransactions array[Transaction] A list of transactions that this Follow Item and period consists of.

StringDoublePair

Parameter Type Required Description
key string
value number

Transaction

Parameter Type Required Description
accountId string true The internal identifier of the account that the transaction belongs to.
amount number true The amount of the transaction. This can be modified by the user.
categoryId string true The category of the transaction. This can be modified by the user.
categoryType string true The category type of the transaction.. Values: INCOME, EXPENSES, TRANSFERS
credentialsId string true The internal identifier of the credentials that the transaction belongs to.
date number true The date the transaction was executed. This can be modified by the user.
description string true The description of the transaction. This can be modified by the user.
dispensableAmount number The dispensable amount of the transaction.
id string true The internal identifier of the transaction.
lastModified number true The date the transaction was last modified by the user.
merchantId string The internal identifier of the merchant that the transaction belongs to. If available.
notes string 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 number true The original amount that was received from the provider, before the user changed it.
originalDate number true The original date that was received from the provider, before the user changed it.
originalDescription string true The original description that was received from the provider, before the user changed it.
partnerPayload object The payload that was previously ingested on the Connector API.
payload object Meta data about the transaction, in key value format with Strings.
pending boolean true Indicates if this transaction has been settled or is still pending.
timestamp integer true The timestamp of when the transaction was first saved to database.
type string true The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL
upcoming boolean Indicates if this is an upcoming transaction not booked yet.
userId string true The internal identifier of the user that the transaction belongs to.
userModified boolean

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

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 Type Required Description
portfolios array[Portfolio] A list of the user’s portfolios.

Portfolio

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

Instrument

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

Loan

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

LoanDetails

Parameter Type Required Description
accountId string
applicants array[string]
coApplicant boolean
loanSecurity string

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 Type Required Description
loanEvents array[LoanEvent]

LoanEvent

Parameter Type Required Description
accountId string
balance number
credentials string
interest number
interestRateChange number
loanType string
nextDayOfTermsChange number
properties object
provider string
timestamp number
title string
type string

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 Type Required Description
loanTimelines array[LoanTimeline]
weightedAverageTimeline array[KVPairStringDouble]

LoanTimeline

Parameter Type Required Description
accountId string
balanceTimeline array[TemporalValueDouble]
interestRateTimeline array[TemporalValueDouble]

TemporalValueDouble

Parameter Type Required Description
date number
value number

KVPairStringDouble

Parameter Type Required Description
key string
value number

Update a loan

Updates certain user modifiable properties of a loan. Please refer to the body schema to see which properties are modifiable by the loan.

PUT /api/v1/loans/update

Request Example

{
  "accountId": "string",
  "balance": 0,
  "interest": 0,
  "loanType": "string"
}

Request Body: UpdateLoanRequest

The updated loan object

Parameter Type Required Description
accountId string
balance number
interest number
loanType string

Response Example

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

Response: Loan

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

LoanDetails

Parameter Type Required Description
accountId string
applicants array[string]
coApplicant boolean
loanSecurity string

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 Required Description
service Forwards the ping to another service (“aggregation”, “main” and “system”). Defaults to “main”.. Values: aggregation, system, main

Response: text/plain

successful operation

Notification Service

Query notifications

Queries notifications

POST /api/v1/notifications/query

Request Example

{
  "limit": 10,
  "offset": 0,
  "statuses": [
    "READ",
    "SENT"
  ]
}

Request Body: NotificationQuery

The query.

Parameter Type Required Description
limit integer The maximum number of notifications to return (when paging, 0 indicates no limit).
offset integer The number of notifications to skip (when paging).
statuses array[string] The set of notification statuses to be used as a query filter

Response Example

{
  "count": 45,
  "notifications": [
    {
      "date": 1455740874875,
      "generated": 1455740874875,
      "groupable": null,
      "key": "unusual-category-high.2016-05.18bb1f4636894f3bba8ddcd567d22fbd",
      "message": "You have spent more than usual on restaurants this month.",
      "sensitiveMessage": "You had an expense charged by H&M.",
      "sensitiveTitle": "Expense",
      "status": "READ",
      "title": "More than usual",
      "type": "unusual-category-high",
      "url": "tink://transactions/953c4eda24554a61a9653a479e70fc96"
    }
  ]
}

Response: NotificationQueryResponse

Parameter Type Required Description
count integer true The total number of notifications
notifications array[Notification] true The filtered list of notifications

Notification

Parameter Type Required Description
date number true The date for which the notification was generated
generated number true The date when the notification was generated
groupable boolean true Flag indicating whether or not the notification is groupable.
key string true The identifying key.
message string true The notification message.
sensitiveMessage string true The notification message if the notification is delivered encrypted.
sensitiveTitle string true The notification title if the notification is delivered encrypted. Used on Android as title and concatenated with the message on iOS.
status string true The notification status.. Values: CREATED, SENT, SENT_ENCRYPTED, RECEIVED, READ
title string true The notification title. Used on Android as title and concatenated with the message on iOS.
type string true The notification type
url string true The deep-link URL

Mark a notification as read

Marks a notification as read

POST /api/v1/notifications/{id}/read

Parameters

Parameter Required Description
id true The id of the notification

Mark a notification as received

Marks a notification as received (only to be used for acknowledging encrypted notifications)

POST /api/v1/notifications/{id}/received

Parameters

Parameter Required Description
id true The id of the notification

OAuth Service

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

Form Parameters

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

Response Example

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

Response: OAuth2AuthenticationTokenResponse

Parameter Type Required Description
access_token string true The access token that can be used to access an API resource.
expires_in integer true The amount of time in seconds for the expiration of the token.
refresh_token string true The refresh token that can be used to get a new access token.
scope string true The scope valid for the returned token.
token_type string true The type of authorization token returned.

Provider Service

Suggest providers for user

GET /api/v1/providers/suggest

Response Example

{
  "providers": [
    {
      "credentialsType": "MOBILE_BANKID",
      "currency": "SEK",
      "displayDescription": "Mobilt BankID",
      "displayName": "Handelsbanken",
      "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"
        }
      ],
      "groupDisplayName": "string",
      "images": {
        "banner": "string",
        "icon": "string"
      },
      "market": "string",
      "multiFactor": false,
      "name": "string",
      "passwordHelpText": "string",
      "popular": false,
      "status": "string",
      "supplementalFields": [
        {
          "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"
        }
      ],
      "transactional": false,
      "type": "string"
    }
  ]
}

Response: ProviderListResponse

Parameter Type Required Description
providers array[ProviderRpc]

ProviderRpc

Parameter Type Required Description
credentialsType string The type of credentials the provider creates. Values: PASSWORD, MOBILE_BANKID, KEYFOB, THIRD_PARTY_APP
currency string The default currency of the provider
displayDescription string The display description of the provider
displayName string The display name of the provider
fields array[Field]
groupDisplayName string The grouped display name of the provider
images ImageUrls
market string The market of the provider
multiFactor boolean Flag to indicate if the provider requires multi-factor authentication
name string The short name of the provider
passwordHelpText string
popular boolean Flag to indicate if the provider is popular
status string The current status of the provider. Values: ENABLED, OBSOLETE, TEMPORARY_DISABLED, DISABLED
supplementalFields array[Field]
transactional boolean Flag to indicate if the provider provides transactional data
type string The type of the provider. Values: BANK, CREDIT_CARD, BROKER, OTHER, TEST, FRAUD

Field

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

ImageUrls

Parameter Type Required Description
banner string
icon string

List providers by Market

List all providers on given Market. Since this is an endpoint that doesn’t require an authenticated user, API consumers should send their OAuth clientId as a header X-Tink-OAuth-Client-ID

GET /api/v1/providers/{market}

Parameters

Parameter Required Description
market true SE for Swedish market

Header Parameters

Parameter Required Description
X-Tink-OAuth-Client-ID true The OAuth2 Client ID
Accept-Language Language to translate to.

Query Parameters

Parameter Required Description
includeTestProviders Defaults to false. If set to true, Providers of TEST type will become ENABLED

Response Example

{
  "providers": [
    {
      "credentialsType": "MOBILE_BANKID",
      "currency": "SEK",
      "displayDescription": "Mobilt BankID",
      "displayName": "Handelsbanken",
      "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"
        }
      ],
      "groupDisplayName": "string",
      "images": {
        "banner": "string",
        "icon": "string"
      },
      "market": "string",
      "multiFactor": false,
      "name": "string",
      "passwordHelpText": "string",
      "popular": false,
      "status": "string",
      "supplementalFields": [
        {
          "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"
        }
      ],
      "transactional": false,
      "type": "string"
    }
  ]
}

Response: ProviderListResponse

Parameter Type Required Description
providers array[ProviderRpc]

ProviderRpc

Parameter Type Required Description
credentialsType string The type of credentials the provider creates. Values: PASSWORD, MOBILE_BANKID, KEYFOB, THIRD_PARTY_APP
currency string The default currency of the provider
displayDescription string The display description of the provider
displayName string The display name of the provider
fields array[Field]
groupDisplayName string The grouped display name of the provider
images ImageUrls
market string The market of the provider
multiFactor boolean Flag to indicate if the provider requires multi-factor authentication
name string The short name of the provider
passwordHelpText string
popular boolean Flag to indicate if the provider is popular
status string The current status of the provider. Values: ENABLED, OBSOLETE, TEMPORARY_DISABLED, DISABLED
supplementalFields array[Field]
transactional boolean Flag to indicate if the provider provides transactional data
type string The type of the provider. Values: BANK, CREDIT_CARD, BROKER, OTHER, TEST, FRAUD

Field

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

ImageUrls

Parameter Type Required Description
banner string
icon string

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 Type Required Description
accounts array[string] The list of account IDs to be used as a query filter
categories array[string] The list of category IDs to be used as a query filter. 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 array[string] The list of credentials IDs to be used as a query filter
endDate number The end date of the result.
externalIds array[string] A list of external IDs to filter for
includeUpcoming boolean Indicates if result should include upcoming transactions.
limit integer The limit for the result, used for paging.
offset integer The offset for the result, used for paging.
order string The order of the result.. Values: ASC, DESC
queryString string The string query.
sort string The sort order of the result.. Values: SCORE, DATE, ACCOUNT, DESCRIPTION, AMOUNT, CATEGORY
startDate number 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": "65bc7a41a66e4ad1aad199bbfb3c5098",
        "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": {},
        "payload": {},
        "pending": false,
        "timestamp": 1464543093494,
        "type": "CREDIT_CARD",
        "upcoming": false,
        "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
        "userModified": false
      },
      "type": "TRANSACTION"
    }
  ]
}

Response: SearchResponse

Parameter Type Required Description
count integer true Number of results returned.
net number true The transaction amount net of the result.
periodAmounts array[StringDoublePair] true Key value object holding periods and statistics values for result with the period specified in query.
query SearchQuery true The query executed.
results array[SearchResult] true The search result.

StringDoublePair

Parameter Type Required Description
key string
value number

SearchQuery

Parameter Type Required Description
accounts array[string] The list of account IDs to be used as a query filter
categories array[string] The list of category IDs to be used as a query filter. 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 array[string] The list of credentials IDs to be used as a query filter
endDate number The end date of the result.
externalIds array[string] A list of external IDs to filter for
includeUpcoming boolean Indicates if result should include upcoming transactions.
limit integer The limit for the result, used for paging.
offset integer The offset for the result, used for paging.
order string The order of the result.. Values: ASC, DESC
queryString string The string query.
sort string The sort order of the result.. Values: SCORE, DATE, ACCOUNT, DESCRIPTION, AMOUNT, CATEGORY
startDate number The start date of the result.

SearchResult

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

Budget

Parameter Type Required Description
budgetedAmount number
categoryId string
currentAmount number
historicalAmounts array[Statistic]
id string
suggestedAmount number
userId string

Statistic

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

Transaction

Parameter Type Required Description
accountId string true The internal identifier of the account that the transaction belongs to.
amount number true The amount of the transaction. This can be modified by the user.
categoryId string true The category of the transaction. This can be modified by the user.
categoryType string true The category type of the transaction.. Values: INCOME, EXPENSES, TRANSFERS
credentialsId string true The internal identifier of the credentials that the transaction belongs to.
date number true The date the transaction was executed. This can be modified by the user.
description string true The description of the transaction. This can be modified by the user.
dispensableAmount number The dispensable amount of the transaction.
id string true The internal identifier of the transaction.
lastModified number true The date the transaction was last modified by the user.
merchantId string The internal identifier of the merchant that the transaction belongs to. If available.
notes string 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 number true The original amount that was received from the provider, before the user changed it.
originalDate number true The original date that was received from the provider, before the user changed it.
originalDescription string true The original description that was received from the provider, before the user changed it.
partnerPayload object The payload that was previously ingested on the Connector API.
payload object Meta data about the transaction, in key value format with Strings.
pending boolean true Indicates if this transaction has been settled or is still pending.
timestamp integer true The timestamp of when the transaction was first saved to database.
type string true The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL
upcoming boolean Indicates if this is an upcoming transaction not booked yet.
userId string true The internal identifier of the user that the transaction belongs to.
userModified boolean

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 Type Required Description
description string Identifier of the data the statistic represents. This could for example be a category ID.
padResultUntilToday boolean Indicates if the result should be flat filled until the period of today.
periods array[string] Time periods for the statistics: year, month, week or day. Format: '2014’, '2014-02’, 2014:45 or '2014-02-12’
resolution string 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 array[string] 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 Type Required Description
description string true Identifier of the data the statistic represents.
payload string Secondary identifier of the data the statistic represent
period string true The statistic’s period, depends on it’s resolution. On of: year, month, week or day. Format: '2014’, '2014-02’, 2014:45 or '2014-02-12’
resolution string true Resolution for the statistics.. Values: DAILY, MONTHLY, MONTHLY_ADJUSTED, YEARLY, ALL, WEEKLY
type string true The statistic’s type.
userId string true The internal identifier of the user that the statistics belongs to.
value number true The value of the statistics for this type, period, and description.

Transaction Service

Update a list of transactions

Updates certain user modifiable properties of a list of transactions

PUT /api/v1/transactions

Request Example

{
  "accountId": "3fe2d96efacd4dc5994404a950f238a9",
  "amount": 34,
  "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
  "categoryType": "EXPENSES",
  "credentialsId": "65bc7a41a66e4ad1aad199bbfb3c5098",
  "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": {},
  "payload": {},
  "pending": false,
  "timestamp": 1464543093494,
  "type": "CREDIT_CARD",
  "upcoming": false,
  "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
  "userModified": false
}

Request Body: Transaction

The transactions to be updated

Parameter Type Required Description
accountId string true The internal identifier of the account that the transaction belongs to.
amount number true The amount of the transaction. This can be modified by the user.
categoryId string true The category of the transaction. This can be modified by the user.
categoryType string true The category type of the transaction.. Values: INCOME, EXPENSES, TRANSFERS
credentialsId string true The internal identifier of the credentials that the transaction belongs to.
date number true The date the transaction was executed. This can be modified by the user.
description string true The description of the transaction. This can be modified by the user.
dispensableAmount number The dispensable amount of the transaction.
id string true The internal identifier of the transaction.
lastModified number true The date the transaction was last modified by the user.
merchantId string The internal identifier of the merchant that the transaction belongs to. If available.
notes string 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 number true The original amount that was received from the provider, before the user changed it.
originalDate number true The original date that was received from the provider, before the user changed it.
originalDescription string true The original description that was received from the provider, before the user changed it.
partnerPayload object The payload that was previously ingested on the Connector API.
payload object Meta data about the transaction, in key value format with Strings.
pending boolean true Indicates if this transaction has been settled or is still pending.
timestamp integer true The timestamp of when the transaction was first saved to database.
type string true The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL
upcoming boolean Indicates if this is an upcoming transaction not booked yet.
userId string true The internal identifier of the user that the transaction belongs to.
userModified boolean

Change category of transactions

Changes category of the supplied list of transactions to the supplied category

PUT /api/v1/transactions/categorize-multiple

Request Example

{
  "categorizationList": [
    {
      "categoryId": "2d3bd65493b549e1927d97a2d0683ab9",
      "transactionIds": [
        "92e9e178cc22437281084c572ada8d7d",
        "a40db0b79bf94d2a9340cbc35d8b8020"
      ]
    }
  ]
}

Request Body: CategorizeTransactionsListRequest

Object holding a list of new categories and the transactions to be categorized

Parameter Type Required Description
categorizationList array[CategorizeTransactionsRequest] true A list of new categories and the transactions’ IDs

CategorizeTransactionsRequest

Parameter Type Required Description
categoryId string true The internal identifier of the category that the list of transactions is categorized to.
transactionIds array[string] true A list of internal identifiers of the transactions categorized.

Get categorization clusters

Returns an object holding clusters of transactions to be categorized and possible categorization level improvement

GET /api/v1/transactions/suggest

Query Parameters

Parameter Required Description
numberOfClusters Max number of clusters returned
evaluateEverything

Response Example

{
  "categorizationImprovement": 0,
  "categorizationLevel": 0,
  "clusters": [
    {
      "categorizationImprovement": 0,
      "description": "McDonalds Stock",
      "transactions": [
        {
          "accountId": "3fe2d96efacd4dc5994404a950f238a9",
          "amount": 34,
          "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
          "categoryType": "EXPENSES",
          "credentialsId": "65bc7a41a66e4ad1aad199bbfb3c5098",
          "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": {},
          "payload": {},
          "pending": false,
          "timestamp": 1464543093494,
          "type": "CREDIT_CARD",
          "upcoming": false,
          "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
          "userModified": false
        }
      ]
    }
  ]
}

Response: SuggestTransactionsResponse

Parameter Type Required Description
categorizationImprovement number true The categorization improvement achieve if all clusters are categorized.
categorizationLevel number true The current categorization level before categorization.
clusters array[TransactionCluster] true Clusters to categorize.

TransactionCluster

Parameter Type Required Description
categorizationImprovement number The categorization improvement achived if cluster is categorized.
description string A description of the cluster to categorized.
transactions array[Transaction] List of transactions belonging to this cluster.

Transaction

Parameter Type Required Description
accountId string true The internal identifier of the account that the transaction belongs to.
amount number true The amount of the transaction. This can be modified by the user.
categoryId string true The category of the transaction. This can be modified by the user.
categoryType string true The category type of the transaction.. Values: INCOME, EXPENSES, TRANSFERS
credentialsId string true The internal identifier of the credentials that the transaction belongs to.
date number true The date the transaction was executed. This can be modified by the user.
description string true The description of the transaction. This can be modified by the user.
dispensableAmount number The dispensable amount of the transaction.
id string true The internal identifier of the transaction.
lastModified number true The date the transaction was last modified by the user.
merchantId string The internal identifier of the merchant that the transaction belongs to. If available.
notes string 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 number true The original amount that was received from the provider, before the user changed it.
originalDate number true The original date that was received from the provider, before the user changed it.
originalDescription string true The original description that was received from the provider, before the user changed it.
partnerPayload object The payload that was previously ingested on the Connector API.
payload object Meta data about the transaction, in key value format with Strings.
pending boolean true Indicates if this transaction has been settled or is still pending.
timestamp integer true The timestamp of when the transaction was first saved to database.
type string true The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL
upcoming boolean Indicates if this is an upcoming transaction not booked yet.
userId string true The internal identifier of the user that the transaction belongs to.
userModified boolean

Get one transaction

Returns a transaction matching the requested id

GET /api/v1/transactions/{id}

Parameters

Parameter Required Description
id true The id of the transaction

Response Example

{
  "accountId": "3fe2d96efacd4dc5994404a950f238a9",
  "amount": 34,
  "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
  "categoryType": "EXPENSES",
  "credentialsId": "65bc7a41a66e4ad1aad199bbfb3c5098",
  "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": {},
  "payload": {},
  "pending": false,
  "timestamp": 1464543093494,
  "type": "CREDIT_CARD",
  "upcoming": false,
  "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
  "userModified": false
}

Response: Transaction

Parameter Type Required Description
accountId string true The internal identifier of the account that the transaction belongs to.
amount number true The amount of the transaction. This can be modified by the user.
categoryId string true The category of the transaction. This can be modified by the user.
categoryType string true The category type of the transaction.. Values: INCOME, EXPENSES, TRANSFERS
credentialsId string true The internal identifier of the credentials that the transaction belongs to.
date number true The date the transaction was executed. This can be modified by the user.
description string true The description of the transaction. This can be modified by the user.
dispensableAmount number The dispensable amount of the transaction.
id string true The internal identifier of the transaction.
lastModified number true The date the transaction was last modified by the user.
merchantId string The internal identifier of the merchant that the transaction belongs to. If available.
notes string 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 number true The original amount that was received from the provider, before the user changed it.
originalDate number true The original date that was received from the provider, before the user changed it.
originalDescription string true The original description that was received from the provider, before the user changed it.
partnerPayload object The payload that was previously ingested on the Connector API.
payload object Meta data about the transaction, in key value format with Strings.
pending boolean true Indicates if this transaction has been settled or is still pending.
timestamp integer true The timestamp of when the transaction was first saved to database.
type string true The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL
upcoming boolean Indicates if this is an upcoming transaction not booked yet.
userId string true The internal identifier of the user that the transaction belongs to.
userModified boolean

Update a transaction

Updates certain user modifiable properties of a transaction

PUT /api/v1/transactions/{id}

Request Example

{
  "accountId": "3fe2d96efacd4dc5994404a950f238a9",
  "amount": 34,
  "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
  "categoryType": "EXPENSES",
  "credentialsId": "65bc7a41a66e4ad1aad199bbfb3c5098",
  "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": {},
  "payload": {},
  "pending": false,
  "timestamp": 1464543093494,
  "type": "CREDIT_CARD",
  "upcoming": false,
  "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
  "userModified": false
}

Parameters

Parameter Required Description
id true The id of the transaction

Request Body: Transaction

The transaction to be updated

Parameter Type Required Description
accountId string true The internal identifier of the account that the transaction belongs to.
amount number true The amount of the transaction. This can be modified by the user.
categoryId string true The category of the transaction. This can be modified by the user.
categoryType string true The category type of the transaction.. Values: INCOME, EXPENSES, TRANSFERS
credentialsId string true The internal identifier of the credentials that the transaction belongs to.
date number true The date the transaction was executed. This can be modified by the user.
description string true The description of the transaction. This can be modified by the user.
dispensableAmount number The dispensable amount of the transaction.
id string true The internal identifier of the transaction.
lastModified number true The date the transaction was last modified by the user.
merchantId string The internal identifier of the merchant that the transaction belongs to. If available.
notes string 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 number true The original amount that was received from the provider, before the user changed it.
originalDate number true The original date that was received from the provider, before the user changed it.
originalDescription string true The original description that was received from the provider, before the user changed it.
partnerPayload object The payload that was previously ingested on the Connector API.
payload object Meta data about the transaction, in key value format with Strings.
pending boolean true Indicates if this transaction has been settled or is still pending.
timestamp integer true The timestamp of when the transaction was first saved to database.
type string true The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL
upcoming boolean Indicates if this is an upcoming transaction not booked yet.
userId string true The internal identifier of the user that the transaction belongs to.
userModified boolean

Response Example

{
  "accountId": "3fe2d96efacd4dc5994404a950f238a9",
  "amount": 34,
  "categoryId": "0e1bade6a7e3459eb794f27b7ba4cea0",
  "categoryType": "EXPENSES",
  "credentialsId": "65bc7a41a66e4ad1aad199bbfb3c5098",
  "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": {},
  "payload": {},
  "pending": false,
  "timestamp": 1464543093494,
  "type": "CREDIT_CARD",
  "upcoming": false,
  "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
  "userModified": false
}

Response: Transaction

Parameter Type Required Description
accountId string true The internal identifier of the account that the transaction belongs to.
amount number true The amount of the transaction. This can be modified by the user.
categoryId string true The category of the transaction. This can be modified by the user.
categoryType string true The category type of the transaction.. Values: INCOME, EXPENSES, TRANSFERS
credentialsId string true The internal identifier of the credentials that the transaction belongs to.
date number true The date the transaction was executed. This can be modified by the user.
description string true The description of the transaction. This can be modified by the user.
dispensableAmount number The dispensable amount of the transaction.
id string true The internal identifier of the transaction.
lastModified number true The date the transaction was last modified by the user.
merchantId string The internal identifier of the merchant that the transaction belongs to. If available.
notes string 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 number true The original amount that was received from the provider, before the user changed it.
originalDate number true The original date that was received from the provider, before the user changed it.
originalDescription string true The original description that was received from the provider, before the user changed it.
partnerPayload object The payload that was previously ingested on the Connector API.
payload object Meta data about the transaction, in key value format with Strings.
pending boolean true Indicates if this transaction has been settled or is still pending.
timestamp integer true The timestamp of when the transaction was first saved to database.
type string true The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL
upcoming boolean Indicates if this is an upcoming transaction not booked yet.
userId string true The internal identifier of the user that the transaction belongs to.
userModified boolean

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 Required Description
id true The id of the transaction

Query Parameters

Parameter Required Description
categoryId Returns similar of the this cateogry
includeSelf 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": "65bc7a41a66e4ad1aad199bbfb3c5098",
      "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": {},
      "payload": {},
      "pending": false,
      "timestamp": 1464543093494,
      "type": "CREDIT_CARD",
      "upcoming": false,
      "userId": "d9f134ee2eb44846a4e02990ecc8d32e",
      "userModified": false
    }
  ]
}

Response: SimilarTransactionsResponse

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

Statistic

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

Transaction

Parameter Type Required Description
accountId string true The internal identifier of the account that the transaction belongs to.
amount number true The amount of the transaction. This can be modified by the user.
categoryId string true The category of the transaction. This can be modified by the user.
categoryType string true The category type of the transaction.. Values: INCOME, EXPENSES, TRANSFERS
credentialsId string true The internal identifier of the credentials that the transaction belongs to.
date number true The date the transaction was executed. This can be modified by the user.
description string true The description of the transaction. This can be modified by the user.
dispensableAmount number The dispensable amount of the transaction.
id string true The internal identifier of the transaction.
lastModified number true The date the transaction was last modified by the user.
merchantId string The internal identifier of the merchant that the transaction belongs to. If available.
notes string 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 number true The original amount that was received from the provider, before the user changed it.
originalDate number true The original date that was received from the provider, before the user changed it.
originalDescription string true The original description that was received from the provider, before the user changed it.
partnerPayload object The payload that was previously ingested on the Connector API.
payload object Meta data about the transaction, in key value format with Strings.
pending boolean true Indicates if this transaction has been settled or is still pending.
timestamp integer true The timestamp of when the transaction was first saved to database.
type string true The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL
upcoming boolean Indicates if this is an upcoming transaction not booked yet.
userId string true The internal identifier of the user that the transaction belongs to.
userModified boolean

Transfer Service

Create new Transfer

Creates a new Transfer. The type of the transfer (BANK_TRANSFER or PAYMENT) will be based on the given destinationUri.

POST /api/v1/transfer

Request Example

{
  "amount": 10,
  "credentialsId": "342220f1e0484c0481b2b468d7fbcfc4",
  "currency": "SEK",
  "destinationMessage": "Happy birthday!",
  "destinationUri": "se://6000123456789?name=myDestination",
  "dueDate": 1471349422000,
  "id": "a4516bda6ff545e0aa24e54b859579e0",
  "messageType": "STRUCTURED",
  "sourceMessage": "Gift to Sophie",
  "sourceUri": "tink://1e09bab571d84b1cbe8d49c0be9c030f",
  "type": "BANK_TRANSFER",
  "userId": "2f37e3ff1e5342b39c41bee3ee73cf8e"
}

Request Body: Transfer

The Transfer object

Parameter Type Required Description
amount number true The amount that will be transferred
credentialsId string The id of the Credentials used to make the transfer. Will be the credentials of which the source account belongs to.
currency string true The currency of the amount
destinationMessage string true The message to the recipient. Optional for bank transfers but required for payments. If the payment recipient requires an OCR, it should be set as destinationMessage.
destinationUri string true The destination account or recipient of the transfer, on the form of a uri.
dueDate number true The date the payment or bank transfer should be executed. If bank transfer, and no dueDate is given, it will be executed immediately
id string The id of this transfer.
messageType string Transfer’s message type, required in Belgium.. Values: STRUCTURED, FREE_TEXT
sourceMessage string A note to show to the source account.
sourceUri string true The source account of the transfer, on the form of a uri.
type string The type of the transfer.. Values: BANK_TRANSFER, PAYMENT
userId string The id of the user making the transfer.

Response Example

{
  "created": 1471349422000,
  "credentialsId": "342220f1e0484c0481b2b468d7fbcfc4",
  "id": "a4516bda6ff545e0aa24e54b859579e0",
  "status": "EXECUTED",
  "statusMessage": "The transfer has been sent to your bank.",
  "type": "TRANSFER",
  "underlyingId": "1e09bab571d84b1cbe8d49c0be9c030f",
  "updated": 1471349422000,
  "userId": "2f37e3ff1e5342b39c41bee3ee73cf8e"
}

Response: SignableOperation

Parameter Type Required Description
created number The timestamp of the creation of the operation.
credentialsId string The id of the Credentials used to make the operation.
id string The id of this operation.
status string The status of the operation. CANCELLED, FAILED and EXECUTED are all endstates.. Values: CREATED, EXECUTING, AWAITING_CREDENTIALS, CANCELLED, FAILED, EXECUTED, AWAITING_THIRD_PARTY_APP_AUTHENTICATION
statusMessage string The status message of the operation
type string The type of operation. Values: TRANSFER
underlyingId string The id of the actual underlying operation (e.g. the id of a Transfer operation).
updated number The timestamp of the last update of the operation.
userId string The id of the user making the operation.

Get accounts and destinations

GET /api/v1/transfer/accounts

Query Parameters

Parameter Required Description
type The type of transfers the account is capable of. Values: BE, SE, SE_SHB_INTERNAL, FI, IBAN, TINK, SE_BG, SE_PG, SEPA_EUR, SORT_CODE
destination Filter only accounts which can do transfers to the specified destination

Response Example

{
  "accounts": [
    {
      "accountExclusion": "string",
      "accountNumber": "1234-123456789",
      "balance": 34567,
      "closed": false,
      "credentialsId": "6e68cc6287704273984567b3300c5822",
      "details": {
        "interest": 0,
        "nextDayOfTermsChange": "string",
        "numMonthsBound": 0,
        "type": "string"
      },
      "excluded": null,
      "favored": null,
      "flags": "[\"MANDATE\"]",
      "holderName": "Thomas Alan Waits",
      "id": "a6bb87e57a8c4dd4874b241471a2b9e8",
      "identifiers": "[\"se://9999111111111111\"]",
      "name": "Privatkonto",
      "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 Type Required Description
accounts array[Account] A list of accounts

Account

Parameter Type Required Description
accountExclusion string true The type of features to exclude for this account. This can be modified by the user.. Values: AGGREGATION, PFM_AND_SEARCH, PFM_DATA, NONE
accountNumber string true The account number of the account. Not necessarily always a full clearingnumber-accountnumber. It can be formatted differently for different accounts and banks.
balance number true The current balance of the account.
closed boolean
credentialsId string true The internal identifier of the credentials that the account belongs to.
details AccountDetails If available, details are populated.
excluded boolean true Indicates if the user has excluded the account. This can be modified by the user.
favored boolean true Indicates if the user has favored the account. This can be modified by the user.
flags string A list of flags specifying attributes on an account. Values: BUSINESS, MANDATE
holderName string The name of the account holder
id string true The internal identifier of account.
identifiers string All possible ways to uniquely identify this Account. An se-identifier is built up like: se://{clearingnumber}{accountnumber}
name string true The display name of the account. This can be modified by the user.
ownership number true The ownership ratio indicating how much of the account is owned by the user. This is used to determine how much of transactions belonging to this account should be attributed to the user when statistics are calculated. This can be modified by the user.
transferDestinations array[TransferDestination] This field contains all the destinations this Account can transfer money to, be that payment or bank transfer recipients. It will only be populated if getting accounts via GET /transfer/accounts (i.e. not through GET /accounts).
type string true The type of the account. This can be modified by the user.. Values: CHECKING, SAVINGS, INVESTMENT, MORTGAGE, CREDIT_CARD, LOAN, PENSION, OTHER, EXTERNAL

AccountDetails

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

TransferDestination

Parameter Type Required Description
balance number The balance of the account. Will only be populated for accounts that is owned by the user.
displayAccountNumber string A display formatted alpha-numeric string of the destination account/payment recipient number.
displayBankName string The name of the bank where this destination recides. Will not be populated for payment destinations.
matchesMultiple boolean 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 string The name of the destination if one exists.
type string 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 string The uri used to describe this destination.

Signing status of Transfer

Get the SignableOperation of the underlying transfer.

GET /api/v1/transfer/{id}/status

Parameters

Parameter Required Description
id true The id of the Transfer

Response Example

{
  "created": 1471349422000,
  "credentialsId": "342220f1e0484c0481b2b468d7fbcfc4",
  "id": "a4516bda6ff545e0aa24e54b859579e0",
  "status": "EXECUTED",
  "statusMessage": "The transfer has been sent to your bank.",
  "type": "TRANSFER",
  "underlyingId": "1e09bab571d84b1cbe8d49c0be9c030f",
  "updated": 1471349422000,
  "userId": "2f37e3ff1e5342b39c41bee3ee73cf8e"
}

Response: SignableOperation

Parameter Type Required Description
created number The timestamp of the creation of the operation.
credentialsId string The id of the Credentials used to make the operation.
id string The id of this operation.
status string The status of the operation. CANCELLED, FAILED and EXECUTED are all endstates.. Values: CREATED, EXECUTING, AWAITING_CREDENTIALS, CANCELLED, FAILED, EXECUTED, AWAITING_THIRD_PARTY_APP_AUTHENTICATION
statusMessage string The status message of the operation
type string The type of operation. Values: TRANSFER
underlyingId string The id of the actual underlying operation (e.g. the id of a Transfer operation).
updated number The timestamp of the last update of the operation.
userId string The id of the user making the operation.

User Data Control Service

List data export requests

Returns a list with all data export requests for a given user.

GET /api/v1/user-data-control/data-exports

Response Example

{
  "dataExportRequests": [
    {
      "created": 1527163200,
      "id": "051837be5fa3410ea676affcc0a35a09",
      "status": "COMPLETED"
    }
  ]
}

Response: DataExportRequestListResponse

Parameter Type Required Description
dataExportRequests array[DataExportRequest]

DataExportRequest

Parameter Type Required Description
created number Data export request creation date
id string The id of the data export request.
status string The status of the data export request. Values: CREATED, IN_PROGRESS, FAILED, COMPLETED

Create data export request

Creates a data export request for a given user.

POST /api/v1/user-data-control/data-exports

Response Example

{
  "created": 1527163200,
  "id": "051837be5fa3410ea676affcc0a35a09",
  "status": "COMPLETED"
}

Response: DataExportRequest

Parameter Type Required Description
created number Data export request creation date
id string The id of the data export request.
status string The status of the data export request. Values: CREATED, IN_PROGRESS, FAILED, COMPLETED

Get data export request

Returns a data export request for a given user and request id.

GET /api/v1/user-data-control/data-exports/{id}

Parameters

Parameter Required Description
id true Data export request id

Download data export

Returns a file to download for a user. Provide a data export request id in the path, and specify the accept type to Accept: text/plain in the header.

GET /api/v1/user-data-control/data-exports/{id}/download

Parameters

Parameter Required Description
id true Corresponding data export request id

List market login methods

Returns a list of markets along with their authentication methods.

GET /api/v1/user-data-control/login-methods

Response Example

{
  "gdprLoginMethods": [
    {
      "auhtenticationMethod": [
        "string",
        "string"
      ],
      "code": "SE",
      "description": "Sweden"
    }
  ]
}

Response: GdprLoginMethodListResponse

Parameter Type Required Description
gdprLoginMethods array[GdprLoginMethod]

GdprLoginMethod

Parameter Type Required Description
auhtenticationMethod array[string] The authentication methods valid for a specific market
code string The ISO 3166-1 alpha-2 country code of the market.. Values: AT, AU, BE, BG, BR, CA, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IN, IT, LU, LV, MT, NL, NO, NZ, PL, PT, RO, SE, SG, SI, SK, UK, US
description string The display name of the market

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 Type Required Description
created number true The date when the user was created.
flags array[string] The user-specific feature flags assigned to the user.
id string true The internal identifier of the user.
nationalId string
password string The password of the user (only included at registration).
profile UserProfile true The configurable profile of the user
username string The username (usually email) of the user.

UserProfile

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

NotificationSettings

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

Update the user

Updates certain user modifiable properties of a user. Please refer to the body schema to see which properties are modifiable by the user.

PUT /api/v1/user

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

Request Body: User

The updated user object

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

UserProfile

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

NotificationSettings

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

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 Type Required Description
created number true The date when the user was created.
flags array[string] The user-specific feature flags assigned to the user.
id string true The internal identifier of the user.
nationalId string
password string The password of the user (only included at registration).
profile UserProfile true The configurable profile of the user
username string The username (usually email) of the user.

UserProfile

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

NotificationSettings

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

Logout a user

POST /api/v1/user/logout

Query Parameters

Parameter Required Description
autologout boolean

List markets

Returns an object with a list of all available markets in which a user could register with.

GET /api/v1/user/markets/list

Query Parameters

Parameter Required Description
desired The ISO 3166-1 alpha-2 country code of the desired market

Response Example

{
  "markets": [
    {
      "code": "SE",
      "currencies": [
        {
          "code": "SEK",
          "factor": 10,
          "prefixed": false,
          "symbol": "kr"
        }
      ],
      "defaultCurrency": "SEK",
      "defaultLocale": "sv_SE",
      "defaultTimeZone": "Europe/Stockholm",
      "description": "Sweden",
      "gdprLoginMethods": [
        "string",
        "string"
      ],
      "loginMethods": [
        "string",
        "string"
      ],
      "registerMethods": [
        "string",
        "string"
      ],
      "suggested": false
    }
  ]
}

Response: MarketListResponse

Parameter Type Required Description
markets array[Market]

Market

Parameter Type Required Description
code string true The ISO 3166-1 alpha-2 country code of the market.. Values: AT, AU, BE, BG, BR, CA, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IN, IT, LU, LV, MT, NL, NO, NZ, PL, PT, RO, SE, SG, SI, SK, UK, US
currencies array[Currency] true The applicable currencies available in the market.
defaultCurrency string true The ISO 4217 code of the default currency.
defaultLocale string true The default locale in the market.
defaultTimeZone string true The default time zone in the market.
description string true The display name of the market
gdprLoginMethods array[string]
loginMethods array[string]
registerMethods array[string]
suggested boolean true Flag to indicate if this is the suggested market for the user.

Currency

Parameter Type Required Description
code string true The ISO 4217 code of the currency.
factor number true An approximate currency conversion factor to inversely scale triggers to the EUR currency.
prefixed boolean true Indicates that the currency symbol should prefix the amount.
symbol string true The symbol of the currency.

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 Type Required Description
currency string true The configured ISO 4217 currency code of the user. This can be modified by the user.
locale string true The configured locale of the user. This can be modified by the user.
market string true The primary market/country of the user.
notificationSettings NotificationSettings true The configured notification settings of the user. This can be modified by the user.
periodAdjustedDay integer true The configured day of the month to break the adjusted period on. This can be modified by the user.
periodMode string true The configured monthly period mode of the user. This can be modified by the user.. Values: MONTHLY, MONTHLY_ADJUSTED
timeZone string true The configured time zone of the user. This can be modified by the user.

NotificationSettings

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

Update the user profile

Updates certain user modifiable properties of a user’s profile. Please refer to the body schema to see which properties are modifiable by the user.

PUT /api/v1/user/profile

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

Request Body: UserProfile

The updated user profile object

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

NotificationSettings

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

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 Type Required Description
currency string true The configured ISO 4217 currency code of the user. This can be modified by the user.
locale string true The configured locale of the user. This can be modified by the user.
market string true The primary market/country of the user.
notificationSettings NotificationSettings true The configured notification settings of the user. This can be modified by the user.
periodAdjustedDay integer true The configured day of the month to break the adjusted period on. This can be modified by the user.
periodMode string true The configured monthly period mode of the user. This can be modified by the user.. Values: MONTHLY, MONTHLY_ADJUSTED
timeZone string true The configured time zone of the user. This can be modified by the user.

NotificationSettings

Parameter Type Required Description
balance boolean true Indicates if the user wants to receive notifications with low or high balances alerts.
budget boolean true Indicates if the user wants to receive notifications regarding her budgets.
doubleCharge boolean true Indicates if the user wants to receive notifications with double-charge alerts.
einvoices boolean true Indicates if the user wants to receive notifications for e-invoices.
fraud boolean true Indicates if the user wants to receive notifications for ID Control warnings.
income boolean true Indicates if the user wants to receive notifications when an income is received.
largeExpense boolean true Indicates if the user wants to receive notifications when a large expense is detected.
leftToSpend boolean true Indicates if the user wants to receive left to spend notifications.
loanUpdate boolean true Indicates if the user wants to receive notifications for loan updates.
summaryMonthly boolean true Indicates if the user wants to receive notifications with monthly summaries.
summaryWeekly boolean true Indicates if the user wants to receive notifications with weekly summaries.
transaction boolean true Indicates if the user wants to receive notifications for every transaction.
unusualAccount boolean true Indicates if the user wants to receive notifications when there is unusual activity on any of her accounts.
unusualCategory boolean 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 Type Required Description
commit string true The last commit of the build
date number true The date of the build
version string true The version of the build

Webhook Service

List Webhooks

List the registered webhooks for the given client.

GET /api/v1/authorization/hooks

Response Example

{
  "webHooks": [
    {
      "events": [
        "signable-operation:update"
      ],
      "secret": "67abc1e08fb64c92b450a13e0876330b",
      "url": "https://www.clienturl.com/webhook/{userid}"
    }
  ]
}

Response: OAuth2WebHookResponse

Parameter Type Required Description
webHooks array[OAuth2WebHook]

OAuth2WebHook

Parameter Type Required Description
events array[string] true A list of events to register web hooks for.
secret string true A secret chosen by the consumer. This secret can be used when getting the actual web hook executed back to verify it is a valid one.
url string true The URL that will receive the web hook. Need to be over https, and Tink needs to have the domain registered in the database.

Create Webhook

Create a new webhook for the authenticated user, giving the possibility to get pushed updates for certain events.

POST /api/v1/authorization/hooks

Request Example

{
  "events": [
    "signable-operation:update"
  ],
  "secret": "67abc1e08fb64c92b450a13e0876330b",
  "url": "https://www.clienturl.com/webhook/{userid}"
}

Request Body: OAuth2WebHook

The specifics of the webhook to create

Parameter Type Required Description
events array[string] true A list of events to register web hooks for.
secret string true A secret chosen by the consumer. This secret can be used when getting the actual web hook executed back to verify it is a valid one.
url string true The URL that will receive the web hook. Need to be over https, and Tink needs to have the domain registered in the database.

Response Example

{
  "events": [
    "signable-operation:update"
  ],
  "secret": "67abc1e08fb64c92b450a13e0876330b",
  "url": "https://www.clienturl.com/webhook/{userid}"
}

Response: OAuth2WebHook

Parameter Type Required Description
events array[string] true A list of events to register web hooks for.
secret string true A secret chosen by the consumer. This secret can be used when getting the actual web hook executed back to verify it is a valid one.
url string true The URL that will receive the web hook. Need to be over https, and Tink needs to have the domain registered in the database.

Delete Webhook

Delete the webhook of the given id.

DELETE /api/v1/authorization/hooks/{id}

Parameters

Parameter Required Description
id true The id of the webhook