NAV Navbar
Examples

General

Introduction

This document gives an overview of the layout and specification of the Connector located in the Tink cluster to get data from customers core systems.

The connector domain model consists of basically three levels:

User The top domain object, holding information about the authenticated user.

Account A user can have one or several accounts. An account could be a savings account, checking account, credit card, mortgage or car loan. An account holds information like: balance, name and number.

Transaction An account can have one or several transactions. A transaction holds information like: amount, date and description.

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.

Authorization

Communication to the ingest endpoints requires a authorization token to be sent in the HTTP header. Certificate pinning is advised, to validate the authenticity of the target host.

The authorization token is submitted according to the standard authorization scheme (in the Authorization field) with token as authorization mechanism.

The token is supplied by Tink, and may be regularly updated. When updated, there will be a grace period during which several tokens are enabled simultaneously to guarantee a seamless transition to the new token. Authorization: Token 88eb60f24418495ab0a172b89e631fa6

User

To enrol a customer into the Tink Platform, a user object (user ID, a token and optional customer details) is sent to the /user endpoint. This user ID and user token will act as a username and password respectively for the user when quering data from the Main API.

So, in order to read this newly activated user's data, you would query the Main API with the Authorization header set to Basic base64(user ID:token).

After successful activation of a user, the customer’s accounts can be created by calling the endpoint in Account Service on the Connector.

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.

API Reference

Account Service

Ingest accounts

Takes a list of accounts and the corresponding user ID.

POST /connector/users/{externalUserId}/accounts

Request Example

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

Parameters

Parameter Required Description
externalUserId true Persistent identifier for the user.

Request Body: AccountListEntity

The accounts.

Parameter Type Required Description
accounts array[AccountEntity] true The accounts.

AccountEntity

Parameter Type Required Description
availableCredit number The available credit of the account.
balance number true The balance of the account.
externalId string true Persistent identifier for the account.
flags array[string] A list of flags specifying attributes on an account
name string true The account name.
number string true The account number.
payload object 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 number The currently reserved amount of the account.
type string true The account type.. Values: CHECKING, SAVINGS, INVESTMENT, MORTGAGE, CREDIT_CARD, LOAN, PENSION, OTHER, EXTERNAL

Delete account

Deletes the account with the given account ID.

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

Parameters

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

Batch Service

Ingest transactions

Takes historical or real time transactions together with an account.

POST /connector/batch

Request Example

{
  "ingestEntities": [
    {
      "container": {
        "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"
      },
      "entityId": "2d3bd65493b549e1927d97a2d0683ab9",
      "externalUserId": "2d3bd65493b549e1927d97a2d0683ab9"
    }
  ],
  "withinLimit": false
}

Request Body: CreateTransactionBatch

Batch of Ingest Transaction entities.

Parameter Type Required Description
ingestEntities array[IngestTransactionEntity] true The batch entities. May contain a maximum of 2500 entities per request.
withinLimit boolean

IngestTransactionEntity

Parameter Type Required Description
container CreateTransactionAccountContainer true The create transaction container.
entityId string true An id of this entity. Will only be used to return back to caller.
externalUserId string true Persistent external identifier for the user.

CreateTransactionAccountContainer

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

CreateTransactionAccountEntity

Parameter Type Required Description
balance number true The balance of the account for the time of the last transaction in the list.
externalId string true Persistent identifier for the account the transaction belongs to.
payload object 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 number The reserved amount of the account for the time of the last transaction in the list.
transactions array[CreateTransactionEntity] true The transaction list.

CreateTransactionEntity

Parameter Type Required Description
amount number true The debited/credited amount in the currency of the account.
date number 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 string true A merchant name if possible. If such value is not available, the description that is shown in the transaction list.
externalId string true Persistent identifier for the transaction.
payload object 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 boolean If the transaction is pending (reserved) or not (booked).
tinkId string Ignored for new objects. Used to specify the id as given by Tink on when updating objects without an existing external ID.
type string true The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL

Response Example

{
  "statuses": [
    {
      "entityId": "string",
      "httpStatus": 0,
      "response": ""
    }
  ]
}

Response: TransactionBatchResponse

Parameter Type Required Description
statuses array[IngestTransactionStatus]

IngestTransactionStatus

Parameter Type Required Description
entityId string
httpStatus integer
response object

Token Service

Generate token

Generates a token that can be used to validate an end-user to the Tink services.

POST /connector/v2/tokens/generate

Request Example

{
  "origin": "ABC1",
  "scopes": [
    "transactions:read"
  ],
  "ttl": 10800,
  "userId": "2ce1f090a9304f13a15458d480f8a85d"
}

Request Body: GenerateTokenRequest

Token generation request

Parameter Type Required Description
origin string (Optional) Identifier for the external service that sent the token generation request.
scopes array[string] true Set of scopes which the token is supposed to be generated for.
ttl integer Time to live for generated token in seconds (max 3 hours).
userId string true Persistent identifier for the user.

Response Example

{
  "expiry": 762273900000,
  "token": "abcdefghijk.lmnopqrstuvwxyz.0123ABC789-_"
}

Response: GenerateTokenResponse

Parameter Type Required Description
expiry integer Timestamp for the expiration of the returned token.
token string true User access token.

Transaction Service

Ingest transactions

Takes historical or real time transactions together with an account.

POST /connector/users/{externalUserId}/transactions

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 Required Description
externalUserId true Persistent identifier for the user.

Request Body: CreateTransactionAccountContainer

Container of account and transactions.

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

CreateTransactionAccountEntity

Parameter Type Required Description
balance number true The balance of the account for the time of the last transaction in the list.
externalId string true Persistent identifier for the account the transaction belongs to.
payload object 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 number The reserved amount of the account for the time of the last transaction in the list.
transactions array[CreateTransactionEntity] true The transaction list.

CreateTransactionEntity

Parameter Type Required Description
amount number true The debited/credited amount in the currency of the account.
date number 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 string true A merchant name if possible. If such value is not available, the description that is shown in the transaction list.
externalId string true Persistent identifier for the transaction.
payload object 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 boolean If the transaction is pending (reserved) or not (booked).
tinkId string Ignored for new objects. Used to specify the id as given by Tink on when updating objects without an existing external ID.
type string true The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL

Delete transactions

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

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

Request Example

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

Parameters

Parameter Required Description
externalUserId true Persistent identifier for the user.

Request Body: DeleteTransactionAccountsContainer

Container of account and transactions.

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

DeleteTransactionAccountEntity

Parameter Type Required Description
balance number true The balance of the account for the time of the last transaction in the list.
externalId string true Persistent identifier for the account the transaction belong to.
payload object 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 number The reserved amount of the account for the time of the last transaction in the list.
transactions array[DeleteTransactionEntity] true The transaction list.

DeleteTransactionEntity

Parameter Type Required Description
externalId string true Persistent identifier for the transaction.

Update transactions

Updates a single transaction related to an account.

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

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 Required Description
externalUserId true Persistent identifier for the user.
externalTransactionId true Persistent identifier for the transaction.

Request Body: UpdateTransactionAccountContainer

Container of account and transactions

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

UpdateTransactionAccountEntity

Parameter Type Required Description
balance number true The balance of the account for the time of the last transaction in the list.
externalId string Persistent identifier for the account the transaction belongs to. Either this or tinkId must be set.
payload object 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 number The reserved amount of the account for the time of the last transaction in the list.
tinkId string Persistent identifier for the account the transaction belongs to generated by Tink. Either this or externalId must be set.
transactions array[CreateTransactionEntity] true The list of transactions to update.

CreateTransactionEntity

Parameter Type Required Description
amount number true The debited/credited amount in the currency of the account.
date number 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 string true A merchant name if possible. If such value is not available, the description that is shown in the transaction list.
externalId string true Persistent identifier for the transaction.
payload object 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 boolean If the transaction is pending (reserved) or not (booked).
tinkId string Ignored for new objects. Used to specify the id as given by Tink on when updating objects without an existing external ID.
type string true The type of the transaction.. Values: DEFAULT, CREDIT_CARD, TRANSFER, PAYMENT, WITHDRAWAL

User Service

Activate a user

Activates a user.

POST /connector/users

Request Example

{
  "blocked": false,
  "externalId": "2ce1f090a9304f13a15458d480f8a85d",
  "locale": "en_US",
  "market": "SE",
  "token": "9ac7f1611519afa1a66488ad11fda19a"
}

Request Body: UserEntity

The user

Parameter Type Required Description
blocked boolean Set to either block or unblock the user.
externalId string true Persistent identifier for the user.
locale string Set locale for the user. Defaults to default locale for the user's market.
market string Market specific code for the user as a ISO 3166-1 country code.. 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
token string true Access token for the user. This is required later as authentication when fetching data for the user.

Delete a user

Deletes a user.

DELETE /connector/users/{externalUserId}

Parameters

Parameter Required Description
externalUserId true Persistent identifier for the user.

Update a user

Updates a user.

PUT /connector/users/{externalUserId}

Request Example

{
  "blocked": false,
  "externalId": "2ce1f090a9304f13a15458d480f8a85d",
  "locale": "en_US",
  "market": "SE",
  "token": "9ac7f1611519afa1a66488ad11fda19a"
}

Parameters

Parameter Required Description
externalUserId true Persistent identifier for the user.

Request Body: UserEntity

The user

Parameter Type Required Description
blocked boolean Set to either block or unblock the user.
externalId string true Persistent identifier for the user.
locale string Set locale for the user. Defaults to default locale for the user's market.
market string Market specific code for the user as a ISO 3166-1 country code.. 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
token string true Access token for the user. This is required later as authentication when fetching data for the user.

Version Service

Get the version

Gets the current version (build) of the application

GET /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

Get all registered webhooks.

Returns an object with a list of all the registered webhooks.

GET /connector/webhooks

Response Example

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

Response: WebhookListEntity

Parameter Type Required Description
webhooks array[WebhookEntity] A list with the registered webhooks.

WebhookEntity

Parameter Type Required Description
events array[string] true A list of events to register webhooks for.
id string The internal Tink ID of the webhook.
secret string true A secret chosen by the partner. This secret can be used when getting the actual webhook executed back to verify it's a valid one.
url string true The URL that will receive the webhook. It needs to be over https, and Tink needs to have the domain registered in the database.

Set up a webhook.

Set up a new webhook for all users, giving the possibility to get pushed updates for certain events. The webhook will automatically concern both old and new users.

POST /connector/webhooks

Request Example

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

Request Body: WebhookEntity

The webhook request.

Parameter Type Required Description
events array[string] true A list of events to register webhooks for.
id string The internal Tink ID of the webhook.
secret string true A secret chosen by the partner. This secret can be used when getting the actual webhook executed back to verify it's a valid one.
url string true The URL that will receive the webhook. It needs to be over https, and Tink needs to have the domain registered in the database.

Delete a webhook.

DELETE /connector/webhooks/{id}

Parameters

Parameter Required Description
id true Internal Tink ID for the webhook.