NAV Navbar
Examples

General

Introduction

Welcome to the Tink API reference! The Connector API can be used to feed transactions and accounts directly into Tink.

The API is accessible at https://api.tink.com

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

Status codes

When doing an HTTP request to the Tink API you will receive an HTTP status code in the server response. The codes are documented per endpoint.

All endpoints can respond with the following HTTP error status codes:

Status code Description
429 Indicates that the user has sent too many requests in a given amount of time ("rate limiting"). A rejected request should be retried.
500 An error happened in one of Tink's servers.

Accounts

The accounts endpoint enables the customer to create, update and delete accounts.

By sending a user token for an activated user, together with a list of account entries, these will be created accordingly (depending on whether they already exist or not).

Before sending transactions to Tink, the customer’s account needs to be created. When enrolling a new customer, all accounts for the customer should be sent in one batch. A successful call to create accounts means that Tink is ready to receive transactions.

Please note: The customer’s accounts must not be subscribed for real-time transactions on the customer side before a successful response has been received from a call to this endpoint with the corresponding account.

Transactions

The customer's backend pushes all transactions (and transaction updates/deletes) to the Transaction Service.

Transactions are sent by account in a list and one request can contain transactions for multiple accounts. The request has a status that indicates if this is historical, batch or real time transactions. This is used by the Tink Platform to prioritize incoming transactions.

Pending transactions

There are two ways to handle the pending to non-pending state of a transaction. The chosen way depends on the partner and whether the persistent id of the transaction (externalId), is the same for the pending transaction and the non-pending one. If the partner has different ids for the pending and non-pending transactions, the easiest way is to ingest the pending transaction normally to the Transaction Service ingest endpoint with flag pending:true. When then ingesting the non-pending transaction with a new externalId, utilize the payload PENDING_IDS: ["pendingTransactionExternalId"] to refer back to the pending transaction (or multiple if that is the case). The Tink Platform will remove all referred pending transactions automatically in favor for the newly ingested non-pending. Categorization is transferred from the pending to the non-pending.

If the partner has the same externalId for both pending and non-pending transactions, one can utilize the Update Transaction endpoint to update the pending transaction to pending:false.

Transaction payload

The transaction payload is a key-value store, which can be utilized by the partner to send in custom data which will be stored together with the transaction in the database. This means that the payload will follow the transaction when being querying on the Main API. The Main API transaction has a field partnerPayload where it will show up.

There are some payload keys that are reserved and used by the platform:

Payload key name type description
PENDING_IDS Array of Strings The array of ids on a non-pending transaction that refers to the pending transactions it replaces.
TAGS Array of Strings The array of strings will be set as tags to the notes field of the transaction.

Authentication

Tink uses Bearer tokens to authenticate requests per client. The token is provided through the HTTP Authorization header, such as Authorization: Bearer <token>. Client tokens are acquired through the OAuth service on the API and are valid for one client for a limited time. When a token has expired, the API call will return the HTTP status code 401 Unauthorized and a new token has to be acquired.

Although it is possible to parse the tokens on the client side, it is not a supported operation and the tokens are to be considered a binary for the purposes of the client.

Available Scopes

Access to Tink is divided into scopes. The currently available scopes for Tink's APIs are:

accounts:read, accounts:write, authorization:grant, budgets:read, budgets:write, categories:read, contacts:read, credentials:read, credentials:refresh, credentials:write, data-exports:read, data-exports:write, documents:read, documents:write, follow:read, follow:write, investments:read, properties:read, properties:write, providers:read, statistics:read, suggestions:read, transactions:categorize, transactions:read, transactions:write, transfer:execute, transfer:read, user:create, user:delete, user:read, user:web_hooks, user:write, identity:read, and identity:write.

Error status codes

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

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

API Reference

Account Service

Ingest accounts

POST /connector/users/{externalUserId}/accounts

Takes a list of accounts and the corresponding user ID.

Request Example

{
  "accounts": [
    {
      "availableCredit": 20000,
      "balance": 7000,
      "closed": null,
      "exclusion": "PFM_AND_SEARCH",
      "externalId": "2d3bd65493b549e1927d97a2d0683ab9",
      "flags": [
        "MANDATE"
      ],
      "name": "Enkla sparkontot",
      "number": "52670208126",
      "payload": {},
      "reservedAmount": 2000,
      "type": "CREDIT_CARD"
    }
  ]
}

Parameters

Parameter Description
externalUserId
required: true
Persistent identifier for the user.

Request Body: AccountListEntity

The accounts.

Parameter Description
accounts
type: array[AccountEntity]
required: true
The accounts.

AccountEntity

Parameter Description
availableCredit
type: number
required: false
The available credit of the account.
balance
type: number
required: true
The balance of the account.
closed
type: boolean
required: false
The closed state of the account.
exclusion
type: string
required: false
The type of features to exclude. PFM_AND_SEARCH will exclude the accounts transactions from categorization, PFM features, and search result. PFM_DATA will exclude the accounts transactions from categorization and PFM features.. Values: PFM_AND_SEARCH, PFM_DATA, NONE
externalId
type: string
required: true
Persistent identifier for the account.
flags
type: array[string]
required: false
A list of flags specifying attributes on an account
name
type: string
required: true
The account name.
number
type: string
required: true
The account number.
payload
type: object
required: false
The payload property can include arbitrary metadata provided by the financial institution in question that can be used either for deep-linking back to the app by the financial institution, for displaying additional information about the account, etc. The format is key-value, where key is a String and value any object.
reservedAmount
type: number
required: false
The currently reserved amount of the account.
type
type: string
required: true
The account type.. Values: CHECKING, SAVINGS, INVESTMENT, MORTGAGE, CREDIT_CARD, LOAN, PENSION, OTHER, EXTERNAL
Status Code Description
204 Accounts created.
400 The payload does not pass validation.
401 User not found, has no credentials, or has more than one set of credentials.
409 Account already exists.

Delete account

DELETE /connector/users/{externalUserId}/accounts/{externalAccountId}

Deletes the account with the given account ID.

Parameters

Parameter Description
externalUserId
required: true
Persistent identifier for the user.
externalAccountId
required: true
Persistent identifier for the account.
Status Code Description
204 Account deleted.
401 User not found, has no credentials, or has more than one set of credentials.
404 Account not found.

Update account

PUT /connector/users/{externalUserId}/accounts/{externalAccountId}

Accepts an object of properties to be updated.

Request Example

{
  "closed": null,
  "exclusion": "PFM_AND_SEARCH",
  "name": "My savings account"
}

Parameters

Parameter Description
externalUserId
required: true
Persistent identifier for the user.
externalAccountId
required: true
Persistent identifier for the account.

Request Body: UpdateAccountEntity

Account update request

Parameter Description
closed
type: boolean
required: false
The closed state of the account.
exclusion
type: string
required: false
The type of features to exclude. PFM_AND_SEARCH will exclude the accounts transactions from categorization, PFM features, and search result. PFM_DATA will exclude the accounts transactions from categorization and PFM features.. Values: PFM_AND_SEARCH, PFM_DATA, NONE
name
type: string
required: false
The account name.
Status Code Description
204 Account updated.
400 The request does not pass validation.
401 User not found, has no credentials, or has more than one set of credentials.
404 Account not found.

Transaction Service

Ingest transactions

POST /connector/users/{externalUserId}/transactions

Takes historical or real time transactions together with an account.

Request Example

{
  "transactionAccounts": [
    {
      "balance": 7000,
      "externalId": "2d3bd65493b549e1927d97a2d0683ab9",
      "payload": {},
      "reservedAmount": 2000,
      "transactions": [
        {
          "amount": -98,
          "date": 1455740874875,
          "description": "Riche Teatergrillen",
          "externalId": "40dc04e5353547378c84f34ffc88f853",
          "payload": {},
          "pending": false,
          "tinkId": "string",
          "type": "CREDIT_CARD"
        }
      ]
    }
  ],
  "type": "REAL_TIME"
}

Parameters

Parameter Description
externalUserId
required: true
Persistent identifier for the user.

Request Body: CreateTransactionAccountContainer

Container of account and transactions.

Parameter Description
transactionAccounts
type: array[CreateTransactionAccountEntity]
required: true
The transaction accounts. All accounts accumulated may contain a maximum of 2500 transactions per request.
type
type: string
required: true
Indicating if this a historical batch of transactions or a real time transaction.. Values: REAL_TIME, HISTORICAL, BATCH

CreateTransactionAccountEntity

Parameter Description
balance
type: number
required: true
The balance of the account for the time of the last transaction in the list.
externalId
type: string
required: true
Persistent identifier for the account the transaction belongs to.
payload
type: object
required: false
The payload property can include arbitrary metadata provided by the financial institution in question that can be used either for deep-linking back to the app of the financial institution, for displaying additional information about the account, or for backend purposes such as automatic categorization improvement, etc. The format is key-value, where key is a String and value any object.
reservedAmount
type: number
required: false
The reserved amount of the account for the time of the last transaction in the list.
transactions
type: array[CreateTransactionEntity]
required: true
The transaction list.

CreateTransactionEntity

Parameter Description
amount
type: number
required: true
The debited/credited amount in the currency of the account.
date
type: number
required: true
Date is when the transaction was executed, not when it was settled (except for scheduled transfers/payments, where the settling date is to be interpreted as the execution date).
description
type: string
required: true
A merchant name if possible. If such value is not available, the description that is shown in the transaction list.
externalId
type: string
required: true
Persistent identifier for the transaction.
payload
type: object
required: false
The payload property can include arbitrary metadata provided by the financial institution in question that can be used either for deep-linking back to the app of the financial institution, for displaying additional information about the transaction, or for backend purposes such as automatic categorization improvement, etc. The format is key-value, where key is a String and value any object.
pending
type: boolean
required: false
If the transaction is pending (reserved) or not (booked).
tinkId
type: string
required: false
Ignored for new objects. Used to specify the id as given by Tink on when updating objects without an existing external ID.
type
type: string
required: true
The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL
Status Code Description
204 Transactions ingested.
400 The payload does not pass validation, or the specified account does not exist.
401 User not found.
409 Transaction already exists.
410 Transaction has already been deleted.
412 Could not find any accounts for the user.

Delete transactions

POST /connector/users/{externalUserId}/transactions/delete

Removes transactions. When deleting transactions, it's only the externalId of each transaction that is necessary.

Request Example

{
  "transactionAccounts": [
    {
      "balance": 7000,
      "externalId": "2d3bd65493b549e1927d97a2d0683ab9",
      "payload": {},
      "reservedAmount": 2000,
      "transactions": [
        {
          "externalId": "40dc04e5353547378c84f34ffc88f853"
        }
      ]
    }
  ],
  "type": "REAL_TIME"
}

Parameters

Parameter Description
externalUserId
required: true
Persistent identifier for the user.

Request Body: DeleteTransactionAccountsContainer

Container of account and transactions.

Parameter Description
transactionAccounts
type: array[DeleteTransactionAccountEntity]
required: true
The transaction accounts.
type
type: string
required: true
Indicating if this a historical batch of transactions or a real time transaction.. Values: REAL_TIME, HISTORICAL, BATCH

DeleteTransactionAccountEntity

Parameter Description
balance
type: number
required: true
The balance of the account for the time of the last transaction in the list.
externalId
type: string
required: true
Persistent identifier for the account the transaction belong to.
payload
type: object
required: false
The payload property can include arbitrary metadata provided by the financial institution in question that can be used either for deep-linking back to the app of the financial institution, for displaying additional information about the account, or for backend purposes such as automatic categorization improvement, etc. The format is key-value, where key is a String and value any object.
reservedAmount
type: number
required: false
The reserved amount of the account for the time of the last transaction in the list.
transactions
type: array[DeleteTransactionEntity]
required: true
The transaction list.

DeleteTransactionEntity

Parameter Description
externalId
type: string
required: true
Persistent identifier for the transaction.
Status Code Description
204 Transactions deleted.
400 The payload does not pass validation, or the specified account does not exist.
401 User not found.
404 Transaction not found.

Update transactions

PUT /connector/users/{externalUserId}/transactions/{externalTransactionId}

Updates a single transaction related to an account.

Request Example

{
  "transactionAccounts": [
    {
      "balance": 7000,
      "externalId": "2d3bd65493b549e1927d97a2d0683ab9",
      "payload": {},
      "reservedAmount": 2000,
      "tinkId": "e4a47d5e3d514ca4bd22130bb43c640b",
      "transactions": [
        {
          "amount": -98,
          "date": 1455740874875,
          "description": "Riche Teatergrillen",
          "externalId": "40dc04e5353547378c84f34ffc88f853",
          "payload": {},
          "pending": false,
          "tinkId": "string",
          "type": "CREDIT_CARD"
        }
      ]
    }
  ],
  "type": "REAL_TIME"
}

Parameters

Parameter Description
externalUserId
required: true
Persistent identifier for the user.
externalTransactionId
required: true
Persistent identifier for the transaction.

Request Body: UpdateTransactionAccountContainer

Container of account and transactions

Parameter Description
transactionAccounts
type: array[UpdateTransactionAccountEntity]
required: true
The transaction accounts.
type
type: string
required: true
Indicating if this a historical batch of transactions or a real time transaction.. Values: REAL_TIME

UpdateTransactionAccountEntity

Parameter Description
balance
type: number
required: true
The balance of the account for the time of the last transaction in the list.
externalId
type: string
required: false
Persistent identifier for the account the transaction belongs to. Either this or tinkId must be set.
payload
type: object
required: false
The payload property can include arbitrary metadata provided by the financial institution in question that can be used either for deep-linking back to the app of the financial institution, for displaying additional information about the account, or for backend purposes such as automatic categorization improvement, etc. The format is key-value, where key is a String and value any object.
reservedAmount
type: number
required: false
The reserved amount of the account for the time of the last transaction in the list.
tinkId
type: string
required: false
Persistent identifier for the account the transaction belongs to generated by Tink. Either this or externalId must be set.
transactions
type: array[CreateTransactionEntity]
required: true
The list of transactions to update.

CreateTransactionEntity

Parameter Description
amount
type: number
required: true
The debited/credited amount in the currency of the account.
date
type: number
required: true
Date is when the transaction was executed, not when it was settled (except for scheduled transfers/payments, where the settling date is to be interpreted as the execution date).
description
type: string
required: true
A merchant name if possible. If such value is not available, the description that is shown in the transaction list.
externalId
type: string
required: true
Persistent identifier for the transaction.
payload
type: object
required: false
The payload property can include arbitrary metadata provided by the financial institution in question that can be used either for deep-linking back to the app of the financial institution, for displaying additional information about the transaction, or for backend purposes such as automatic categorization improvement, etc. The format is key-value, where key is a String and value any object.
pending
type: boolean
required: false
If the transaction is pending (reserved) or not (booked).
tinkId
type: string
required: false
Ignored for new objects. Used to specify the id as given by Tink on when updating objects without an existing external ID.
type
type: string
required: true
The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL
Status Code Description
204 Transactions updated.
400 The payload does not pass validation, or the specified account does not exist.
401 User not found.
404 Transaction not found.