NAV
code

Introduction

About Kontomatik

Kontomatik offers a variety of solutions that support financial processes - loans, leasing, bookkeeping, personal finance management and more.

This documentation covers most of our features, including:

If you want to know more about Kontomatik, please visit our homepage: https://kontomatik.com.

Getting API access

In order to get access to our services and the API, you need to have a signed contract with Kontomatik, which includes a data processing agreement. You can contact our Sales Team to request a demo and pricing details.

Once all paperwork is done, you will receive access to Insight to configure your Kontomatik account and take full advantage of our API.

Glossary

Term Description
Command Request that is sent to the Kontomatik systems to perform a specific operation.
Session A session of interaction between Kontomatik, the end-user and the bank starting when the user chooses their bank in the Widget, and ending when the data has finished importing or it has been otherwise interrupted for any reason.
Target Technical identifier of a Kontomatik-to-bank connection. The name might indicate a type of connection or the specific banking system used. For any given bank there might be multiple targets handling different audiences or systems.
Institution Technical identifier of a group of targets that share the same banking system for fetching data. Within an institution there might be multiple types of targets, but in the production environment only one of them should be provided to end-users at any given moment. Grouping was introduced to make switching between PSD2 and Fallback targets easier. For any bank there might be multiple institutions enabled (e.g. one for individual clients and one for corporate).
User, end-user, owner, PSU The owner of the imported accounts, usually the user who authorized access to the account.
SCA, 2FA (Strong Customer Authentication, Two Factor Authentication) Additional authentication methods used in banking systems to secure the access to the account, e.g. biometrics, SMS codes, in-app confirmation etc.
PSD2 target, Open Banking target Target that uses a PSD2-based connection to a bank via a dedicated API interface as per PSD2 regulations
Fallback target A target that uses a connection alternative to the PSD2 API, usually enabled when the API doesn’t work properly at the moment. Typically this uses screen-scraping methods for extracting data.
TPP (Third Party Provider) A company licensed to perform one or more PSD2-based services: Account Information Service, Payment Initiation Service and Confirmation of the Availability of Funds
AISP (Account Information Service Provider) A TPP licensed to provide Account Information Service
PolishAPI Documentation for PSD2-based APIs that describes how TPPs should integrate with Polish banks. See: https://polishapi.org
Beta An indicator used for targets or features that have been recently introduced and have not yet been proven to be fully stable in the production environment.

API Conventions

General conventions

  1. The character encoding for API requests and responses is UTF-8.

  2. Reply status codes are consistent with the HTTP response status codes:

    a. 200-299 codes assume successful command execution and you should be able to safely parse the content as per the endpoint documentation.

    b. 400-499 codes usually mean an application error. The response content should follow our standard templates (XML Error Response or JSON Error Response).

    c. 500-599 codes usually mean server/network issues; the response content might not follow any templates.

    d. Some codes (like 300-399) should be automatically handled by your HTTP agent.

  3. Element and attribute names use the camel case naming convention.

  4. Dates and times follow the ISO 8601 format, for example YYYY-MM-DD or YYYY-MM-DDThh:mm:ssZ.

  5. Currency amounts use the standard computer format with two decimal places, i.e. 0.99, -20.00.

  6. Currencies are expressed in currency symbols which follow the ISO 4217 format giving the 3-letter currency code, for example PLN, EUR etc.

  7. Any identifiers used in the process should be treated as String types, even if they contain only numbers.

  8. The /v1/ prefix in all URLs stands for the API version.

  9. Most API endpoints return an XML formatted response. Newer or reworked endpoints return JSON responses.

  10. API changes:

    a. Your integration should allow API extensions by default at any time. This includes new nodes or node attributes.

    b. The API endpoints can also be modified or become deprecated and removed in a way that is not backwards compatible. Such changes will be communicated by email to all clients in advance.

Owner data aggregation

Specifying the ownerExternalId in widgets and uploading endpoints allows you to aggregate data from multiple sources of different types or the same ones (AIS+AIS, PDF+PDF, AIS+PDF etc.).

To extract the aggregated result, use the Aggregated Data endpoint.

In Insight and for all endpoints where the ownerExternalId is a required parameter, the result is based on the aggregated data only. If you require analysis for each session separately, use a unique ownerExternalId each time, even for the same person.

ownerExternalId accepts strings with up to 255 characters. Don’t ever pass on any personal numbers of the owner (e.g. document ID, national ID), in the content of this identifier.

Commands execution limit

Importing and uploading commands (Default Import, PDF Parsing, Owner Upload, Advanced Import commands) all share the same limit of 8 simultaneous executions in progress.

While most of our clients don’t come close to reaching this limit, you might want to implement a queueing or repeating solution to call our endpoints.

Authentication

Environments

The public API is available in two different environments: test and production.

The test environment usually runs the same version of our software with some configuration differences, lower server capacity and stability, but offers our mock bank for testing purposes.

Addresses:

Clients with dedicated deployments need to use addresses provided to them during the implementation process.

API credentials

To use the Kontomatik API, you need to make the calls from a server that has been whitelisted. Additionally, endpoints require an API key provided in a X-Api-Key header.

You can whitelist your servers and generate API keys in Insight for each environment separately.

In some cases you will need to use a client ID provided to you by Kontomatik. It’s different for each environment and usually follows the pattern:

You’ll find your client ID in Insight on the top left side.

Owner Data Model

The Owner Data Model describes data structures related to owners and their financial information. API features related to importing or fetching data use this model to return the results.

This model is used in both XML and JSON responses.

Owners section

<owners>
    <owner>
        <name>Mariusz Dawny</name>
        <kind>CO_OWNER</kind>
    </owner>
    <owner>
        <name>Maciek Obróbka</name>
        <kind>CO_OWNER</kind>
    </owner>
    <owner>
        <name>Budrog Poland S.P. Z.O.O</name>
        <address>Narcyzów 15 56-239 Lublin</address>
        <polishNip>1156361014</polishNip>
        <kind>COMPANY</kind>
    </owner>
</owners>

 "owners": [
    {
          "name": "Tadeusz Krajowy",
          "address": null,
          "kind": "CO_OWNER"
    },
    {
          "name": "Maria Sochacka",
          "address": "Stolarska 15/2 33-543 Jaworzno",
          "kind": "OWNER"
    }
 ]

The <owners> node contains a list of owners appearing on any of the imported accounts.

Please note that this data is not always directly provided by banks. In some cases it will be extracted from details of transactions or otherwise assumed. Additionally, it's important to be aware that banks may not always return information about owners. To verify whether a specific bank provides owner information, you can refer to the details outlined in the documentation listed in the Coverage section.

Each owner is placed in an <owner> structure which contains the following fields:

Node Availability Description
kind always See: Owner kind
name always Full name of the owner or company
address possibly none Address(es) of the owner. In case multiple addresses are found, they will be listed in a comma-separated format.
polishNip possibly none Polish NIP number
polishRegon possibly none Polish REGON number
phone possibly none Phone number
email possibly none E-mail address
citizenship possibly none Citizenship
nationality possibly none Nationality
personalDocumentType possibly none Identity document type
personalDocumentNumber possibly none Identity document number
birthDate possibly none Date of birth
birthPlace possibly none Place of birth

Owner kind

Owner kind provided in the kind field can have one of the following values:

Kind Description
OWNER Default owner type, assigned when the type cannot be determined, the person is the main owner or the person has logged into the account
CO_OWNER Person with access to the account, regardless of the permission level, usually appears when another person is marked as OWNER
COMPANY The owner of the account is a legal entity

Each kind can appear multiple times within one account.

Account section


<accounts>
    <account>
        <name>Konto 1</name>
        <friendlyName>Konto prywatne</friendlyName>
        <iban>PL46132019990000061081356879</iban>
        <currencyBalance>255923.39</currencyBalance>
        <currencyFundsAvailable>255923.39</currencyFundsAvailable>
        <currencyName>PLN</currencyName>
        <activeSinceAtLeast>2023-08-06</activeSinceAtLeast>
        <directDebit available="false"/>
        <moneyTransactions>
            <moneyTransaction>
                ...
            </moneyTransaction>
            <moneyTransaction>
                ...
            </moneyTransaction>
        </moneyTransactions>
        <owners>
            <owner>
                <name>Budrog Poland S.P. Z.O.O</name>
                <address>Narcyzów 15 56-239 Lublin</address>
                <kind>COMPANY</kind>
            </owner>
            <owner>
                <name>Mariusz Dawny</name>
                <kind>CO_OWNER</kind>
            </owner>
        </owners>
    </account>
    <account>
        ...
    </account>
</accounts>

The <accounts> node contains a list of accounts, each of them inside an <account> structure with the following fields:

Node Availability Description
name always [AIS], possibly none [PDF] Account name, usually as shown in the bank’s transaction system
friendlyName possibly none Account name, assigned by the user
iban always Account number
currencyBalance always [AIS], possibly none [PDF] Account balance expressed in the account's currency.
currencyFundsAvailable always [AIS], possibly none [PDF] Account balance at the user’s immediate disposal, expressed in the account's currency.
currencyName always Currency of the account
activeSinceAtLeast always The date when the account was opened or the date of the oldest transaction found (limited to the past year)
directDebit possibly none Specifies whether the account supports direct debit or not, contains available attribute set to true or false
owners almost always List of owners for that particular account. This structure is identical to the Owners section structure with a restriction to 3 fields: kind, name, address.
moneyTransactions almost always See: Account Transactions section. Empty if no transactions were found on the account in the specified period.

Account Transactions section

<accounts>
    <account>
        ...
        <moneyTransactions>
            <moneyTransaction>
                <transactionOn>2023-08-27</transactionOn>
                <bookedOn>2023-08-28</bookedOn>
                <currencyAmount>-25.00</currencyAmount>
                <currencyBalance>255923.39</currencyBalance>
                <title>SWIAT PRASY GDYNIA</title>
                <kind>TRANSAKCJA KARTĄ PŁATNICZĄ</kind>
                <status>DONE</status>
                <labels>
                    <label>press</label>
                    <label>leisure</label>
                </labels>
            </moneyTransaction>
            <moneyTransaction>
                <transactionOn>2023-08-27</transactionOn>
                <bookedOn>2023-08-28</bookedOn>
                <currencyAmount>2800.00</currencyAmount>
                <currencyBalance>255948.39</currencyBalance>
                <title>Wynagrodzenie za pracę</title>
                <party>LIDL POLSKA SP Z O O</party>
                <partyIban>PL48105000021572771618714189</partyIban>
                <kind>PRZELEW PRZYCHODZĄCY</kind>
                <status>DONE</status>
                <labels>
                    <label>salary</label>
                    <label>compensation</label>
                </labels>
            </moneyTransaction>
            <moneyTransaction>
                ...
            </moneyTransaction>
        </moneyTransactions>
        <owners>
            ...
        </owners>
    </account>
    <account>
        ...
    </account>
</accounts>

Account transactions visible in the <account> node are held within a <moneyTransactions> structure. Each transaction in a <moneyTransaction> node includes the following fields:

Node Availability Description
transactionOn always* Transaction date
bookedOn always* Transaction booking date
currencyAmount always Transaction amount expressed in the account currency. It can be positive or negative, reflecting the flow of the funds.
currencyBalance possibly none Account balance after the transaction in the account currency
partyIban possibly none Account number of the other party in the transaction
party possibly none Name of the other party in the transaction
kind possibly none Transaction type as stated by the bank, e.g. “Transakcja kartą debetową”
title possibly none Transaction title
status (beta) AIS only, possibly none Transaction status, can take one of the following values DONE, PENDING, REJECTED, SCHEDULED, HOLD
labels possibly none See: Transaction Labeling. Only when using the service and only when any labels have been assigned to that transaction.
analytics possibly none See: Transaction analytics. Only when using the Vendors Recognition service and only when any labels or vendors have been assigned to that transaction.

*in PDF Parsing only one of the two might appear depending on the document

When using AIS in Czech banks the <moneyTransaction> node might also contain the following fields:

Node Availability Description
variableSymbol possibly none Identifier used for payments in Czech Republic (variabilní symbol)
constantSymbol possibly none Identifier used for payments in Czech Republic (konstantní symbol)

Credit Cards section

<creditCards>
    <creditCard>
        <name>Karta kredytowa 1</name>
        <cardId>PL02909610140000069993720246</cardId>
        <iban>PL02909610140000069993720246</iban>
        <number>5287********7137</number>
        <currencyBalance>121808.34</currencyBalance>
        <currencyFundsAvailable>121808.34</currencyFundsAvailable>
        <currencyName>PLN</currencyName>
        <limit>0.00</limit>
        <dueDate>2020-09-04</dueDate>
        <moneyTransactions>
            <moneyTransaction>
                <transactionOn>2023-08-27</transactionOn>
                <bookedOn>2023-08-28</bookedOn>
                <currencyAmount>-5.00</currencyAmount>
                <currencyBalance>121808.34</currencyBalance>
                <title>Opłata za kartę</title>
                <kind>OPŁATA</kind>
                <status>DONE</status>
                <labels>
                    <label>fee</label>
                </labels>
            </moneyTransaction>
            <moneyTransaction>
                ...
            </moneyTransaction>
        </moneyTransactions>
        <owners>
            <owner>
                <name>Budrog Poland S.P. Z.O.O</name>
                <address>Narcyzów 15 56-239 Lublin</address>
                <kind>COMPANY</kind>
            </owner>
            <owner>
                <name>Mariusz Dawny</name>
                <kind>CO_OWNER</kind>
            </owner>
        </owners>
    </creditCard>
</creditCards>

The <creditCard> node contains a list of credit cards, each of them inside a <creditCard> structure with the following fields:

Node Availability Description
name always Card name, usually as shown in the bank’s transaction system
cardId always Arbitrary card ID assigned by Kontomatik, based on either IBAN or the card number
iban always Account number of the bank account linked to the credit card
cardNumber possibly none Card number
currencyBalance always Current credit card balance in the card currency
currencyFundsAvailable possibly none The amount of available credit in the card currency
currencyName always Currency of the credit card
owners possibly none List of owners for that particular account. This structure is identical to the Owners section structure with a restriction to 3 fields: kind, name, address.
limit possibly none Credit limit
interest possibly none Card interest rate, expressed in percentage
dueDate possibly none Date on which the card repayment is due
moneyTransactions almost always See: Credit Card Transactions section. Empty if no transactions were found on the account in the specified period.

Credit Card Transactions section

<creditCards>
    <creditCard>
        ...
        <moneyTransactions>
            <moneyTransaction>
                <transactionOn>2023-08-27</transactionOn>
                <bookedOn>2023-08-28</bookedOn>
                <currencyAmount>-5.00</currencyAmount>
                <currencyBalance>121808.34</currencyBalance>
                <title>Opłata za kartę</title>
                <kind>OPŁATA</kind>
                <status>DONE</status>
                <labels>
                    <label>fee</label>
                </labels>
            </moneyTransaction>
            <moneyTransaction>
                ...
            </moneyTransaction>
        </moneyTransactions>
        ...
    </creditCard>
</creditCards>

Credit card transactions visible in the <creditCard> node are held within a <moneyTransactions> structure. Each transaction in a <moneyTransaction> node includes the following fields:

Node Availability Description
transactionOn always Transaction date
bookedOn always Transaction booking date
currencyAmount always Currency amount in the card’s currency
currencyBalance possibly none Current credit card balance after the transaction in the card’s currency
partyIban possibly none Account number of the other party in the transaction
party possibly none Name of the other party in the transaction
kind possibly none Transaction type as stated by the bank, e.g. “Transakcja kartą kredytową”
title possibly none Transaction title
labels possibly none See: Transaction Labeling. Only when using the service and only when any labels have been assigned to that transaction.

Transaction analytics (beta)

Returns transaction-specific analysis, mainly based on our Data Analytics features.

Analysis results will appear in the <analytics> section of the <moneyTransaction> structure. Currently the section only appears if you have the Vendors Recognition enabled.

Transaction analytics - labels

<analytics>
    <labels>
        <label>
            <name>e commerce</name>
        </label>
        <label>
            <name>payment processor</name>
        </label>
        <label>
            <name>beauty</name>
        </label>
    </labels>
</analytics>

When you have Labeling and Vendors Recognition enabled, the <analytics> section might contain the <labels> node - in case any labels were assigned.

Inside you’ll find each assigned label in a <label> structure with its name in the <name> node.

Please consult the example on the right.

Transaction analytics - vendors

<analytics>
    <labels>
      <label>
       <name>e commerce</name>
        <vendors>
         <vendor>Amazon</vendor>
        </vendors>
      </label>
        <label>
         <name>payment processor</name>
          <vendors>
           <vendor>Blik</vendor>
          </vendors>
      </label>
      <label>
       <name>beauty</name>
      </label>
    </labels>
</analytics>

Whenever any vendors get recognized in a single transaction, each <label> node from the Transaction analytics - labels section might contain a <vendors> structure. Inside, each vendor identifier is contained within the <vendor> node.

Account Information Service

Introduction

Account Information Service (AIS) allows you to fetch live data from the end-user's bank.

In order to integrate, you need to embed our SignIn Widget first, which allows the users to sign in to their online banking accounts and consent to a data import.

Once the user successfully passes this stage, you will receive session identifiers from the Widget. You need to pass them to your backend.

Then call the Default Import endpoint to set up the importing command. You will receive the command identifier immediately, but the command will be running in the background, fetching data from the bank.

Finally, you need to call the Get Import Result endpoint repeatedly (in 2-5 seconds intervals) to know if the importing has finished. If it has, you will get the user’s data as a result.

If you don’t want to integrate with our API you can also use the Auto import option (a.k.a. the zero-integration solution).

Access modes

The Account Information Service works in two modes:

You can specify the desired access mode in the SignIn Widget as it will impact the login process and the list of available banks.

Multiple Access is not enabled by default. Please contact Sales for details.

SignIn Widget

Kontomatik SignIn Widget is an HTML5 iframe element that you embed on your website by calling our JavaScript.

Upon successful sign-in, you will be provided with the sessionId and sessionIdSignature parameters. You will need them to execute Kontomatik API commands.

Jump to section:

Embedding the SignIn Widget

<!-- index.html / head -->
<script src="https://signin.kontomatik.com/assets/signin-widget.js">
</script>

<!-- index.html / body -->
<div id="kontomatik" />

// index.js
embedKontomatik({
  client: 'YOUR_CLIENT_ID',  // replace it with your assigned client id
  divId: 'kontomatik',       // must match the div element id
  onSuccess: function(target, sessionId, sessionIdSignature, options) {
    // End-user successfully signed in to the bank
    // Pass target, sessionId and sessionIdSignature to your backend
    alert('It works!');
  }
});

To embed the Widget on your web page:

  1. Reference the widget's JavaScript library.

  2. Add an empty <div> element, where you want your widget to be rendered. You need to specify the ID of that element.

  3. Call the embedKontomatik() JS function, specifying the required parameters.

See the provided code examples.

SignIn Widget parameters

To use the parameters mentioned in this section, pass them in a JSON object to the embedKontomatik() function.

Required parameters

Parameter Description
client Your client ID, as per API credentials. Make sure to use the right one for each environment.
divId ID of the div element where the Widget should be rendered. Make sure this element already exists before calling the embedKontomatik() function.
onSuccess Callback function triggered when the end-user successfully logs in to their bank. See: onSuccess callback.
Parameter Default Description
country null Pre-selects the country from which the available banks will be displayed in the widget. Accepted values: cz, ee, es, it, lt, lv, pl, pt, ro, se.
If omitted, the country drop-down list will be shown.
locale en Determines the Widget interface language. Accepted values: cz, en, es, et, it, lt, lv, pl, pt, ro, ru.
ownerExternalId null Identifier generated by you and used for Owner data aggregation
onError null Callback function triggered when any error or exception occurs during the login process. See: onError callback.

Other parameters

Parameter Default Description
autoImport null See: Auto import (zero-integration)
target null (not recommended) Pre-selects the end-user’s bank. See: Own list for bank selection
showScreenshot true Determines whether screenshots of the bank login process are visible in the Widget
showBetaQualityLabels true/false For targets in the beta stage, the option will show a "beta" label next to the bank name. Default is true in the test environment, false in production.
showTargetMissingOption true Shows an additional option for users to suggest a new bank not available in the Widget
showTargetMissingForm true When set to false, you can show the user your own suggestion form for a new target, see: onUnsupportedTarget callback
dynamicHeight false Determines whether the height of the <iframe> will change dynamically based on the content of the element.
fluidWidth false If set to true, the width of the <iframe> will adjust to the width of the container. The list of banks displayed will transform into tiles as the width extends.
styling null See: Styling the SignIn Widget
psd2 null Contains settings specific to PSD2 targets. See: psd2 parameter

You can also implement other optional callbacks described in the SignIn Widget callbacks section.

psd2 parameter

// index.js
embedKontomatik({
  //client: 'YOUR_CLIENT_ID', divId: 'kontomatik',       // must match the div element id
  onSuccess: function(target, sessionId, sessionIdSignature, options) {
    alert('It works!'); // End-user successfully signed in to the bank
  },
  psd2: {
    accessMode: `SINGLE`,
    forceSca: true,
    maxImportDate:  '2019-01-01'
  }
});
Parameter Default Description
accessMode SINGLE Possible values:
  • SINGLE - creates only single import sessions
  • MULTIPLE - shows only targets which support Multiple Access and creates only Multiple Access sessions
  • MIXED - if the target selected by the user supports Multiple Access, this mode will create a Multiple Access session. Otherwise, it will create a single import session.

See: Access modes
multipleAccessEmail null The option to provide the end-user’s email address for the Multiple Access process. Regardless of whether the address has been provided in this parameter or not, the end user will be able to enter/edit it during the login process.
maxImportDate null Date in the YYYY-MM-DD format. The earliest date from which you want the transactions to be imported.
See: Getting more than 90 days history
forceSca false Shows additional steps in targets that require SCA in some cases, especially for fetching more than 90 days of transaction history.
It will be ignored if the target doesn’t support separate flows.
See: Getting more than 90 days history

SignIn Widget callbacks

The SignIn Widget comes with a set of callbacks, which are invoked when the Widget enters a new state or an important event takes place.

Only the onSuccess callback must be implemented. All other callbacks are optional.

The following figure presents a visual reference for the callbacks and the Widget's transition between stages:

AIS onSuccess callback

Called when the user successfully signs into the banking system. The parameters below will be sent to this callback:

Parameter Description
target Name of the target the user has signed into
sessionId ID of the session assigned by Kontomatik
sessionIdSignature Signature assigned to the sessionId ensuring protection against enumeration attacks
options Extra parameters; see the table below

The options object contains the following:

Parameter Availability Description
officialName always Full bank name
multipleAccessId only for Multiple Access ID of the Multiple Access token assigned by Kontomatik

AIS onError callback

Called when anything goes wrong during the login process. The parameters below will be sent to this callback:

Parameter Description
exception Name of the exception. See: Error handling
options Extra parameters; see the table below

The options object contains the following:

Parameter Availability Description
target if session has been created Name of the target the user has signed into
officialName if session has been created Full bank name
sessionId if session has been created ID of the session assigned by Kontomatik
widgetSessionId always ID assigned to the ongoing user interaction with the Widget. May encompass multiple Kontomatik sessions. Reset to a new value upon refresh.

AIS onUnsupportedTarget callback

The callback is triggered when showTargetMissingOption is set to true and:

The parameters below will be sent to this callback:

Parameter Description
target Name of the bank provided by the user
country Country code
address Bank website URL provided by the user

AIS onInitialized callback

Called when the Widget is loaded and ready for user interaction. It will be fired once in the Widget’s lifecycle.

AIS onStarted callback

Called each time the bank selection list is shown to the user. An object parameter will be sent to this callback with fields listed below:

Parameter Availability Description
widgetSessionId always ID assigned to the ongoing user interaction with the Widget. May encompass multiple Kontomatik sessions. Reset to a new value upon refresh.

AIS onTargetSelected callback

Called when the user has selected a bank. The parameters below will be sent to this callback:

Parameter Description
name Name of the selected target
officialName Full bank name

AIS onSessionCreated callback

Called after the session has been successfully created. The parameters below will be sent to this callback:

Parameter Description
sessionId ID of the session assigned by Kontomatik

AIS onConsentsGiven callback

Called after the user accepts all required consents and gets redirected to the next Widget step.

AIS onCredentialEntered callback

Called after the user submits a credential or, in case it's an API target, just before the user gets redirected to the bank’s website.

AIS onRedirect callback

Called after the user clicks the "continue" button and gets redirected to the bank’s website for authentication. Happens only for the PSD2-based targets.

AIS onReset callback

Called when the user clicks a button to go back to the first page of the process, typically the bank selection step.

Reloading the Widget

If you dynamically reload the SignIn Widget on the frontend, the already registered callbacks will be attached to the previously created session and cause errors when trying to use the new instance of the Widget.

In order to manage this, please use the removeKontomatik() function before calling for embedKontomatik() again.

Styling the SignIn Widget

Example

embedKontomatik({
  client: 'YOUR_CLIENT_ID',
  divId: 'kontomatik',
  onSuccess: function (target, sessionId, sessionIdSignature, options) {
    // End-user successfully signed in to the bank
    alert('It works!');
  },
  styling: {
    "bgColor": "#252C38",
    "textColor": "#CECECE",
    "borderColor": "#656F86",
    "primaryColor": "#7CCDEE",
    "secondaryColor": "#FFFFFF",
    "mainHoverColor": "#395572",
    "listHoverColor": "#3F4A5B",
    "disabledColor": "#CED4DA",
    "errorColor": "#FF5454"
  }
});

Using CSS overrides or any other external modifications of the Widget are strictly forbidden. You can, however, use the styling setting of the Widget to adjust some properties - just add the styling node inside of your embedKontomatik() function.

When using the setting, you don’t need to use all properties inside - just the ones you want to change compared to the default version.

Example on the right depicts a proposal for a dark mode.

Color properties accept only HEX (#FFF) and RGB (rgb(12, 32, 111)) notations.

Size properties accept all standard CSS units for size: px, em, rem etc.

The styling node contains the following fields:

Key Default Description
bgColor #FFF Background of the elements: Widget body, lists, inputs
textColor #000 All standard texts, including texts inside inputs and lists
borderColor #E5E5E5 Border of elements: list containers, tiles, inputs
primaryColor #2E3F5B Headings, input names, primary buttons background, links, tags, other elements meant to stand out, inputs active/focused border
primaryReverseColor #FFF Text color for primary buttons
secondaryColor #586374 Secondary button text (no background), other elements meant to stand out less than primary
mainHoverColor #7CCDEE Background color for hovered primary buttons, text color for hovered secondary buttons, hovered links color
mainHoverReverseColor #FFF Text color for hovered primary buttons
listHoverColor #F5F5F5 Background color for hovered list items, meant to be subtle and contrast well with textColor and primaryColor
disabledColor #CED4DA Text color for disabled inputs and list items
errorColor #BB0000 Error text color, inputs validation
borderRadius 25px Border radius for primary buttons and inputs

Default Import

The Default Import command sets up a data import process.

Once called, you will receive an identifier of the command for the specific session and Kontomatik servers will begin fetching all data asynchronously in the background.

While the import is happening you have to call Get Import Result repeatedly until you receive a final status, ideally with the data you requested.

For each session you can call this command only once!

Request

Request

curl \
 --header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
 --data "sessionId=999999" \
 --data "sessionIdSignature=ffff....ffff" \
 --data "since=YYYY-MM-DD" \
https://test.api.kontomatik.com/v1/command/default-import.xml

POST /v1/command/default-import.xml

Required parameters:

Parameter Description
sessionId ID of the session assigned by Kontomatik
sessionIdSignature Signature assigned to the sessionId ensuring protection against enumeration attacks
since Date in the YYYY-MM-DD format. The earliest date from which you want the transactions to be imported.
The date parameter must be set within a maximum range of five years. With any dates beyond this limit it will be automatically trimmed to five years in the past, or to the one passed in maxImportDate

Response

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/command.xsd" status="202 Accepted">
  <command id="000000" state="setup" name="DefaultImportCommand">
    <progress><value>0</value></progress>
  </command>
</reply>

Final result of polling for this command status

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/default_import.xsd" status="200 OK">
  <command id="653643" state="successful" name="DefaultImportCommand" target="Alior" institution="Alior">
    <progress><value>13</value></progress>
    <result>
      <owners>
        <owner>
          <name>Jan Kowalski</name>
          <address>Kwiatowa 8/97 Warszawa  PL</address>
          <phone>+48612***078</phone>
          <email>jankowalski@xgmail.com</email>
          <citizenship>PL</citizenship>
          <personalDocumentType>Identity document</personalDocumentType>
          <personalDocumentNumber>AAB123456</personalDocumentNumber>
          <birthDate>1984-01-18</birthDate>
          <kind>OWNER</kind>
        </owner>
        <!-- ... more owners ... -->
      </owners>
      <accounts>
        <account>
          <name>eKONTO</name>
          <iban>PL32114020040000320250132522</iban>
          <currencyBalance>1467.39</currencyBalance>
          <currencyFundsAvailable>1407.39</currencyFundsAvailable>
          <currencyName>PLN</currencyName>
          <activeSinceAtLeast>2000-02-28</activeSinceAtLeast>
          <moneyTransactions>
            <moneyTransaction>
              <transactionOn>2012-06-28</transactionOn>
              <bookedOn>2012-06-30</bookedOn>
              <currencyAmount>20.00</currencyAmount>
              <title>Return for beer in a pub</title>
              <party>Jan Kowalski</party>
              <partyIban>PL68249000050000400075212326</partyIban>
              <kind>EXTERNAL INCOMING TRANSFER</kind>
              <labels>
                <label><!-- label type --></label>
                <!-- ... more labels ... -->
              </labels>
            </moneyTransaction>
            <!-- ... more transactions ... -->
          </moneyTransactions>
          <owners>
            <owner>
              <name>Jan Kowalski</name>
              <address>Kwiatowa 8/97 Warszawa  PL</address>
              <kind>OWNER</kind>
            </owner>
            <owner>
              <name>Adam Nowak</name>
              <kind>CO_OWNER</kind>
            </owner>
          </owners>
        </account>
        <!-- ... more accounts ... -->
      </accounts>
      <!-- ... if target supports credit cards import -->
      <creditCards>
            <creditCard>
               <name>Karta Kredytowa W/Shell</name>
               <cardId>**************13</cardId>
               <iban>PL19025714369262645919804211</iban>
               <number>**************13</number>
               <currencyBalance>-79.00</currencyBalance>
               <currencyFundsAvailable>1321.02</currencyFundsAvailable>
               <currencyName>PLN</currencyName>
               <owners>
                 <owner>
                   <name>Jan Kowalski</name>
                   <address>Kwiatowa 8/97 Warszawa  PL</address>
                   <kind>OWNER</kind>
                 </owner>
               </owners>
               <moneyTransactions>
                  <moneyTransaction>
                     <transactionOn>2019-10-02</transactionOn>
                     <bookedOn>2019-10-03</bookedOn>
                     <currencyAmount>-100.99</currencyAmount>
                     <currencyBalance>1000.00</currencyBalance>
                     <title>Transakcja kartą kredytową;obciążenie 4814 POL Poznan Doladowania.payu (efwu)</title>
                     <party>Doladowania.payu, POL Poznan Doladowania.payu</party>
                     <partyIban>PL63249010440000420034376084</partyIban>
                     <kind>ZAPŁATA KARTĄ</kind>
                     <status>DONE</status>
                     <variableSymbol>6789</variableSymbol>
                  </moneyTransaction>
                  <!-- ... more transactions ... -->
               <moneyTransactions>
            </creditCard>
       <!-- ... more credit cards ... -->
      </creditCards>
    </result>
  </command>
</reply>

After calling the endpoint, you will receive a command identifier in the id attribute of the <command> node. You need to save this ID to poll the Get Import Result endpoint.

Once the command finishes successfully, Get Import Result will contain a <result> node further split into sections: Owners, Accounts and Credit Cards with their respective fields inside.

Get Import Result

Returns information about the state of an importing command and provides its result in the case that it’s successful.

To be called repeatedly until you receive a final state: successful, error or fatal. When you get one of these, save the response in your system and stop calling the endpoint.

We recommend 2-5 second intervals for polling.

Request

Request

curl --get \
  --header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
  https://test.api.kontomatik.com/v1/command/000000.xml

GET /v1/command/{id}.xml

{id} is the command ID you received when setting up the importing command, e.g. Default Import.

This endpoint doesn’t require any parameters except for your API Key.

Response

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/command.xsd" status="202 Accepted">
  <command id="000000" state="setup" name="DefaultImportCommand">
    <progress><value>0</value></progress>
  </command>
</reply>

Example final result of a command

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/default_import.xsd" status="200 OK">
  <command id="000000" state="successful" name="DefaultImportCommand" target="Alior" institution="Alior">
    <progress><value>13</value></progress>
    <result>
      <owners>
        <owner>
          <name>Jan Kowalski</name>
          <address>Kwiatowa 8/97 Warszawa  PL</address>
          <phone>+48612***078</phone>
          <email>jankowalski@xgmail.com</email>
          <citizenship>PL</citizenship>
          <personalDocumentType>Identity document</personalDocumentType>
          <personalDocumentNumber>AAB123456</personalDocumentNumber>
          <birthDate>1984-01-18</birthDate>
          <kind>OWNER</kind>
        </owner>
        <!-- ... more owners ... -->
      </owners>
      <accounts>
        <account>
          <name>eKONTO</name>
          <iban>PL32114020040000320250132522</iban>
          <currencyBalance>1467.39</currencyBalance>
          <currencyFundsAvailable>1407.39</currencyFundsAvailable>
          <currencyName>PLN</currencyName>
          <activeSinceAtLeast>2000-02-28</activeSinceAtLeast>
          <moneyTransactions>
            <moneyTransaction>
              <transactionOn>2012-06-28</transactionOn>
              <bookedOn>2012-06-30</bookedOn>
              <currencyAmount>20.00</currencyAmount>
              <title>Return for beer in a pub</title>
              <party>Jan Kowalski</party>
              <partyIban>PL68249000050000400075212326</partyIban>
              <kind>EXTERNAL INCOMING TRANSFER</kind>
              <labels>
                <label><!-- label type --></label>
                <!-- ... more labels ... -->
              </labels>
            </moneyTransaction>
            <!-- ... more transactions ... -->
          </moneyTransactions>
          <owners>
            <owner>
              <name>Jan Kowalski</name>
              <address>Kwiatowa 8/97 Warszawa  PL</address>
              <kind>OWNER</kind>
            </owner>
            <owner>
              <name>Adam Nowak</name>
              <kind>CO_OWNER</kind>
            </owner>
          </owners>
        </account>
        <!-- ... more accounts ... -->
      </accounts>
      <!-- ... if target supports credit cards import -->
      <creditCards>
            <creditCard>
               <name>Karta Kredytowa W/Shell</name>
               <cardId>**************13</cardId>
               <iban>PL19025714369262645919804211</iban>
               <number>**************13</number>
               <currencyBalance>-79.00</currencyBalance>
               <currencyFundsAvailable>1321.02</currencyFundsAvailable>
               <currencyName>PLN</currencyName>
               <owners>
                 <owner>
                   <name>Jan Kowalski</name>
                   <address>Kwiatowa 8/97 Warszawa  PL</address>
                   <kind>OWNER</kind>
                 </owner>
               </owners>
               <moneyTransactions>
                  <moneyTransaction>
                     <transactionOn>2019-10-02</transactionOn>
                     <bookedOn>2019-10-03</bookedOn>
                     <currencyAmount>-100.99</currencyAmount>
                     <currencyBalance>1000.00</currencyBalance>
                     <title>Transakcja kartą kredytową;obciążenie 4814 POL Poznan Doladowania.payu (efwu)</title>
                     <party>Doladowania.payu, POL Poznan Doladowania.payu</party>
                     <partyIban>PL63249010440000420034376084</partyIban>
                     <kind>ZAPŁATA KARTĄ</kind>
                     <status>DONE</status>
                     <variableSymbol>6789</variableSymbol>
                  </moneyTransaction>
                  <!-- ... more transactions ... -->
               <moneyTransactions>
            </creditCard>
       <!-- ... more credit cards ... -->
      </creditCards>
    </result>
  </command>
</reply>

The <command> element is described by the following attributes:

Attribute Availability Description
id always ID of the command assigned by Kontomatik
name always Executed command name
state always State of the command, see: Command states
target when import is successful Name of the target
institution when import is successful Name of the institution

Once the command finishes successfully, it will also contain the <result> structure. For details of its contents, please consult the documentation regarding that particular command.

Command states

Consult the table below for an explanation of the values of different command states.

State Description
setup The command is currently in a queued state and awaiting the allocation of resources
in_progress The command is being executed
successful The command has finished successfully, and the response contains imported data
error Command execution failed due to a known scenario, see: Error Handling
fatal Command execution failed due to unexpected reasons, see: Error Handling

Reuse Multiple Access

Creates a new session for an existing multipleAccessId token. The session can be used to import the end-user’s data again (e.g. using the Default Import command).

Closes all existing sessions for that user if any are still active.

A new session can be created up to 4 times in a 24-hour period. Whenever a bank account is associated with many Multiple Access tokens, the limit is shared between all of those tokens.

Each new session is associated with the same ownerExternalId you’ve provided in the SignIn Widget when the token was created, which impacts Owner data aggregation.

Request

Request

curl \
  --header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
  --data "multipleAccessId=ffff....ffff" \
  https://test.api.kontomatik.com/v1/command/reuse-multiple-access.xml

POST /v1/command/reuse-multiple-access.xml

Required parameter:

Parameter Description
multipleAccessId Parameter returned by the SignIn Widget (after successful logging in) within the options object when the target was used in the Multiple Access mode

Response

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://developer.kontomatik.com/schema/v1/reuse_multiple_access.xsd" status="201 Created" user="multiple-access-user" ownerExternalId="123456">
   <session id="3868" signature="3be8d15144544faf3ecad099aa66468902a8a29515a8d72134d67b88c9b3ee52"/>
</reply>

The reply contains a <session> node with the following attributes:

Attribute Availability Description
id always ID of the session assigned by Kontomatik
signature always Signature assigned to the sessionId ensuring protection against enumeration attacks

The attributes are equivalent to sessionId and sessionIdSignature returned by the onSuccess callback in the SignIn Widget.

Revoke consent granted by the end-user for Multiple Access.

Consents are automatically deleted 180 days after creation or if the bank returns information that the consent is no longer valid when executing Reuse Multiple Access or Default Import.

Request

Request

curl \
  --header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
  --data "multipleAccessId=ffff....ffff" \
  https://test.api.kontomatik.com/v1/command/delete-multiple-access.xml

POST /v1/command/delete-multiple-access.xml

Response

204 No Content

Required parameter:

Parameter Description
multipleAccessId Parameter returned by the SignIn Widget (after successfully logging in) within the options object when the target was used in the Multiple Access mode

Testing (AIS)

In order to test Account Information Service you can use our mock bank - KontoBank. You can use the provided mock accounts to create a test session either manually or automatically.

Once you get the session information, you can perform any API action you would on a real session, but using the test API endpoints. Some features might be unavailable as per your contract.

Mock accounts don’t typically change, however Data Analysis features work in real time on the mock accounts. If any Machine Learning models change, the returned results for those endpoints might change as well.

KontoBank is available only in the test environment. If you want to perform tests on production and/or in real banks, you need to obtain real accounts by yourself.

Mock accounts

The full list of available mock accounts, divided by country, can be found in this document. However, the credentials are typically as follows:
Login test1, test2, … (as per the accounts list)
Password Test123
SMS OTP Test123
Country PL, ES, CZ, … (as per the accounts list)

Create a test session manually

To create a test session you can embed the SignIn Widget using your test client ID.

Then perform the login process using one of the two targets:

Both targets accept the credentials mentioned in the section above.

Create a test session automatically

For automated testing, you can create a session using the endpoint that will return necessary information to continue the flow with other API endpoints.

Request

Request

curl \
  --header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
  --data "login=test1" \
  --data "country=pl" \
  --data "ownerExternalId=END_USERS_OWNER_EXTERNAL_ID" \
  --data "multipleAccess=true" \
  --data "ownerEmail=END_USERS_EMAIL_ADDRESS" \
  https://test.api.kontomatik.com/v1/mock-session.xml

Response (example)


<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://developer.kontomatik.com/schema/v1/create_mock_session.xsd" status="201 Created" user="user-test" ownerExternalId="1234567890" responseTimestamp="2023-01-01T00:00:00Z" >
  <session id="000000000" signature="ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"/>
    <multipleAccessId>1a2b3c4d-a9bc-123a-a12b-1a2b9911c1d2</multipleAccessId>
  <credentialsMetadata></credentialsMetadata>
</reply>

POST /v1/mock-session.xml

Parameters:

Parameter Requirement Description
login obligatory Login as per the Mock accounts section
country obligatory Country code as per the Mock accounts section
ownerExternalId optional Identifier generated by you and used for Owner data aggregation
multipleAccess optional (true/false) Enables the Multiple Access mode
ownerEmail optional (required when using Multiple Access mode) Multiple Access mode requires providing the end-user's email address. Please use any email you have available for testing purposes.

Response

The reply contains a <session> node with the following attributes:

Attribute Availability Description
id always ID of the session assigned by Kontomatik
signature always Signature assigned to the sessionId ensuring protection against enumeration attacks

When using the Multiple Access mode, you’ll also receive a <multipleAccessId> node containing the ID of the Multiple Access token.

Auto import (zero-integration)

<!DOCTYPE html>
<html>
<head>
  <script src="https://signin.kontomatik.com/assets/signin-widget.js">
  </script>
</head>
<body>
  <div id="kontomatik"></div>

  <script>
    embedKontomatik({
      client: 'YOUR_CLIENT_ID', // TODO: replace with your client id
      divId: 'kontomatik',
      onSuccess: function() {
        /*
          End user successfully signed in to the bank.
          Kontomatik started importing data in the background.
          It will take from a few seconds to a few minutes.
          To simplify things we assume everything will go well with the data import.
          Lets show the finishing message to the user already!
        */
        // TODO: customize it to your needs
        let kontomatikDiv = document.getElementById("kontomatik");
        kontomatikDiv.innerHTML = "Thank you! We will review your application and get back to you shortly.";
      },
      autoImport: {
        sinceMonths: 3
      }      
    });
  </script>
</body>
</html>

Auto import is disabled by default. Please contact our support team to enable this feature.

Kontomatik allows you to import data without actually having to call our API endpoints.

If you use the autoImport setting with the sinceMonths parameter in our SignIn Widget, we will start the import automatically. Once it’s done you’ll be able to see the owner information in Insight.

Please see the example on the right. Copy it and change:

We also recommend modifying the onSuccess function, but if you’re happy with how it works, you can just leave it like it is.

You’re more than welcome to also change other Widget options (like the default Widget language), handle errors and add custom styling.

PDF Statements Parsing

Introduction

PDF Parsing allows you to upload end-user’s bank statements and receive extracted data in a processing-friendly version.

You can use this feature in different ways:

Before data can be extracted, the documents will go through tampering verification. The process is based on simple heuristics and whitelists, but if anything suggests a potential modification of the document, no data will be returned. Instead, the API or the PDF Widget will return an error.

Please note that documents can be flagged as modified even though the user didn’t actually change anything on purpose. The verification also doesn’t guarantee that the document is authentic.

Inconsistent statements

Some statements, typically Account History, are inconsistent (Inconsistent type) by default: they lack balances after transactions, can be filtered out or are missing some other information.

Those types of statements will be rejected.

By default, parsing of inconsistent statements within the PDF Widget or Insight is not supported. However, you can reach out to us to enable parsing for these types of statements.

If you are parsing via API, you have the option to include the acceptInconsistent flag, which permits the processing of these documents even if they contain inconsistencies.

This flag doesn’t disable checks that are possible in these Inconsistent type statements nor does it omit consistency checks for other documents.

When a statement gets parsed, the isConsistent flag will tell you if the document was of the Inconsistent type or not.

Parse statement

Returns data from the PDF statement or an error when the uploaded file is not a valid PDF document or seems to have been modified.

The command takes only one document at the time.

Request

Request with PDF as binary

curl \
  -H "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
  -F "pdf=@file.pdf" \
https://test.api.kontomatik.com/v1/statement.xml

Request with PDF as Base64

curl \
  -H "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
  -F "pdfAsBase64=<YOUR_BASE64_ENCODED_PDF_FILE" \
https://test.api.kontomatik.com/v1/statement.xml

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/statement.xsd" status="200 OK">
  <result>
    <statement id="12323423" isConsistent="true">
      <owners>
        <owner>
          <name>Jan Kowalski</name>
          <address>Krótka 8, Wąchock</address>
          <polishNip>1258882345</polishNip>
          <kind>OWNER</kind>
        </owner>
        <!-- ... more owners ... -->
      </owners>
      <period>
        <startOn>2014-01-01</startOn>
        <endOn>2014-01-31</endOn>
      </period>
      <type>MONTHLY_STATEMENT</type>
      <target name="MBank">
        <accounts>
          <account>
            <name>eKONTO</name>
            <iban>PL32114020040000320250132522</iban>
            <owners>
              <owner>
                <name>Jan Kowalski</name>
                <address>Krótka 8, Wąchock</address>
                <kind>OWNER</kind>
              </owner>
              <!-- ... more owners ... -->
            </owners>
            <activeSinceAtLeast>2014-11-12</activeSinceAtLeast>
            <currencyBalance>1467.39</currencyBalance>
            <currencyName>PLN</currencyName>
            <moneyTransactions>
              <moneyTransaction>
                <transactionOn>2012-06-28</transactionOn>
                <bookedOn>2012-06-30</bookekOn>
                <currencyAmount>20.00</currencyAmount>
                <currencyBalance>1264.21</currencyBalance>
                <title>I return money for a beer</title>
                <party>Mark Brown</party>
                <partyIban>PL68249000050000400075212326</partyIban>
                <kind>OUTGOING EXTERNAL TRANSFER</kind>
              </moneyTransaction>
              <!-- ... more transactions ... -->
            </moneyTransactions>
          </account>
          <!-- ... more accounts ... -->
        </accounts>
      </target>
    </statement>
  </result>
</reply>

POST /v1/statement.xml

Parameters:

Parameter Requirement Description
pdf optional* PDF file (in binary)
pdfAsBase64 optional* PDF file encoded as Base64
ownerExternalId optional Identifier generated by you and used for Owner data aggregation
acceptInconsistent optional Pass true to accept Inconsistent statements, false by default

*You must provide one of them in your request. The binary form is recommended. Sending both pdf and pdfAsBase64 or neither will result in an error.

Response

Unless the document returned an error, within the <reply> element, you will find the <statement> node with the following elements:

Node Availability Description
id always ID of the document assigned by Kontomatik
isConsistent always true/false, consistency type of the document assigned as per the Inconsistent statements section
owners always See: Owners section
period always See: PDF Period section
target always See: PDF Target section

PDF Period section

The <period> element specifies the date range of the imported document as read from the statement. It contains the following fields:

Node Availability Description
startOn always Start date
endOn always End date

PDF Target section

The <target> element wraps the Accounts section and provides the target name in the name attribute.

Failed verifications

Response

<reply status="400 Bad Request">
    <exception name="InvalidStatementMetadata">
        <message>Metadata does not match any known template</message>
        <statementId>500124229</statementId>
        <failedVerifications>
            <verification>
                <kind>InvalidStatementMetadata</kind>
                <description>Metadata does not match any known template</description>
            </verification>
            <verification>
                <kind>InvalidStatementMetadata</kind>
                <description>Dates are inconsistent ModificationDates{documentInfoCreateDate=2020-11-04T12:50:14+01:00, documentInfoModificationDate=2024-05-13T12:04:37+02:00, xmpCreateDate=null, xmpModificationDate=null}</description>
            </verification>
            <verification>
                <kind>InvalidStatementFonts</kind>
                <description>Invalid fonts: [PdfFont[size=11, font=NOTGDE+ArialMT, color=RGB 0.9098 0.90196 0.8902]]</description>
            </verification>
            <verification>
                <kind>InvalidStatementConsistency</kind>
                <description>Account history is supported only if flag acceptInconsistent is set to true</description>
            </verification>
        </failedVerifications>
    </exception>
</reply>

If there is a modification indicator detected, the response will contain <failedVerifications> node which contains a list of all detected inconsistencies.

Each inconsistency is presented within a <verification> structure, which includes the following fields:

node description
kind Name of the error, see error list
description Provides details of the inconsistency.

It's important to note that the first detected inconsistency is also available outside the <failedVerifications> node, as the main exception in the <exception> tag.

Get uploaded documents

Allows you to get a list of parsed documents for a given owner. Each document can be downloaded using the provided link.

The list and the documents are stored for up to 7 days from the date of parsing.

Request the list

Request

curl \
-H "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
https://test.api.kontomatik.com/v1/documents.xml?ownerExternalId=example_id_123

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://developer.kontomatik.com/schema/v1/get_documents.xsd" status="200 OK" user="demo-test" ownerExternalId="example_id_123" responseTimestamp="2023-10-02T08:05:55Z">
   <documents>
      <document>
         <state>SUCCESSFUL</state>
         <parsingDate>2023-10-02</parsingDate>
         <fileUrl>https://test.api.kontomatik.com/v1/document-file?documentId=12341234</fileUrl>
      </document>
   </documents>
</reply>

GET /v1/documents.xml

Parameters:

Parameter Requirement Description
ownerExternalId optional Identifier generated by you and used for Owner data aggregation

Documents list response

List of the parsed documents is contained in the <documents> node. Each document within a <document> node has the following fields:

Node Availability Description
state always SUCCESSFUL or ERROR depending on the result of parsing
parsingDate always Date of the file's parsing request
fileUrl always URL to the file with the document

It’s possible that there will be no <document> elements in some cases, e.g.:

Request a file

Request

curl \
-H "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
https://test.api.kontomatik.com/v1/document-file.xml?documentId=23546697

To download a document, send a GET request to the provided URL in the fileUrl field.

File response

The response will contain the requested file as a body along with the following headers:

Header Description
Content-Disposition E.g. Content-Disposition: attachment; filename="23546697-2a1d878a9cef.pdf"
Filename is a String of maximum 36 characters plus file extension length.
Content-Length Size of the entity-body in bytes
Content-Type Type of the downloaded file

PDF Widget

The Kontomatik PDF Widget is an HTML5 iframe element that you embed on your website by calling our JavaScript.

The PDF Widget voids the need to create your own frontend for accepting documents — it validates and parses them right away. When the documents are uploaded and processed, you will find the extracted data in Insight.

If you need XML data from the documents parsed via our Widget, you have to use the Aggregated Data endpoint.

Jump to section:

Embedding the PDF widget

<!-- index.html / head -->
<script src="https://signin.kontomatik.com/assets/statement-widget.js">
</script>

<!-- index.html / body -->
<div id="kontomatik" />

// index.js
embedKontomatikPdf({
  client: 'YOUR_CLIENT_ID',    // replace it with your assigned client id
  divId: 'kontomatik',         // must match the div element id
  since: '2018-01-01',
  ownerExternalId: 'owner_id',
  onFinished: function({ target, periods, count }) {
    // End-user finished uploading the PDFs
    alert('It works!');
  }
});

To embed the widget on your web page:

1. Reference the widget's JavaScript library.

2. Add an empty <div> element where you want your widget to be rendered. You need to specify the ID of that element.

3. Call the embedKontomatikPdf() JS function, specifying the required parameters.

See the provided code examples.

PDF Widget parameters

Required parameters (PDF)

Parameter Description
client Your client ID, as per API credentials. Make sure to use the right ID for each environment.
divId ID of the div element where the Widget should be rendered. Make sure this element already exists before calling the embedKontomatikPdf() function.
ownerExternalId Identifier generated by you and used for Owner data aggregation
since Start date in the YYYY-MM-DD format. The end-user will be asked to provide PDF statements which cover the period since this date until present day.
Be aware that this parameter cannot be set to a date more than 5 years before the current date.
onFinished Callback function triggered when the documents have been parsed. See: onFinished callback.

Other parameters (PDF)

Parameter Default Description
locale en Determines the Widget interface language. Accepted values: cz, en, es, et, it, lt, lv, pl, pt, ro, ru.
target null (not recommended) Pre-selects the end-user’s bank. See: Own list for bank selection
showBetaQualityLabels true/false For targets in the beta stage the option will show a “beta” label next to the bank name.Default is true in the test environment, false in production.
showTargetMissingOption true Shows an additional option for users to suggest a new bank not available in the Widget
showTargetMissingForm true When set to false, you can show the user your own suggestion form for a new target, see: onUnsupportedTarget callback
styling null See: Styling the PDF Widget
coverageThreshold 0.8 Desired coverage ratio (from 0 to 1) of the periods in the parsed statements compared to the requested time (from since till now). Not meeting the coverage doesn’t stop the process, but a warning will be shown.
disableTargetChangeAfterUpload false Disables the option to change the selected target after the first successfully uploaded document

PDF Widget callbacks

PDF Widget provides a set of callbacks, which are invoked when the Widget enters a new state or an important event takes place.

Only onFinished callback is required to implement. All other callbacks are optional.

The following figure presents a visual reference for the callbacks and the Widget's transition between stages:

PDF onFinished callback

Called when files have been successfully parsed. The parameters below will be sent to this callback:

Parameter Description
target Technical identifier of the bank the document originates from
periods List of periods covered by the uploaded PDF statements in the format: [{ startOn: 'YYYY-MM-DD', endOn: 'YYYY-MM-DD' }, { startOn: 'YYYY-MM-DD', endOn: 'YYYY-MM-DD' }, …]
count Number of PDF files sent

PDF onError callback

Called when any error occurs. The parameters below will be sent to this callback:

Parameter Description
exception Name of the exception, see: Error handling
options Extra parameters, see the table below

The options object contains the following:

Parameter Description
target Technical identifier of the bank the document originates from
officialName Full bank name

PDF onUnsupportedTarget callback

The callback is triggered when showTargetMissingOption is set to true and:

The parameters below will be sent to this callback:

Parameter Description
target The name of the bank provided by the user
country Country code
address Bank website URL provided by the user

PDF onInitialized callback

Called when the Widget is loaded and ready for user interaction. Will be fired once in the Widget’s life cycle.

PDF onStarted callback

Called each time the bank selection list is shown to the user.

PDF onTargetSelected callback

Called when the user has selected a bank. The parameters below will be sent to this callback:

Parameter Description
name Technical identifier of the selected bank
officialName Full bank name

Reloading the PDF Widget

If you dynamically reload the PDF Widget on the frontend, the already registered callbacks will be attached to the previously created session and cause errors when trying to use the new instance of the Widget.

In order to manage this, please use the removeKontomatikPdf() function before calling for embedKontomatikPdf() again.

Styling the PDF Widget

Example

embedKontomatikPdf({
  /*
  ... (see Embedding the widget for the full reference) ...
  */
  styling: {
    "bgColor": "#252C38",
    "textColor": "#CECECE",
    "borderColor": "#656F86",
    "primaryColor": "#7CCDEE",
    "secondaryColor": "#FFFFFF",
    "mainHoverColor": "#395572",
    "listHoverColor": "#3F4A5B",
    "disabledColor": "#CED4DA",
    "errorColor": "#FF5454"
  }
});

Using CSS overrides or any other external modifications of the Widget are strictly forbidden. You can, however, use the styling setting of the Widget to adjust some properties - just add the styling node inside of your embedKontomatikPdf() function.

When using the setting, you don’t need to use all properties inside - just the ones you want to change compared to the default version.

Example on the right depicts a proposal for a dark mode.

Color properties accept only HEX (#FFF) and RGB (rgb(12, 32, 111)) notations.

Size properties accept all standard CSS units for size: px, em, rem etc.

The styling node contains the following fields:

Key Default Description
bgColor #FFF Background of the elements: Widget body, lists, inputs
textColor #000 All standard texts, including texts inside inputs and lists
borderColor #E5E5E5 Border of elements: list containers, tiles, inputs
primaryColor #2E3F5B Headings, input names, primary buttons background, links, tags, other elements meant to stand out, inputs active/focused border
primaryReverseColor #FFF Text color for primary buttons
secondaryColor #586374 Secondary button text (no background), other elements meant to stand out less than primary
mainHoverColor #7CCDEE Background color for hovered primary buttons, text color for hovered secondary buttons, hovered links color
mainHoverReverseColor #FFF Text color for hovered primary buttons
listHoverColor #F5F5F5 Background color for hovered list items, meant to be subtle and contrast well with textColor and primaryColor
disabledColor #CED4DA Text color for disabled inputs and list items
errorColor #BB0000 Error text color, inputs validation
borderRadius 25px Border radius for primary buttons and inputs

Testing (PDF)

To test the PDF Parsing service, you can:

Both options work via API and PDF Widget.

KontoBank statements

To generate a fake statement:

  1. Go to https://bank.kontomatik.com/pdf/

  2. Choose one of the available mock accounts

  3. Choose document type:

    a. monthly statement - spans over one month only for just one account

    b. account history - can include multiple accounts within a custom date range

  4. Select dates for which the statement will be generated

  5. (optional) Add errors to test negative scenarios

  6. Click “Generate PDF” and then save the file

PDF Confirmations Parsing

Our API allows you to extract data from transaction confirmations generated as PDFs, providing you with essential information such as transaction status, amount, currency, sender, recipient, and more.

Before data can be extracted, the documents will go through tampering verification. The process is based on simple heuristics and whitelists, but if anything suggests a potential modification, the API will return an error.

Parse Transaction Confirmations

Request

curl -H "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
     -F "pdf=@file.pdf"
     https://test.api.kontomatik.com/v1/parse-pdf/confirmation

POST /v1/parse-pdf/confirmation

Parameters:

Parameter Requirement Description
pdf obligatory PDF file (in binary)

Response

{
  "requestId":"3cce426d-2d3d-11b2-9f5e-9325dba2fd4e",
  "content":{
    "status":"BOOKED",
    "target": {
      "name": "Pko",
      "institution": "Pko",
      "officialName": "PKO Bank Polski"
    }
    "generatedBy":"RECIPIENT",
    "transactionOn":"2023-07-04",
    "bookedOn":"2023-07-04",
    "currencyAmount":3700.00,
    "currencyName":"PLN",
    "title":"Wynagr. z tyt. um. zlec. 001289",
    "sender":{
      "details":[
        {
          "name":"SKLEP SPOŻYWCZY SŁAWOMIR KIELICH SPÓŁKA JAWNA"
        }
      ],
      "iban":"PL46132019990000061081356879"
    },
    "recipient":{
      "details":[
        {
          "name":"Gniewomir Bąk",
          "address":"SŁOWIAŃSKA 2 M.28 46-398, RADOM"
        }
      ],
      "iban":"PL70154024288185594510903422"
    },
    "kind":"Przelew z rachunku",
    "analytics":{
      "labels":[
        {
          "name":"salary"
        }
      ]
    }
  }
}

Main response structure

The response is a JSON object with the following structure:

Node Type Description
requestId String ID of the transaction confirmation request for debugging purposes.
content Object Transaction Confirmation Object. The key is missing when any exceptions occur.
exception Object JSON Error Response. The key is missing when no exception occurs. Might contain a Tamper Report object inside.

Transaction Objects

Transaction Confirmation object

Node Type Description
status String Determines the status of the transaction, possible values: BOOKED, UNBOOKED, UNKNOWN.
target Object Information about the technical identifiers of the bank the document originates from. For more information please refer to the Target Information Object.
generatedBy String Determines who generated the document, possible values: SENDER, RECIPIENT, UNKNOWN.
transactionOn String Date of the operation
bookedOn String Booking date of the operation
currencyAmount Number Amount of the transaction, it always has a positive value.
currencyName String Currency of the transaction
title String Title of the transaction
sender Object Information about the transaction's sender, possible data: name, address, iban. For more information please refer to the Transaction Party Object.
recipient Object Information about the recipient of the transaction, possible data: name, address, iban. For more information please refer to the Transaction Party Object.
kind String Transaction kind/type
analytics (optional) Object Analytical section containing labeling. For more information please refer to the Analytics Object
tamperReport (optional) Object Returned when Force parsing is used and any potential modification was detected

Target Information Object

Example

"target": {
  "name": "MBankApi",
  "institution": "MBank",
  "officialName": "mBank"
}

Returns information about the target a given transaction comes from.

Node Type Description
name String Name of the target
institution String Name of the target
officialName String Official name of the bank

Transaction Party Object


{
   "requestId":"3cce426d-2d3d-11b2-9f5e-9325dba2fd4e",
   "content":{
      ...
      "sender":{
        "details":[
            {
                "name":"SKLEP SPOŻYWCZY SŁAWOMIR KIELICH SPÓŁKA JAWNA"
            }
          ],
            "iban":"PL46132019990000061081356879"
        },
      "recipient":{
    "details":[
    {
     "name":"Gniewomir Bąk",
         "address":"SŁOWIAŃSKA 2 M.28 46-398, RADOM"
     }
    ],
         "iban":"PL70154024288185594510903422"
      },
      ...
   }

The Transaction Confirmations parser extracts data based on the information present in the confirmation both about the sender and recipient. These statements may contain various fields depending on the information provided by the bank.

Below you will find information about which fields can appear inside the sender and recipient objects:

Node Type Description
details List List containing object(s) with the details of each sender/recipient appears in the transaction.
iban String Account number

details Object

Contains details of each sender or recipient of the transfer.

Node Type Description
name String Full name or company name
address String Adress

Analytics Object

{
    "requestId": "3cce426d-2d3d-11b2-9f5e-9325dba2fd4e",
    "content": {
    ...
    "analytics":{
         "labels":[
            {
               "name":"internal"
            }
         ]
      }
    }
}


{
    "requestId": "3cce426d-2d3d-11b2-9f5e-9325dba2fd4e",
    "content": {
    ...
    "analytics":{
         "labels":[
            {
               "name":"internet and tv",
          "vendors": [
                 "Vectra"
                  ]

            }
         ]

      }
    }
}

This object contains Labeling or Vendors Recognition results depending on you contract.

Inside the analytics object there is a labels structure containing a list of Objects, a single one representing a label with the following fields:

Node Type Description
name String Name of the label. For a list of all available labels please refer to the Labeling section
vendors (optional) List Information about parties/companies involved in a transaction, for more information please refer to the Vendors Recognition section

Tamper Report

{
   "requestId":"3a5db04b-2d40-11b2-8aa1-355b864aa12e",
   "exception":{
      "name":"PotentiallyModified",
      "message":"Cannot parse tampered transaction confirmation",
      "tamperReport":[
         {
            "name":"InvalidStatementMetadata",
            "message":"Metadata does not match any known template"
         },
         {
            "name":"InvalidStatementFonts",
            "message":"Invalid fonts: [PdfFont{size=6, font='CAAAAA+ArialUnicodeMS', color='RGB 0.0 0.0 0.0'}, PdfFont{size=11, font='BAAAAA+Arial-Black', color='RGB 0.0 0.0 0.0'}, PdfFont{size=9, font='CAAAAA+ArialUnicodeMS', color='RGB 0.0 0.0 0.0'}, PdfFont{size=9, font='BAAAAA+Arial-Black', color='RGB 0.0 0.0 0.0'}]"
         },
         {
            "name":"InvalidStatementLogo",
            "message":"Invalid graphics in document [027e88bd12de6fde9563bba6cdd4370c78b8e828]"
         }
      ]
   }
}

The Tamper Report is a list of possible document modification indicators discovered during the parsing of a provided confirmation. These indicators suggest a potential tampering attempt from the end-user.

The Tamper Report can take one of two forms:

Below, you will find details about the elements in the form of objects that can appear within the Tamper Report list:

Node Type Description
name String Name of the modification indicator, see the Errors list
message String A more detailed description of the modification indicator.

Force parsing

This feature was designed for customers who want to assess the risks associated with accepting a parsed document that may have been altered by the user.

By default, if Kontomatik detects any modification indicators, the document is declined, and the API returns an error. However, when force parsing is employed and the document is successfully parsed, the data is still provided along with a Tamper Report Object outlining the encountered problems. In case the document cannot be parsed, tamperReport will also be provided, regardless of the use of force parsing.

Request

curl -H "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
     -F "pdf=@file.pdf" 
     https://test.api.kontomatik.com/v1/parse-pdf/confirmation-trusted

  {
    "requestId": "3cce426d-2d3d-11b2-9f5e-9325dba2fd4e",
    "content": {
      ...
      "tamperReport": [
        {
          "name": "UnrecognizedStatementLayout",
          "message": "Document does not contain all of required keywords"
        },
    {
     "name":"InvalidStatementLogo",
     "message":"Invalid graphics in document [027e88bd12de6fde9563bba6cdd4370c78b8e828]"
    }
      ]
    }
  }

POST /v1/parse-pdf/confirmation-trusted

Parameters:

Parameter Requirement Description
pdf obligatory PDF file (in binary)

Testing

To test the PDF Confirmations Parsing feature, you can generate a mock confirmation from the fake KontoBank accounts and parse it on the test environment.

Follow these steps to create a fake statement:

  1. Go to https://bank.kontomatik.com/pdf/

  2. Pick one of the mock accounts provided

  3. Choose transaction_confirmation as the document type

  4. Choose a specific transaction

  5. (optional) Add errors to simulate negative scenarios and/or determine the transaction's status (booked/unbooked/unknown)

  6. Click “Generate PDF” and then save the file

Owner Upload

Owner Upload allows you to send your own owner and transactional data to Kontomatik servers so they can be further used for data analysis and other API features.

This service is not available by default and requires a signed contract. Please contact Sales for details.

Request

Request

curl \
    -H "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
    -H "Content-Type: application/json" \
    -d @data.json \
    https://test.api.kontomatik.com/v1/owner

POST /v1/owner

Owner Upload Payload

Example data.json file content

{
  "ownerExternalId": "3r43r43fef4f54",
  "country": "pl",
  "accounts": [
    {
      "iban": "PL78001230020000432532412340",
      "currencyName": "USD",
      "ownerNames": [
        "Jozin Zbazin"
      ],
      "transactions": [
        {
          "currencyAmount": -15.43,
          "currencyBalance": 1200.00,
          "transactionOn": "2018-02-15",
          "bookedOn": "2018-02-15",
          "kind": "Płatność kartą",
          "party": "Sklep Żabka",
          "title": "Zakupy na kwotę 15.43",
          "partyIban": "PL26003043020000012412312313"
        },
        {
          "currencyAmount": 100.00,
          "currencyBalance": 643.50,
          "transactionOn": "2018-02-16",
          "bookedOn": "2018-02-16",
          "kind": "Wpłata ATM",
          "party": "Jan Kowalski",
          "title": "Wpłata 100.00 PLN z dnia 16-02-2018",
          "partyIban": "PL61109010140000071219812874"
        }
      ]
    }
  ],
  "creditCards": [
    {
      "currencyName": "PLN",
      "iban": "PL92109025900000000142961694",
      "ownerNames": [
        "Jozin Zbazin",
        "Karlova Vara"
      ],
      "transactions": [
        {
          "currencyAmount": -15.43,
          "currencyBalance": 1200.00,
          "transactionOn": "2018-02-15",
          "bookedOn": "2018-02-15",
          "kind": "Płatność kartą",
          "party": "Sklep Żabka",
          "title": "Zakupy na kwotę 15.43",
          "partyIban": "PL26003043020000012412312313"
        },
        {
          "currencyAmount": 100.00,
          "currencyBalance": 643.50,
          "transactionOn": "2018-02-15",
          "bookedOn": "2018-02-16",
          "kind": "Wpłata ATM",
          "party": "Jan Kowalski",
          "title": "Wpłata 100.00 PLN z dnia 16-02-2018",
          "partyIban": "PL61109010140000071219812874"
        }
      ]
    }
  ]
}

Data sent to the endpoint should contain the following:

Field Requirement Description Example value
ownerExternalId obligatory Identifier generated by you and used for Owner data aggregation “3r43r43fef4f54”
country obligatory Country code. Accepted values: cz, ee, es, it, lt, lv, pl, pt, ro. "es"
accounts optional See: Owner Upload Accounts List [<account1>, <account2>, …]
creditCards optional See: Owner Upload Accounts List [<card1>, <card2>, …]

Owner Upload Accounts List

A list containing Objects describing accounts or credit cards with the following fields:

Field Requirement Description Example value
currencyName obligatory Currency code "PLN"
iban obligatory Account number “PL92109025900000000142961694”
ownerNames obligatory Names of the owners of this account or the credit card ["Jan Kowalski", "Janina Kowalska"]
transactions obligatory See: Owner Upload Transactions List [<transaction1>, <transaction2>, …]

Owner Upload Transactions

A list containing Objects describing transactions with the following fields:

Field Requirement Description Example value
currencyAmount obligatory Amount of the transaction -15.43
currencyBalance obligatory Account balance after the transaction 1200.00
transactionOn obligatory Date of the operation “2018-02-15”
bookedOn obligatory Booking date of the operation “2018-02-16”
party optional The other party in the transaction “Sklep Żabka”
partyIban optional IBAN of the other party “PL26003043020000012412312313”
title optional Title of the transaction "Zakupy na kwotę 15.43"
kind optional Transaction kind/type "Płatność kartą"

Response

Response

{
  "requestId":"b1a7eb21-be0c-4805-bb4e-6c93e61ac0d8"
}

If the posted content is parsed successfully, you’ll receive a JSON object with the following field:

Node Availability Description
requestId when input processed successfully ID of the request

In case of an error, please consult the JSON errors section.

Data processing

All features in this section are available by default when using Account Information Service, PDF Statements Parsing or Owner Upload.

Get aggregated data

Returns data from all possible sources for a given owner.

The command doesn’t import anything or update the data, it simply extracts what has already been downloaded onto the Kontomatik servers before.

Request

Request

curl --get \
 --header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
 --data "ownerExternalId=END_USERS_OWNER_EXTERNAL_ID" \
  https://test.api.kontomatik.com/v1/data.xml

GET /v1/data.xml

Query parameters:

Parameter Requirement Description
ownerExternalId obligatory Identifier generated by you and used for Owner data aggregation
only optional Filters the response to one of the Owner Data Model sections.
Accepted values: owners, accounts, transactions, creditcards

Response

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/get_data.xsd" status="200 OK">  <owner externalId="653643">
    <target name="MBank" officialName="mBank" institution="MBank">
      <owners>
        <owner>
          <name>Jan Kowalski</name>
          <address>Kwiatowa 8/97 Warszawa  PL</address>
          <phone>+48612***078</phone>
          <email>jankowalski@xgmail.com</email>
          <citizenship>PL</citizenship>
          <nationality>polska</nationality>
          <personalDocumentType>Identity document</personalDocumentType>
          <personalDocumentNumber>AAB123456</personalDocumentNumber>
          <birthDate>1984-01-18</birthDate>
          <birthPlace>Warsaw</birthPlace>
          <kind>OWNER</kind>
        </owner>
        <!-- ... more owners ... -->
      </owners>
      <accounts>
        <account>
          <name>eKONTO</name>
          <iban>PL32114020040000320250132522</iban>
          <currencyBalance>1467.39</currencyBalance>
          <currencyFundsAvailable>1407.39</currencyFundsAvailable>
          <currencyName>PLN</currencyName>
          <activeSinceAtLeast>2000-02-28</activeSinceAtLeast>
          <owners>
            <owner>
              <name>Jan Kowalski</name>
              <address>Kwiatowa 8/97 Warszawa  PL</address>
              <kind>OWNER</kind>
            </owner>
          </owners>
          <owners>
            <owner>
              <name>Adam Nowak</name>
              <address>Robocza 1 M.14 Warszawa PL</address>
              <kind>CO-OWNER</kind>
            </owner>
          </owners>
          <moneyTransactions>
            <moneyTransaction>
              <transactionOn>2012-06-28</transactionOn>
              <bookedOn>2012-06-30</bookedOn>
              <currencyAmount>20.00</currencyAmount>
              <currencyBalance>443.00</currencyBalance>
              <title>Return for beer in a pub</title>
              <party>Jan Kowalski</party>
              <partyIban>PL68249000050000400075212326</partyIban>
              <kind>EXTERNAL INCOMING TRANSFER</kind>
                <labels>
                  <label><!-- label type --></label>
                  <!-- ... more labels ... -->
                </labels>
            </moneyTransaction>
            <!-- ... more transactions ... -->
          </moneyTransactions>
        </account>
        <!-- ... more accounts ... -->
      </accounts>
      <creditCards>
        <creditCard>
            <name>Lux Credit MasterCard</name>
            <cardId>5390********6217</cardId>
            <iban>PL09807410131232175240357841</iban>
            <number>5390********6217</number>
            <currencyBalance>-213.59</currencyBalance>
            <currencyFundsAvailable>783.370</currencyFundsAvailable>
            <currencyName>PLN</currencyName>
            <owner>Jan Kowalski</owner>
             <limit>1000.00</limit>
            <interest>15.20</interest>
            <dueDate>2014-06-01</dueDate>
            <moneyTransactions>
                <moneyTransaction>
                    <transactionOn>2020-12-05</transactionOn>
                    <bookedOn>2020-12-06</bookedOn>
                    <currencyAmount>-100.99</currencyAmount>
                    <currencyBalance>1000.00</currencyBalance>
                    <title>Credit Card Transaction 4814 POL Warsaw payu (R4nD)</title>
                    <party>Payu, POL Warszawa payu</party>
                    <partyIban>PL76103011623052268948576932</partyIban>
                    <kind>Credit Card transaction</kind>
                    <status>DONE</status>
                    <variableSymbol>6789</variableSymbol>
                    <labels>
                      <label><!-- label type --></label>
                      <!-- ... more labels ... -->
                    </labels>
                </moneyTransaction>
                <!-- ... more transactions ... -->
            <moneyTransactions>
            <owners>
                <owner>
                <name>Jan Kowalski</name>
                <address>Kwiatowa 8/97 Warszawa  PL</address>
                </owner>
            </owners>
        </creditCard>
        <!-- ... more credit cards ... -->
      </creditCards>
    </target>
  </owner>
</reply>

<!-- Partial responses will include this attribute! -->
<account partialDueToTimeout="true">
<!-- account details -->
</account>

The response is held in the <reply> element. Inside there might be multiple <target> elements representing multiple data sources. Each has a name attribute (target/parser technical name) and contains Owner, Account and Credit Card sections.

Delete Data

All data associated with one ownerExternalId is automatically removed from Kontomatik servers after 24 hours (or more, up to 14 days depending on your contract).

The time is counted from the moment the first batch of data appeared (e.g. first import performed for a given ownerExternalId).

If you want to remove the data sooner, you can use the following method.

Request

Request

curl -X DELETE \
 --header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
 --data "ownerExternalId=222222" \
https://test.api.kontomatik.com/v1/owner.xml

Response

<reply status="200 OK">
</reply>

DELETE /v1/owner.xml

Parameters:

Parameter Requirement Description
ownerExternalId obligatory Identifier generated by you and used for Owner data aggregation

Data Analysis

Introduction

Our Data Analysis features provide tools that help you assess your clients without having to create all calculation algorithms by yourself.

All Data Analysis endpoints work on the aggregated owner data.

Each feature requires a signed contract separately. Please contact Sales for details.

For billing purposes, for a single owner identified by ownerExternalId and the scope of imported data at the moment of using a specific feature, all requests to that feature’s endpoints are treated as one event.

Labeling

<moneyTransactions>
  <moneyTransaction>
    <!-- ...transaction details... -->
    <labels>
      <label>monthly</label>
      <label>repayment</label>
    </labels>
  </moneyTransaction>
  <moneyTransaction>
    <!-- ...transaction details... -->
    <labels>
      <label>healthcare</label>
    </labels>
  </moneyTransaction>
  <moneyTransaction>
    <!-- ...transaction details... -->
    <labels>
      <label>gambling</label>
    </labels>
  </moneyTransaction>
  <moneyTransaction>
    <!-- ...transaction details... -->
    <labels>
      <label>loan</label>
    </labels>
  </moneyTransaction>
  <!-- ... more transactions ... -->
</moneyTransactions>

The Labeling service provides labels assigned to transactions that help describe them for further analysis, grouping and aggregation.

In case a transaction is eligible for labels and the service is enabled on your account, the <moneyTransaction> node in the Account section will contain an additional <labels> structure with each label provided in a <label> element. Each transaction can receive 0, 1 or more labels.

Below you’ll find the complete list of available labels.

Technical

Label Direction Description
bank both transactions to and from banks, currently only available in Poland, can be assigned only when verification, loan or repayment label is also assigned
card payment expense payments made with the use of a payment card, only for Poland
internal both transactions between person's own accounts (self-to-self) or within the immediate family (same surname)
loan company both transactions to and from non-bank lending companies, currently only available in Poland, can be assigned only when verification, loan or repayment label is also assigned
monthly both transactions that occur monthly around the same date, have similar title and amount and the same party (sender or recipient)
overdraft expense user has withdrawn more money than the account holds
overdraft recovery income transactions that helped to have the non-negative account balance again
payment processor both payment typically involving online card payment or a payment processor like PayPal, PayU, DotPay, Allegro, DialCom24 etc.
return income money returned because of overpayment (e.g. tax returns) or consumer goods returned at the store, incoming return payments are also described with labels indicating the type of the original transactions, e.g. repayment, tax or apparel, even though these labels are intended mainly for expense transactions
savings both safe investments (e.g. term deposits, voluntary retirement savings), also (positive) interest from savings
verification both transactions which serve to prove user's identity or account ownership, typically with a very small nominal amount like 1 EUR or 0.01 EUR; often combined with return

Compensation

Label Direction Description
compensation income widely understood compensation, including all cases where individual receives money from a company, such as on the basis of a B2B contract; compensation is more general than salary
extra pay income transfer of money from a company to an individual which is more than a regular salary, such as overtime payments, discretionary bonuses, reimbursements for work travel expenses etc.
pension income payments of retirement money or pension received from the state
regular wage income recurring revenue coming regularly from the same account and having amount high enough to consider transaction as wage payment
salary income transfer from a company to an individual on the basis of an employment contract

Debt

Label Direction Description
bailiff expense transactions that are executed by bailiffs or enforcement agents following a court decision and without any action from the account owner
claim income payments made by loan companies to the clients, who were successfully reclaiming short-term loans, can be assigned only when loan label is also assigned (beta, only for Spain)
credit card expense repayment of credit card debt, can be combined with return in case of overpayment; label repayment is also being automatically assigned to such transactions
debt collection both voluntary repayment of debt to specialized debt collection companies
invoice both all incoming (mostly for companies) invoices, but also outgoing payments (often for phone and internet and tv)
late payment expense overdue payment transactions, usually combined with repayment label
leasing expense transactions indicating a leasing repayment
loan income transactions indicating a loan from a lending company or a bank; the label covers payday loans, consumer loans etc; does not cover: leasing-related transactions
mortgage expense transactions indicating a mortgage repayment
repayment expense repayment of a debt, such as loan installment or credit card debt

State

Label Direction Description
500+ income specific welfare benefit granted in Poland for every next child under 18
cit expense transfers describing CIT transactions (one of tax types- corporate income tax, only for Poland)
krus expense transfers suggesting that it is a corporate transfer (one of social insurance types, only for Poland)
pit expense transfers describing PIT transactions (one of tax types, only for Poland)
sick benefit income sickness benefits received due to a temporary or permanent inability to work; if this is a benefit paid by the state, label welfare is additionally assigned
tax expense income tax (PIT), property tax, capital gain tax, interest tax, excise, duty, value added tax (VAT), state social insurance (in Poland: ZUS), inheritance tax, and any other form of taxation; transactions with this label are usually expense transactions, but they could also represent income, e.g. tax return
unemployment benefit income government support for the unemployed
vat expense transfers describing VAT transactions (one of tax types, only for Poland)
welfare income any kind of social security - money received from the state, private charities and NGOs
zus expense transfers suggesting that it is a corporate transfer (one of social insurance types, only for Poland)

Cash

Label Direction Description
cash deposit income physical cash deposit via bank machine (ATM) or bank branch
cash withdrawal expense physical cash withdrawal from a bank machine (ATM) or bank branch

Lifestyle

Label Direction Description
accountancy expense payments for accounting services
alcohol expense spirits and liquor stores, online alcohol shops
apparel expense clothes, shoes, handbags etc.
beauty expense cosmetics, pharmacy, perfume shops, barber and hairdresser, manicure and pedicure salons, basic hygiene expenses; does not cover: apparel spendings
books expense money spent on books, ebooks, audiobooks, DVDs, albums, magazines etc. in stores like e.g. Empik in Poland or online
charity expense transfers describing charity transactions
culture expense events, concerts, museums, cinema, theaters, festivals, escape rooms, zoo visits, and similar; does not cover: does not cover transport and traveling
e commerce expense buying stuff online, for example Amazon, AliExpress, Allegro
eating out expense bars, restaurants, cafes, bistros, fast food restaurants; does not cover: pubs, cocktail bars, night clubs
education both education related outbound transactions (courses, university fee, academic, school trips), but also incoming transactions like grants or scholarships; does not cover: books
electronics expense consumer electronics, all physical and online stores, which have selling electronics as their primary business, for example MediaMarkt; also includes repair services and gadget shops; does not cover: electricity bills.
express transfer both transactions with titles, which indicate that it was an express transfer. BLIK online and phone payments work like express transfers.
food with delivery expense home food delivery (e.g. Pyszne.pl or Uber Eats)
gambling both online gambling and betting, lottery tickets, city casinos, and other forms of gambling; it can also mark income transactions, e.g. gambling gains
insurance both mandatory or optional insurance of any type, both expense and income transactions (e.g. overpayment return or insurance indemnity)
leisure expense transactions automatically assigned to transactions with labels: books, culture, pets, press, software and games, sport, streaming, travel
nightlife expense pubs and cocktail bars, night clubs, gentlemen clubs
pets expense money spent on pets, vet, food for dogs and cats etc.
postal service expense outcoming postal transactions (e.g. Inpost, Poczta Polska, DHL, DPD)
press expense money spent in newspaper shops
software and games expense money spent on PlayStation, Xbox, Windows Store etc., also all expenses for phone applications, such as Google Play, Apple App Store
sport expense sport-related expenses, including gyms, pools, yoga lessons, dance lessons, etc.; it covers sport gear shops (e.g. bike shops, Decathlon) as well
streaming expense any kind of online streaming services, e.g. Spotify, Netflix, Disney Plus, HBO Go; includes also iTunes purchases and similar
tobacco expense indicates products bought in specialized tobacco shops (only for Latvia, Portugal, Romania and Spain)
travel expense money spent on accommodation, flight tickets, long distance trains etc.
uberlike and taxi expense taxis, taxi-like services (e.g. Uber, Taxify, Lyft), carpooling services (e.g. BlaBlaCar) and car rentals (e.g. Panek)
university both outgoing transactions that are expenditure on higher education and incoming transactions like scholarships

Living

Label Direction Description
alimony both incoming and outgoing alimony transactions (children-related)
car expense fuel, parking, insurance, repairs, car accessories, road taxes, tickets and other car-related expenses
children both children-related expense and income; toys, accessories and clothes for babies, toddlers and young teenagers, children stores, kindergarten and pre-school payments, primary school books and expenses; does not cover: higher education, university fees, specialised trainings and courses e.g. photography school
fee expense bank and other financial fees; most often relatively small amount; it also covers fines and tickets, payments for SMS notifications etc.
grocery expense grocery stores, discount stores, supermarkets
healthcare expense medication, doctor and dentist visits, medical diagnosis, hospital bills, treatment bills, rehabilitation bills; does not cover: beauty procedures and SPA
indemnity income insurance indemnity incoming transfers; label insurance is being additionally assigned to these transactions
internet and tv expense internet and TV bills
life insurance both life insurance transfers, both expense and income transactions (e.g. overpayment return or life insurance indemnity)
phone expense mobile, landline
public transport expense public transport tickets and fees
refurbishment expense construction, furniture, interior design and household appliances
rent expense payment of rent for house, apartment, student housing etc.
utilities expense basic utilities like electricity, gas, water, heating, garbage collection; does not cover: TV, phone, internet, rent

Business labeling

A separate labeling model dedicated for business accounts is available in Poland. It has a different scope of labels tailored to the corporate finances. Response structure of a business labeling is exactly the same as in an individual labeling. Below you’ll find the list of labels available only in the business labeling. The detailed description of all labels, algorithms and exclusion criteria used to define the set of labels in business labeling is available upon request.

Label Direction Description
factoring both all transactions related to factoring companies
government assistance income transfers related to government aid programs intended for companies and entrepreneurs
investments both transfers related to investing money by a company for profit
payment terminal income transactions made via payment terminal
payroll expense wages paid to employees
split payment both transactions with amount of payment divided into two or more transactions
financing activity both label assigned automatically to all transactions having any label from financing category
operating activity both label assigned automatically to all transactions having any label from operating category
investing activity both label assigned automatically to all transactions having any label from investing category

Vendors Recognition (beta)

<analytics>
    <labels>
        <label>
            <name>e commerce</name>
        </label>
        <label>
            <name>payment processor</name>
        </label>
        <label>
            <name>beauty</name>
        </label>
    </labels>
</analytics>

<analytics>
    <labels>
      <label>
       <name>e commerce</name>
        <vendors>
         <vendor>Amazon</vendor>
        </vendors>
      </label>
        <label>
         <name>payment processor</name>
          <vendors>
           <vendor>Blik</vendor>
          </vendors>
      </label>
      <label>
       <name>beauty</name>
      </label>
    </labels>
</analytics>

The Vendors Recognition service returns information about parties/companies involved in a transaction, e.g. shops, online services, payment processors.

The recognized vendors are assigned to transaction labels, telling you what type of company the vendor is or the type of service they provide. Each transaction can receive 0, 1 or more vendors.

Please see Transaction analytics - vendors for the technical details of the data returned.

For the full list of vendors recognized and the labels they can be assigned to, please see this file.

Score

Returns assessments of the owner’s financial situation. Available only when also using the Labeling service.

The common score typically provided to new clients is based on Machine Learning models and follows the standard API response described below.

Custom-made scores might be based on different criteria and provide different response structure and values which you will be made aware of during the model preparation process.

Request

Request

curl --get \
  --header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
  --data "ownerExternalId=END_USERS_OWNER_EXTERNAL_ID" \
  https://test.api.kontomatik.com/v1/owner-scores.xml

GET /v1/owner-scores.xml

Parameters:

Parameter Requirement Description
ownerExternalId obligatory Identifier generated by you and used for Owner data aggregation

Response

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/get_owner_scores.xsd"
  status="200 OK"
  client="fastmoney"
  ownerExternalId="4324-13-14">

  <models>

    <!-- Common model -->
    <model id="common-2018-08-18" retrainedAt="2018-08-20T16:16:45Z">
      <scores>
        <score>
          <!-- 0..1 value representing estimated creditworthiness of an individual (the higher the better) -->
          <value>0.03282</value>
        </score>
        <scorePercentile>
          <!-- 0..1 value representing population percentile (the higher the better) -->
          <value>0.49824</value>
        </scorePercentile>
        <scoreTier>
          <!-- letter A-F indicating the scoring group (letter A is the most creditworth group) -->
          <value>C</value>
        </scoreTier>
      </scores>
    </model>

    <!-- Model specific to lender "Fast Money" (just to give an example) -->
    <model id="fastmoney-2018-08-01" retrainedAt="2018-08-14T07:16:45Z">
      <scores>
        <score>
          <!-- 0..1 value representing estimated creditworthiness of an individual (the higher the better) -->
          <value>0.9717</value>
        </score>
        <scorePercentile>
          <!-- 0..1 value representing population percentile (the higher the better) -->
          <value>0.81069</value>
        </scorePercentile>
        <scoreTier>
          <!-- rank of the client -->
          <value>TOP TIER CLIENT</value>
        </scoreTier>
      </scores>
    </model>

  </models>
</reply>

Please consult the provided example.

The reply element wraps a <models> object, which can contain multiple <model> objects. Select the one of interest to you using the id attribute.

The <model> object contains <scores> objects. A standard <score> object contains the following nodes with their values inside a <value> node:

Node Availability Description
score always Creditworthiness of the owner, 0..1 scale, the higher the better
scorePercentile always Estimates the percentile of the population which the owner’s score is equal to or better than based on training data, 0..1 scale, the higher the better
scoreTier always Client’s rank, typically ranging from A to F (A - highest, F - lowest)

Owner Features

Provides a list of numerous Machine Learning-based features describing the owner’s financials that are used to calculate the Score. Available only when also using the Scores and Labeling service.

By using Owner Features, you can pick and choose from available features to complement your own scoring.

Request

Request

  curl --get \
    --header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
    --data "ownerExternalId=END_USERS_OWNER_EXTERNAL_ID" \
    https://test.api.kontomatik.com/v1/owner-features.xml

GET /v1/owner-features.xml

Parameters:

Parameter Parameter Description
ownerExternalId obligatory Identifier generated by you and used for Owner data aggregation

Response

Response

  <?xml version="1.0" encoding="utf-8"?>
  <reply
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/get_features.xsd"
  status="200 OK"
  client="fastmoney"
  ownerExternalId="4324-13-14">

  <models>

    <!-- Common model -->
    <model id="common-2018-08-18" retrainedAt="2018-08-20T16:16:45Z">
      <features>
        <feature id="d4f51702ea" value="-0.43" relevance="0.8" />
        <feature id="59ab5c6f97" value="2.00355" relevance="0.3" />
        <feature id="03d10dbf0a" value="1.932" relevance="1.5" />
        <feature id="ec4207aaf2" value="NaN" relevance="0" />
        <feature id="b31711374c" value="-INF" relevance="-2" />
        <feature id="ddb0ebf93a" value="INF" relevance="5.3" />
        <!-- ...hundreds of features... -->
      </features>
    </model>

    <!-- Model specific to lender "Fast Money" (just to give an example) -->
    <model id="fastmoney-2018-08-01" retrainedAt="2018-08-14T07:16:45Z">
      <features>
        <feature id="d4f51702ea" value="-0.43" relevance="0.8" />
        <feature id="59ab5c6f97" value="2.00355" relevance="0.3" />
        <feature id="03d10dbf0a" value="1.932" relevance="1.5" />
        <feature id="ec4207aaf2" value="NaN" relevance="0" />
        <feature id="b31711374c" value="-INF" relevance="-2" />
        <feature id="ddb0ebf93a" value="INF" relevance="5.3" />
        <!-- ...hundreds of features... -->
      </features>
    </model>

  </models>
</reply>

Please consult the provided example.

The reply element wraps a <models> object, which can contain multiple <model> objects. Select the one of interest to you using the id attribute.

The <model> object contains a <features> list. The <features> list contains <feature> nodes with the following attributes:

Attribute Availability Description
id always Unique ID of the feature, not consistent between different models
value always Decimal value of the feature as a standard deviation from the population.
Possible values are a number, -INF, INF, NaN (see xs:double).
relevance always Decimal number representing how much the feature influenced the final score of the client.
A positive value means that the feature worked in favor of the client repaying, while a negative suggests the opposite.
Only numeric values are possible - NaN or INF are not allowed. Relevance "0" means the feature did not influence the outcome at all.

Data Summary

Accounts Summary Example

{
  "requestId": "5dc6f805-2d0d-11b2-87ca-736b35cd55fb",
  "content": {
    "PL46103015400000060994977858": {
      "daysInRange": 383,
      "activeSinceAtLeast": "2022-04-21",
      "currencyName": "PLN",
      "balance": 372559.16,
      "owners": [
        {
          "name": "Katarzyna Bałka",
          "address": "Długowieły 13/15 11-220",
          "kind": "OWNER"
        }
      ],
      "target": {
        "name": "MBankApi",
        "institution": "MBank",
        "officialName": "mBank"
      },                        
      "balancePerTransaction": {
        "min": 342069.94,
        "max": 369864.16,
        "average": 357069.99
      },
      "positiveBalancePerTransaction": {
        "min": 342069.94,
        "max": 369864.16,
        "average": 357069.99,
        "count": 34,
        "numberOfDays": 29
      },
      "negativeBalancePerTransaction": null,
      "allTransactions": {
        "all": {
          "count": 34,
          "average": 817.33,
          "total": 27789.22,
          "numberOfDays": 29
        },
        "outgoing": {
          "count": 23,
          "average": -91.77,
          "total": -2110.78,
          "numberOfDays": 21
        },
        "incoming": {
          "count": 11,
          "average": 2718.18,
          "total": 29900.00,
          "numberOfDays": 10
        }
      },
      "label:monthly": {
        "all": {
          "count": 16,
          "average": 570.76,
          "total": 9132.19,
          "numberOfDays": 16
        },
        "outgoing": {
          "count": 12,
          "average": -138.98,
          "total": -1667.81,
          "numberOfDays": 12
        },
        "incoming": {
          "count": 4,
          "average": 2700.00,
          "total": 10800.00,
          "numberOfDays": 4
        }
      }
    },
    "PL24888410270000060053524108": {
      "daysInRange": 383,
      "activeSinceAtLeast": "2022-09-21",
      "currencyName": "PLN",
      "balance": 115432.78,
      "owners": [
        {
          "name": "Katarzyna Bałka",
          "address": "Długowieły 13/15 11-220",
          "kind": "OWNER"
        }
      ],
      "target": {
        "name": "MBankApi",
        "institution": "MBank",
        "officialName": "mBank"
      },    
      "balancePerTransaction": {
        "min": 100535.69,
        "max": 110244.77,
        "average": 105062.97
      },
      "positiveBalancePerTransaction": {
        "min": 100535.69,
        "max": 110244.77,
        "average": 105062.97,
        "count": 46,
        "numberOfDays": 38
      },
      "negativeBalancePerTransaction": null,
      "allTransactions": {
        "all": {
          "count": 46,
          "average": 186.48,
          "total": 8577.93,
          "numberOfDays": 38
        },
        "outgoing": {
          "count": 39,
          "average": -78.77,
          "total": -3072.07,
          "numberOfDays": 34
        },
        "incoming": {
          "count": 7,
          "average": 1664.29,
          "total": 11650.00,
          "numberOfDays": 7
        }
      },
      "label:monthly": {
        "all": {
          "count": 17,
          "average": 438.80,
          "total": 7459.61,
          "numberOfDays": 15
        },
        "outgoing": {
          "count": 11,
          "average": -153.67,
          "total": -1690.39,
          "numberOfDays": 10
        },
        "incoming": {
          "count": 6,
          "average": 1525.00,
          "total": 9150.00,
          "numberOfDays": 6
        }
      }
    }
  }
}

Owner Summary With Monthly Example

{
    "requestId": "e864ff84-2d19-11b2-a030-d706fba888c6",
    "content": {
        "owners": [
            {
                "name": "Tadeusz Krajowy",
                "address": null,
                "kind": "CO_OWNER"
            },
            {
                "name": "Maria Sochacka",
                "address": "Stolarska 15/2 33-543 Jaworzno",
                "kind": "OWNER"
            }
        ],
        "currencies": {
            "PLN": {
                "monthly": {
                    "2023-01": {
                        "daysInRange": 31,
                        "balancePerTransaction": {
                            "min": 245061.16,
                            "max": 250352.20,
                            "average": 247754.11
                        },
                        "allTransactions": {
                            "all": {
                                "count": 17,
                                "average": 304.50,
                                "total": 5176.42,
                                "numberOfDays": 13
                            },
                            "outgoing": {
                                "count": 13,
                                "average": -71.04,
                                "total": -923.58,
                                "numberOfDays": 11
                            },
                            "incoming": {
                                "count": 4,
                                "average": 1525.00,
                                "total": 6100.00,
                                "numberOfDays": 4
                            }
                        },
                        "label:monthly": {
                            "all": {
                                "count": 3,
                                "average": 815.12,
                                "total": 2445.36,
                                "numberOfDays": 3
                            },
                            "outgoing": {
                                "count": 2,
                                "average": -127.32,
                                "total": -254.64,
                                "numberOfDays": 2
                            },
                            "incoming": {
                                "count": 1,
                                "average": 2700.00,
                                "total": 2700.00,
                                "numberOfDays": 1
                            }
                        },
                        "label:loan": {
                            "all": {
                                "count": 0,
                                "average": null,
                                "total": 0.00,
                                "numberOfDays": 0
                            },
                            "outgoing": {
                                "count": 0,
                                "average": null,
                                "total": 0.00,
                                "numberOfDays": 0
                            },
                            "incoming": {
                                "count": 0,
                                "average": null,
                                "total": 0.00,
                                "numberOfDays": 0
                            }
                        }
                    },
                    "2023-02": {
                        "daysInRange": 28,
                        "balancePerTransaction": {
                            "min": 250057.55,
                            "max": 256212.22,
                            "average": 254314.14
                        },
                        "allTransactions": {
                            "all": {
                                "count": 13,
                                "average": 473.44,
                                "total": 6154.66,
                                "numberOfDays": 11
                            },
                            "outgoing": {
                                "count": 8,
                                "average": -36.92,
                                "total": -295.34,
                                "numberOfDays": 7
                            },
                            "incoming": {
                                "count": 5,
                                "average": 1290.00,
                                "total": 6450.00,
                                "numberOfDays": 4
                            }
                        },
                        "label:monthly": {
                            "all": {
                                "count": 2,
                                "average": -63.66,
                                "total": -127.33,
                                "numberOfDays": 2
                            },
                            "outgoing": {
                                "count": 2,
                                "average": -63.66,
                                "total": -127.33,
                                "numberOfDays": 2
                            },
                            "incoming": {
                                "count": 0,
                                "average": null,
                                "total": 0.00,
                                "numberOfDays": 0
                            }
                        },
                        "label:loan": {
                            "all": {
                                "count": 0,
                                "average": null,
                                "total": 0.00,
                                "numberOfDays": 0
                            },
                            "outgoing": {
                                "count": 0,
                                "average": null,
                                "total": 0.00,
                                "numberOfDays": 0
                            },
                            "incoming": {
                                "count": 0,
                                "average": null,
                                "total": 0.00,
                                "numberOfDays": 0
                            }
                        }
                    },
                    "2023-03": {
                        "daysInRange": 31,
                        "balancePerTransaction": {
                            "min": 258947.23,
                            "max": 259422.52,
                            "average": 259167.80
                        },
                        "allTransactions": {
                            "all": {
                                "count": 12,
                                "average": 265.86,
                                "total": 3190.29,
                                "numberOfDays": 11
                            },
                            "outgoing": {
                                "count": 9,
                                "average": -34.41,
                                "total": -309.71,
                                "numberOfDays": 9
                            },
                            "incoming": {
                                "count": 3,
                                "average": 1166.67,
                                "total": 3500.00,
                                "numberOfDays": 3
                            }
                        },
                        "label:monthly": {
                            "all": {
                                "count": 1,
                                "average": -0.01,
                                "total": -0.01,
                                "numberOfDays": 1
                            },
                            "outgoing": {
                                "count": 1,
                                "average": -0.01,
                                "total": -0.01,
                                "numberOfDays": 1
                            },
                            "incoming": {
                                "count": 0,
                                "average": null,
                                "total": 0.00,
                                "numberOfDays": 0
                            }
                        },
                        "label:loan": {
                            "all": {
                                "count": 0,
                                "average": null,
                                "total": 0.00,
                                "numberOfDays": 0
                            },
                            "outgoing": {
                                "count": 0,
                                "average": null,
                                "total": 0.00,
                                "numberOfDays": 0
                            },
                            "incoming": {
                                "count": 0,
                                "average": null,
                                "total": 0.00,
                                "numberOfDays": 0
                            }
                        }
                    }
                },
                "daysInRange": 90,
                "activeSinceAtLeast": "2022-08-14",
                "owners": [
                    {
                        "name": "Maria Sochacka",
                        "address": "Stolarska 15/2 33-543 Jaworzno",
                        "kind": "OWNER"
                    },
                    {
                        "name": "Tadeusz Krajowy",
                        "address": null,
                        "kind": "CO_OWNER"
                    }
                ],
                "balance": 259402.51,
                "balancePerTransaction": {
                    "min": 245061.16,
                    "max": 259422.52,
                    "average": 253045.65
                },
                "allTransactions": {
                    "all": {
                        "count": 42,
                        "average": 345.75,
                        "total": 14521.37,
                        "numberOfDays": 35
                    },
                    "outgoing": {
                        "count": 30,
                        "average": -50.95,
                        "total": -1528.63,
                        "numberOfDays": 27
                    },
                    "incoming": {
                        "count": 12,
                        "average": 1337.50,
                        "total": 16050.00,
                        "numberOfDays": 11
                    }
                },
                "label:monthly": {
                    "all": {
                        "count": 6,
                        "average": 386.34,
                        "total": 2318.02,
                        "numberOfDays": 6
                    },
                    "outgoing": {
                        "count": 5,
                        "average": -76.40,
                        "total": -381.98,
                        "numberOfDays": 5
                    },
                    "incoming": {
                        "count": 1,
                        "average": 2700.00,
                        "total": 2700.00,
                        "numberOfDays": 1
                    }
                },
                "label:loan": {
                    "all": {
                        "count": 0,
                        "average": null,
                        "total": 0.00,
                        "numberOfDays": 0
                    },
                    "outgoing": {
                        "count": 0,
                        "average": null,
                        "total": 0.00,
                        "numberOfDays": 0
                    },
                    "incoming": {
                        "count": 0,
                        "average": null,
                        "total": 0.00,
                        "numberOfDays": 0
                    }
                }
            }
        }
    }
}

Data Summary is a calculation tool providing you with a summary of the owner’s data in the form of many metrics divided into categories for a requested date range.

You can fetch an Accounts Summary (per account calculations) or an Owner Summary (summarizing all accounts). Each can be further divided per month.

For an additional implementation fee and depending on available data, you can request a custom-made category designed to fit your specific needs.

Available calculations

The following abbreviations are used for the scope of categories:

Category Scope & Availability Description
daysInRange A, AM, O, OM; always Number of days in the calculated scope
activeSinceAtLeast A, O; almost always Date of oldest transaction found (for O - among all accounts, for A - per account)
currencyName A*; always Currency of the account
ibans O**; always List of IBANs from all imported accounts
owners A, O; usually List of account owners
A: per account
O: found on all accounts
target A; always Information about the account source target
balance A, O; always Current balance of the account (A) or sum of all current balances within a given currency (O)
balancePerTransaction A, AM, O, OM; sometimes Metrics calculated from information about account balances after each transaction
positiveBalancePerTransaction A, AM, O, OM; sometimes Calculated from information about balance after each transaction, for when the balance was 0 or over
negativeBalancePerTransaction A, AM, O, OM; rarely Calculated from information about balance after each transaction, for when the balance was below 0
allTransactions A, AM, O, OM; almost always Summary of all transactions
Null when no transactions were fetched
Labels Query A, AM, O, OM; often; when labeling enabled Summary of all transactions that contain labels matching the Labels Query

*Owner Summary includes the currency names as fields used to categorize summaries in different currencies.

**Account Summary includes the IBANs as fields identifying each account's summary.

Request

Request

curl \
  --header 'X-Api-Key: YOUR_LONG_API_KEY_HERE' \
  --header "Content-Type: application/json" \
  --data '{"ownerExternalId":"12345","start":"2022-10-01","end":"2023-01-31","categories":["balance","allTransactions","label:healthcare"]}' \
  --request POST https://test.api.kontomatik.com/v1/accounts-summary-with-monthly

Request

curl \
--header 'X-Api-Key: YOUR_LONG_API_KEY_HERE' \
--header "Content-Type: application/json" \
--data '{"ownerExternalId":"12345","start":"2022-10-01","end":"2023-01-31","categories":["daysInRange","balance","allTransactions","ibans", "label:loan"]}' \
--request POST https://test.api.kontomatik.com/v1/owner-summary-with-monthly

Choose one of the following endpoints depending on the type of summary you need:

POST /v1/accounts-summary

POST /v1/accounts-summary-with-monthly

POST /v1/owner-summary

POST /v1/owner-summary-with-monthly

The requests require:

Parameter Availability Description
ownerExternalId obligatory Identifier generated by you and used for Owner data aggregation
start obligatory Start date for the calculations, e.g. 2023-01-01
end obligatory End date for the calculations, e.g. 2023-01-31
categories obligatory List of categories to be included in the response, see: Categories parameter

The range between start and end dates cannot surpass 10 years.

Categories parameter

Categories are passed as an array containing their names, e.g.: [“balancePerTransaction”, “owners”, “activeSinceAtLeast”, “allTransactions”]

For label:(label) category, include it in the request as following: [“label:car”, “label:loan”]

For label:(all_labels), join multiple labels with an ampersand sign (up to 5 labels in one category): [“label:car&loan”, “label:leasing&car&loan&bank”]

For label:(any_labels), join multiple labels with a pipe sign (up to 5 labels in one category): [“label:salary|compensation”, “label:leasing|car”]

See the list of available labels and their technical names to be used in the request.

For Labels Queries please consult the section below.

All types of categories can be joined together in one request: [“balancePerTransaction”, “owners”, “activeSinceAtLeast”, “label:car”, “label:loan”, “label:car&loan”, “label:leasing&car&loan&bank”, “label:salary|compensation”]

Labels Query

With the Labels Query, you can create your own category that will base the calculations on transactions having specific labels assigned if you’re using the Labeling service. You can achieve this by creating a rule based on the labels we provide and using logical operators AND (&), OR (|) and NOT (~).

The query construction:

Labels Query examples:

In the response, your query will become the category name with calculated metrics inside.

For more information about the Labels Query, check our User Guide about it.

Response

Below you’ll find descriptions of data structures possible to receive in the Data Summary (Accounts or Owner) responses.

Main response structure

Example

{
  "requestId": "b1a7eb21-be0c-4805-bb4e-6c93e61ac0d8",
  "content": {...}
}

Example

{
  "requestId": "b1a7eb21-be0c-4805-bb4e-6c93e61ac0d8",
  "exception": {...}
}

The response is a JSON object with the following structure:

Node Type Description
requestId String ID of the data summary request for debugging purposes.
content Object Accounts Summary Map or Owner Summary Object (depending on the used endpoint). The key is missing when any exceptions occur.
exception Object JSON Error Response. The key is missing when no exception occurs.

Nested Data Structures

Accounts Summary Map

Example:

"content": {
  "PL24888410270000060053524108": {
    "balance": 115432.78,
    "allTransactions": {...},
    ...
  },
  "PL80960400050000092274855291": {...},
  "PL85903800040000047549807460": {...},
  ...
}

An object mapping IBANs as keys to Account Summary Objects. Each Account Object contains a summary of the account identified by the IBAN.

Owner Summary Object

Example:

"content": {
  "owners": [
     {
     "name": "Jan Kowalski i S-ka",
     "address": "Kwiatowa 8/97 Warszawa  PL",
     "kind": "COMPANY",
     "polishNip": "1092596394",
     "email": "jkowalski.firma@gmail.com"
      },
      { ... }
   ],
  "currencies": {
    "EUR": {
      "balance": 102149.79,
      "owners": ...,
      ...
      },
    "PLN": {
      ...
      }
  }
}
Node Type Description
owners Array List of global owners (Array containing Global Owner Objects). Contains a list of reduplicated owners information gathered from all accounts in all currencies with potentially additional data which is impossible to assign in currency-related objects.
currencies Date Owner Currencies Summary Map
Owner Currencies Summary Map

Example:

"currencies": {
  "EUR": {
    "balance": 102149.79,
    "owners": ...,
    ...
  },
  "PLN": {
    ...
  }
}

An object mapping currency names as keys to Owner Currency Summary Object. Each Owner Currency Summary Object contains a summary of the owner’s accounts that are held in a specific currency.

Account Summary Object

Example:

"PL46103015400000060994977858": {
  "daysInRange": 92,
  "balance": 2041.32,
  "activeSinceAtLeast": "2022-04-04",
  "owners": [
  ...
  ],
  "target": {
  ...
  },
  "balancePerTransaction": {
  ...
  },
  "positiveBalancePerTransaction": {
  ...
  },
  "negativeBalancePerTransaction": {
  ...
  },
  "allTransactions": {
  ...
  },
  "label:healthcare": {
  ...
  },
  "label:monthly&healthcare": {
  ...
  },
  "monthly": {
  ...
  }
}
Node Type Description
daysInRange Number Number of days within the requested date range
activeSinceAtLeast Date Date of the oldest transaction found in the account. Can exceed the requested Summary date range.
currencyName String Currency symbol, e.g. "PLN"
balance Number Current account balance
owners Array List of account owners (Array containing Owner Objects)
target Object Target Information Object
balancePerTransaction Object Balance Per Transaction Object
positiveBalancePerTransaction Object Directional Balance Object
negativeBalancePerTransaction Object Directional Balance Object
allTransactions Object Directional Category Object
label:(label/all_labels/any_labels) Object Directional Category Object
monthly Object Monthly Summary Map, contains monthly summaries for the account, only in /v1/accounts-summary-with-monthly

Owner Currency Summary Object

Example

"PLN": {
  "daysInRange": 102,
  "balance": 5191.48,
  "activeSinceAtLeast": "2022-03-01",
  "ibans": [
    "PL31831900030000047764589493",
    "PL59106001770000082840025256"
  ],
  "owners": [
    ...
  ],
  "balancePerTransaction": {
    ...
  },
  "positiveBalancePerTransaction": {
    ...
  },
  "negativeBalancePerTransaction": {
    ...
  },
  "allTransactions": {
    ...
  },
  "label:healthcare": {
    ...
  },
  "label:monthly&healthcare": {
    ...
  },
  "monthly": {
    ...
  }
}

All categories and metrics in the Owner Currency Summary Object are calculated within a scope of a given currency (i.e. “all accounts” refers to all accounts in that currency).

Node Type Description
daysInRange Number Number of days within the requested date range
activeSinceAtLeast Date Date of the oldest transaction found in all accounts. Can exceed the requested Summary date range
ibans Array List of IBANs for all accounts
balance Number Sum of current balances from all accounts
owners Array List of owners found in all accounts (Array containing Owner Objects)
balancePerTransaction Object Balance Per Transaction Object
positiveBalancePerTransaction Object Directional Balance Object
negativeBalancePerTransaction Object Directional Balance Object
allTransactions Object Directional Category Object
label:(label/all_labels/any_labels) Object Directional Category Object
monthly Object Monthly Summary Map, contains monthly summaries for the account, only in /v1/owner-summary-with-monthly
Monthly Summary Map

Example

"monthly": {
    "2022-10": {
    "daysInRange": 22,
    "balancePerTransaction": {...},
    ...
  },
  "2022-11": {...},
  "2022-12": {...}
}

An object mapping year-month as keys to Monthly Summary Object. Each Monthly Summary Object contains a summary of the account(s) for the month identified by the year-month.

Monthly Summary Object

Example

"2022-10": {
  "daysInRange": 22,
  "balancePerTransaction": {
    "min": 143821.21,
    "max": 151921.20,
    ...
  },
  "positiveBalancePerTransaction": {...},
  "negativeBalancePerTransaction": {...},
  "allTransactions": {...},
  "label:healthcare": {...},
  "label:monthly&healthcare": {...}
  }
}

Object containing categories calculated for a given month.

Node Type Description
daysInRange Number Number of days in a given month, cut by either start or end date of the requested summary range
balancePerTransaction Object Balance Per Transaction Object
positiveBalancePerTransaction Object Directional Balance Object
negativeBalancePerTransaction Object Directional Balance Object
allTransactions Object Directional Category Object
label:(label/all_labels/any_labels) Object Directional Category Object

Balance Per Transaction Object

Example

"balancePerTransaction": {
  "min": 143821.21,
  "max": 151921.20,
  "average": 149233.78
}

Object containing metrics calculated from account balances after each transaction.

Node Type Description
min Number Lowest account balance found in transactions
max Number Highest account balance found in transactions
average Number Average from all found balances in transactions

Directional Balance Object

Example

"positiveBalancePerTransaction": {
  "min": 143821.21,
  "max": 151921.20,
  "average": 149233.78,
  "count": 7,
  "numberOfDays": 4
}

Metrics calculated from account balances after each transaction in a given state - when the balance is negative (below 0) or positive (0 or higher).

Node Type Description
min Number Lowest found balance in transactions
max Number Highest found balance in transactions
average Number Average from all found balances in transactions
count Number Number of transactions with a balance in the given state (negative or positive)
numberOfDays Number Number of days when any transaction has a balance in the given state (negative or positive)

Global Owner Object

Example

{
  "name": "Jan Kowalski i S-ka",
  "address": "Kwiatowa 8/97 Warszawa  PL",
  "kind": "COMPANY",
  "polishNip": "1092596394",
  "email": "jkowalski.firma@gmail.com"
}

Object containing owner information. The object is included in the array of all global owners and follows the Owner section structure.

Node Type Description
name String Name of an account owner
address String Address of an account owner
kind String one of: OWNER, CO_OWNER, COMPANY. OWNER is the natural person shown as the main account owner, for example in the profile page. CO_OWNER is a co-owner of one of the bank accounts with full access to that specific bank account. COMPANY is the legal entity shown as the main account owner. If it's not possible to determine the main owner, all found persons will be marked as OWNER.
polishNip String Polish NIP number
polishRegon String Polish REGON number
phone String Phone number
email String Email address
citizenship String Citizenship
nationality String Nationality
personalDocumentType String Identity document type, as presented by the bank (e.g. “National ID”)
personalDocumentNumber String Identity document number
birthDate String Date of birth
birthPlace String Place of birth

Owner Object

Example

{
  "name": "Jan Kowalski",
  "address": "Kwiatowa 8/97 Warszawa  PL",
  "kind": "OWNER"
}

Object containing owner information. The object is included in the array of all owners and follows the Owner section structure with a restriction to 3 fields: kind, name, address.

Node Type Description
name String Name of an account owner
address String Address of an account owner
kind String one of OWNER, CO_OWNER, COMPANY. OWNER is the natural person shown as the main account owner, for example in the profile page. CO_OWNER is a co-owner of one of the bank accounts with full access to that specific bank account. COMPANY is the legal entity shown as the main account owner. If it's not possible to determine the main owner, all found persons will be marked as OWNER.

Target Information Object

Example

"target": {
  "name": "MBankApi",
  "institution": "MBank",
  "officialName": "mBank"
}

Returns information about the target a given account comes from.

Node Type Description
name String Name of the target
institution String Name of the target
officialName String Official name of the bank

Directional Category Object

Example

"allTransactions": {
  "all": {
    "count": 3,
    "average": -52.00,
    ...
  },
  "outgoing": {...},
  "incoming": {...}
}
Node Type Description
all Object Directional Metrics Object, grouping all transactions within a given scope
incoming Object Directional Metrics Object, grouping only incoming transactions within a given scope
outgoing Object Directional Metrics Object, grouping only outgoing transactions within a given scope

Directional Metrics Object

Example

"incoming": {
  "count": 0,
  "average": null,
  "total": 0.00,
  "numberOfDays": 0
}
Node Type Description
average Number Average from transactions values in a given scope
count Number Number of transactions in a given scope
total Number Sum total of transactions values in a given scope
numberOfDays Number Number of days when the transactions in a given scope occurred

Income Confirmation (beta)

Income Confirmation provides a categorized summary of an end-user’s income sources in the past 3 months based on bank transaction data obtained via Kontomatik.

When the endpoint is called for a given ownerExternalId, all imported bank accounts are split by currencies and for each of them we create a summary divided into months - M-0, M-1, M-2 which mean current month, previous month and two months ago respectively. The summary for each month provides sum totals of incoming transaction amounts in different categories (e.g. salary, pension, other income).

We also provide a summary for the last 90 days in the same categories, but in this case the totals are divided by 3, creating a monthly average for this period (90daysMonthlyAverage in the API response).

The categories in which the calculations are made are based on the Transaction Labeling performed by our Machine Learning and other algorithms.

For compliance purposes please use the Accept-Signature: SHA256withRSA header in the API call in order for us to digitally sign the response (see: Digitally Signed Responses). This will give you certainty that the data comes from our servers and hasn’t been modified by anyone during the transfer.

For billing purposes, for a single end-user identified by ownerExternalId and the scope of imported data at the moment of using this feature, all requests to the Income Confirmation endpoint are treated as one event.

Request

Request

curl --get \
 --header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
 --header "Content-Type: application/json" \
 --header "Accept-Signature: SHA256withRSA" \
 --data "ownerExternalId=222222" \
https://api.kontomatik.com/v1/owner-income-confirmation

GET /v1/owner-income-confirmation

Parameters

Parameter Requirement Description
ownerExternalId obligatory Identifier generated by you and used for Owner data aggregation

Income Confirmation Response

Main response structure

Example

{
  "requestId": "ebcf7879-2c46-11b2-a695-e75b6d3b9d75",
  "content": {...}
}

Example

{
  "requestId": "b1a7eb21-be0c-4805-bb4e-6c93e61ac0d8",
  "exception": {...}
}

Example

{
  "requestId": "ebcf7879-2c46-11b2-a695-e75b6d3b9d75",
  "content": {
    "description": "Data confirmed based on bank account history",
    "dataUpdate": "2020-05-10",
    "currencies": {
      "EUR": {
        "ibans": [
          "PL06054594124717966313342836"
        ],
        "oldestTransactionFound": "2020-01-10",
        "newestTransactionFound": "2020-05-09",
        "90daysMonthlyAverage": {
          "start": "2020-02-10",
          "end": "2020-05-10",
          "salary": 533.33,
          "extraPay": 533.33,
          "regularWage": 400.00,
          "invoice": 266.67,
          "otherIncome": 133.33,
          "welfareAndAlimony": 266.67,
          "pension": 400.00,
          "cashDeposit": 133.33,
          "internal": 133.33,
          "total": 2799.99
        },
        "M-0": {
          "start": "2020-05-01",
          "end": "2020-05-10",
          "salary": 400.00,
          "extraPay": 400.00,
          "regularWage": 300.00,
          "invoice": 200.00,
          "otherIncome": 100.00,
          "welfareAndAlimony": 200.00,
          "pension": 300.00,
          "cashDeposit": 100.00,
          "internal": 100.00,
          "total": 2100.00
        },
        "M-1": {
          "start": "2020-04-01",
          "end": "2020-04-30",
          "salary": 400.00,
          "extraPay": 400.00,
          "regularWage": 300.00,
          "invoice": 200.00,
          "otherIncome": 100.00,
          "welfareAndAlimony": 200.00,
          "pension": 300.00,
          "cashDeposit": 100.00,
          "internal": 100.00,
          "total": 2100.00
        },
        "M-2": {
          "start": "2020-03-01",
          "end": "2020-03-31",
          "salary": 400.00,
          "extraPay": 400.00,
          "regularWage": 300.00,
          "invoice": 200.00,
          "otherIncome": 100.00,
          "welfareAndAlimony": 200.00,
          "pension": 300.00,
          "cashDeposit": 100.00,
          "internal": 100.00,
          "total": 2100.00
        }
      },
      "PLN": {
        "ibans": [
          "PL05114020170000400213015148",
          "PL16385396554957485595895803"
        ],
        "oldestTransactionFound": "2020-01-10",
        "90daysMonthlyAverage": {
          "start": "2020-02-10",
          "end": "2020-05-10",
          "salary": 1066.67,
          "extraPay": 1066.67,
          "regularWage": 800.00,
          "invoice": 533.33,
          "otherIncome": 266.67,
          "welfareAndAlimony": 533.33,
          "pension": 800.00,
          "cashDeposit": 266.67,
          "internal": 266.67,
          "total": 5600.01
        },
        "M-0": {
          "start": "2020-05-01",
          "end": "2020-05-10",
          "salary": 800.00,
          "extraPay": 800.00,
          "regularWage": 600.00,
          "invoice": 400.00,
          "otherIncome": 200.00,
          "welfareAndAlimony": 400.00,
          "pension": 600.00,
          "cashDeposit": 200.00,
          "internal": 200.00,
          "total": 4200.00
        },
        "M-1": {
          "start": "2020-04-01",
          "end": "2020-04-30",
          "salary": 800.00,
          "extraPay": 800.00,
          "regularWage": 600.00,
          "invoice": 400.00,
          "otherIncome": 200.00,
          "welfareAndAlimony": 400.00,
          "pension": 600.00,
          "cashDeposit": 200.00,
          "internal": 200.00,
          "total": 4200.00
        },
        "M-2": {
          "start": "2020-03-01",
          "end": "2020-03-31",
          "salary": 800.00,
          "extraPay": 800.00,
          "regularWage": 600.00,
          "invoice": 400.00,
          "otherIncome": 200.00,
          "welfareAndAlimony": 400.00,
          "pension": 600.00,
          "cashDeposit": 200.00,
          "internal": 200.00,
          "total": 4200.00
        }
      }
    }
  }
}

The response is a JSON object with the following structure:

Node Type Description
requestId String ID of the data summary request for data for debugging purposes.
content Object Income Confirmation Object. The key is missing when any exceptions occur.
exception Object JSON Error Response. The key is missing when no exception occurs.
Income Confirmation Object

Example

"content": {
  "description": "Legal notice",
  "dataUpdate": "2020-05-10",
  "currencies": {...}
}
Node Type Description
description String Legal notice for the generated calculations.
dataUpdate Date The date of the last time the owner data was updated (e.g. last AIS import performed or PDF Parsing for that owner).
currencies Object Income Confirmation Currency Map.

Income Confirmation Currency Map

Example

"currencies": {
  "EUR": {...},
  "PLN": {...}
}

An object mapping currency names as keys to Income Confirmation Currency Objects. Each Income Confirmation Currency Object contains calculations for the owner’s accounts that are held in a specific currency.

Income Confirmation Currency Object

Example

"PLN": {
  "ibans": [
    "PL05114020170000400213015148",
    "PL16385396554957485595895803"
  ],
  "oldestTransactionFound": "2020-01-10",
  "90daysMonthlyAverage": {...},
  "M-0": {...},
  "M-1": {...},
  "M-2": {...}
}

All calculations or values regard the specific currency.

Node Type Description
ibans Array IBANs
oldestTransactionFound Date The date of the oldest transaction found.
newestTransactionFound Date The date of the newest transaction found.
90daysMonthlyAverage Object Income Confirmation Summary Object
Contains summarized information about income in different categories from the last 90 days. Each individual amount is a total divided by 3.
M-0 Object Income Confirmation Summary Object
Contains summarized information about income in different categories from the current month. Each individual amount is a sum total amount for these categories.
M-1 Object Income Confirmation Summary Object
Contains summarized information about income in different categories from the previous month. Each individual amount is a sum total amount for these categories.
M-2 Object Income Confirmation Summary Object
Contains summarized information about income in different categories from two months ago. Each individual amount is a sum total amount for these categories.
Income Confirmation Summary Object

Example

"M-2": {
  "start": "2020-03-01",
  "end": "2020-03-31",
  "salary": 800.00,
  "extraPay": 800.00,
  "regularWage": 600.00,
  "invoice": 400.00,
  "otherIncome": 200.00,
  "welfareAndAlimony": 400.00,
  "pension": 600.00,
  "cashDeposit": 200.00,
  "internal": 200.00,
  "total": 4200.00
}

The object contains values being sums of income in specific categories. For the 90daysMonthlyAverage the value is the total divided by 3.

The categories include transactions with specific labels mentioned in the description column below.

Node Type Description
start Date Start date for the period calculation
end Date End date for the period calculation
salary Number Includes labels: salary
Excludes labels: n/a
extraPay Number Includes labels: extra pay
Excludes labels: salary
regularWage Number Includes labels: regular wage
Excludes labels: salary, extra pay
invoice Number Includes labels: invoice
Excludes labels: extra pay, regular wage
otherIncome Number Includes labels: compensation
Excludes labels: salary, regular wage, extra pay, invoice
welfareAndAlimony Number Includes labels: welfare, alimony
Excludes labels: pension
pension Number Includes labels: pension
Excludes labels: n/a
cashDeposit Number Includes labels: cash deposit
Excludes labels: n/a
internal Number Includes labels: internal
Excludes labels: n/a
total Number Sum total of the categories above

External Data Labeling

External Data Labeling enables you to obtain labels for sets of transactions from sources other than the Kontomatik API. This feature allows you to send batches of transactions related to multiple accounts and owners at once. Data sent via this endpoint will not be usable for other purposes, e.g. Data aggregation or other analytical features. If you require such handling, please see Owner Upload.

External Labeling Setup

This endpoint will set up a process that will asynchronously add labels to your transactions. Get the command ID from the response and then poll for the External Labeling Response later.

Request

Request

curl \
  -H "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d @data.json \
https://test.api.kontomatik.com/v1/command/label-transactions

Example data.json file content

[
  {
    "country": "PL",
    "ibans": [
      "PL61109010140000071219812874",
      "PL78001230020000432532412340"
    ],
    "ownerNames": [
      "Jan Kowalski",
      "Janina Kowalska"
    ],
    "transactions": [
      {
        "uid": "1",
        "currencyAmount": -1.00,
        "currencyBalance": 1.00,
        "transactionOn": "2012-06-28",
        "kind": "PŁATNOŚĆ KARTĄ",
        "party": "Beauty & Grocery",
        "title": "Płatność kartą w Beauty & Grocery",
        "partyIban": "PL00000000000000000000000003"
      },
      {
        "uid": "2",
        "currencyAmount": 1.00,
        "currencyBalance": 1.00,
        "transactionOn": "2012-06-28",
        "kind": "PRZELEW",
        "party": "Pracodawca",
        "title": "Wynagrodzenie",
        "partyIban": "PL00000000000000000000000004"
      }
    ]
  },
  {
    "country": "PL",
    "ibans": [
      "PL00000000000000000000000004"
    ],
    "ownerNames": [
      "Some Company s.p. z.o.o"
    ],
    "transactions": [
      {
        "uid": "3",
        "currencyAmount": 1.00,
        "currencyBalance": 1.00,
        "transactionOn": "2019-02-14",
        "kind": "PRZELEW",
        "party": "ZUS",
        "title": "ZUS",
        "partyIban": "PL00000000000000000000000005"
      }
    ]
  }
]

To request labeling of your data, send the following request:

POST /v1/command/label-transactions

External Labeling Payload

Example

[
  {
    "country": ...,
    "ibans": ...,
    "ownerNames": ...,
    "transactions": [...]
  },
  {
    ...
  },
  ...
]

The Payload is an array representing a list of batches to be processed.

External Labeling Batch

Example

{
  "country": "PL",
  "ibans": [
    "PL61109010140000071219812874",
    "PL78001230020000432532412340"
  ],
  "ownerNames": [
    "Jan Kowalski",
    "Janina Kowalska"
  ],
  "transactions": [...]
}

One batch of data ideally should represent accounts and transactions regarding a specific owner or a group of owners.

Field Requirement Description Example value
country obligatory Country code “PL”
ibans optional List of IBANs where the transactions belong ["PL00000000000000000000000001",
"PL00000000000000000000000002"]
owner_names optional List of end-users marked as owners for the accounts ["Some Owner", "Some Second Owner"]
transactions obligatory See: External Labeling Transactions List [<transaction1>, <transaction2>, …]
External Labeling Transactions List

Example

[
  "transactions": [
    {
      "uid": "1",
      "currencyAmount": -1.00,
      "currencyBalance": 1.00,
      "transactionOn": "2012-06-28",
      "kind": "PŁATNOŚĆ KARTĄ",
      "party": "Beauty & Grocery",
      "title": "Płatność kartą w Beauty & Grocery",
      "partyIban": "PL00000000000000000000000003"
    },
    {
      "uid": "2",
      "currencyAmount": 1.00,
      "currencyBalance": 1.00,
      "transactionOn": "2012-06-28",
      "kind": "PRZELEW",
      "party": "Pracodawca",
      "title": "Wynagrodzenie",
      "partyIban": "PL00000000000000000000000004"
    },
  ]
Field Requirement Description Example value
uid obligatory Unique ID of the transaction.

This field has to be unique across the entire External Labeling Payload in all batches!		 “batch001-26-01-2018__-124.00_1”
currencyAmount obligatory Amount of the transaction. Positive for incoming transfers, negative for outgoing ones. -15.43
currencyBalance optional Account balance after the transaction 1200.00
transactionOn obligatory Date of the operation “2018-02-15”
party optional The other party in the transaction “Sklep Żabka”
partyIban optional IBAN of the other party “PL26003043020000012412312313”
title optional Title of the transaction “Zakupy na kwotę 15.43”
kind optional Transaction kind/type “Płatność kartą”
Response

Example

{
  "id": 123,
  "state": "in_progress"
}
Field Description Example value
id ID of the External Labeling command to be used in the External Labeling Result endpoint 752468123
state Command status. See: External Labeling Command Status “in_progress”
exception Exception details in case an error occurs. See: External Labeling Error Response {"name":"ExampleException","message":"Example message"}

External Labeling Result

Returns information about the state of a labeling command and provides its result in the case that it’s successful.

To be called repeatedly until you receive a final state: successful, error or fatal. When you get one of these, save the response in your system and stop calling the endpoint.

We recommend 2-5 second intervals for polling.

Request

Request

curl \
  -H "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
  -H "Content-Type: application/json" \
https://test.api.kontomatik.com/v1/command/{id}.json

GET /v1/command/{id}.json

{id} is the command ID you received when setting up the labeling command. This endpoint doesn’t require any parameters except for your API Key.

Response

Response

{
  "id": 3,
  "state": "successful",
  "result": [...]
}

You’ll receive a JSON response containing a command object with the following fields:

Field Description Example value
id ID of the External Labeling command to be used in the External Labeling Result endpoint 752468123
state Command status. See: External Labeling Command Status “success”
exception Exception details in case an error occurs. See: External Labeling Error Response {"name":"ExampleException","message":"Example message"}
result Command result, if successful, see: Labeling Result List [\<labels1\>,\<labels2\>,...]
Labeling Result List

Example

[
  "result": [
    {
      "uid": 0,
      "labels": ["beauty", "grocery"]
    },
    {
      "uid": 1,
      "labels": ["pension"]
    },
    {
      "uid": 2,
      "labels": ["tax"]
    }
  ]

Labeling Result List is an array containing objects described by the following fields:

Field Description Example value
uid Unique ID of the labeled transaction “batch001-26-01-2018__-124.00_1”
labels List of labels assigned to that transaction. Can be empty if no labels were assigned. ["beauty", "grocery"]

External Labeling Command States

Consult the table below for an explanation of the values of different command states.

State Description
in_progress The command is being executed
successful The command has finished successfully, and the response contains the labeling result
error Command execution failed due to a known scenario, see: Error Handling
fatal Command execution failed due to unexpected reasons, see: Error Handling

External Labeling Error Response

Example

{
  "id": 123,
  "state": "error",
  "exception": {
    "name": "JobsQuotaExceeded",
    "message": "User exceeds maximum number of simultaneous tasks, please wait for other tasks to finish and try again."
  }
}

An error response for External Labeling doesn’t follow the standard JSON Error Response template. It’s a JSON object with the command field with the following fields:

Field Description Example value
id ID of the External Labeling command to be used in the External Labeling Result endpoint 752468123
state Command status. See: External Labeling Command Status “fatal”
exception Exception details in case an error occurs. See: External Labeling Error Response {"name":"ExampleException","message":"Example message"}

The exception object is described by the following fields:

Field Availability Description
name always Name of the error as per the Errors list section
message optional More detailed information on the error

The error names are based on a catalog of possible errors, whereas the error message may be generated, is not constant and should not be used for any automatic processing.

Other API features

Health Check

Used to ensure that the Kontomatik server is up.

Request

Request

curl --get \
  https://test.api.kontomatik.com/isItWorking

GET /isItWorking

This is the only request that does not require the API key.

Response

I am working.

Response

If the server is up, the response will include a plain text: I am working..

Digitally Signed Responses

Request

curl -i \
  --header "Accept-Signature: SHA256withRSA" \
https://test.api.kontomatik.com/isItWorking

Response (example)

HTTP/2 200
date: Wed, 05 Jul 2023 12:25:25 GMT
content-type: text/plain;charset=UTF-8
content-length: 13
request-id: 8fa66651-2d2d-11b2-8233-7f60d50105d9
x-signature: QXwQATYFwA8+VrbtJs+2tc8yZv+bbAmCgSgKykrr8TqNvaZ4ak93O8aTHSgn1i88Z7/sWg0r4llBH4fhAPkKQq1yjPvFVhZVBdrf26VRpX69Q7Eam16cQJpPhNlZRhAvN8apPctLxSZ8X4OECOorL8WwAwN3xTCgpYGu4p/e1kjdFW0+nee8HLmJUMrmAeS0DpbgKiKLsaY3DEXuoMmiI8IOUuXs4gYrT5/Wf22ZZDUiQQs5ovdhmjMzyXlRCN8NI8J7WkTRrOtxEl2PCfLVKjkg8y0FJnZtg5YhX7xr8tXzd4JbCsihHYg+GnvbedaavJwpldWdmBvWoDZ00zG66Q==
x-signature-cert-url: https://get.kontomatik.com/certificates/kontomatik_signing_2023_qsealc.cer
content-language: en-US

I am working.

To receive signed responses, add the following header in your requests:

Accept-Signature: SHA256withRSA

Responses will contain additional headers:

Header Description
X-Signature Base64-encoded signature of the response body
X-Signature-Cert-Url URL of the public certificate which can be used to verify the response

Code example

#!/bin/bash

# Send the request and save the response
curl -i --header "Accept-Signature: SHA256withRSA" https://test.api.kontomatik.com/isItWorking > http_response

# Extract the signature and the URL of the certificate
signature=$(awk -F": " '/x-signature:/{print $2}' http_response | tr -d '\r')
cert_url=$(awk -F": " '/x-signature-cert-url:/{print $2}' http_response | tr -d '\r')

# Extract the body
body=$(sed -n '/^\r$/,$p' http_response | tail -n +2)

# Download the certificate
curl -s $cert_url > kontomatik_certificate.pem

# Decode signature from Base64 and save it to a file
echo $signature | base64 --decode > received_signature

# Verify the signature
echo -n "$body" | openssl dgst -sha256 -verify <(openssl x509 -in kontomatik_certificate.pem -pubkey -noout) -signature received_signature

To verify the signature, please follow these steps:

  1. send a request with the Accept-Signature: SHA256withRSA header;
  2. extract the signature and the public certificate URL from the headers;
  3. extract the body of the response;
  4. download the certificate file*;
  5. decode the signature using Base64;
  6. verify the decoded signature against the response body using the certificate file.

See the provided example.

Please be sure to also confirm that the downloaded certificate file can be trusted using your preferred methods (e.g. CA verification, subject or keyring information).

AIS Catalog

Returns a list of banks and a list of available commands for each bank supported in Account Information Service.

Do not hardcode a once-fetched list into your application. You should call the endpoint every time the list is needed.

Request

Request

curl --get \
  --header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
  --data "country=pl" \
  https://test.api.kontomatik.com/v1/catalog.xml

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/get_command_catalog.xsd" status="200 OK">
  <targets>
    <target country="pl" name="KontoBankApi" institution="Kontobank" officialName="KontoBank" officialUrl="https://bank.kontomatik.com" beta="true" psd2="true">
      <supportedAccountTypes>
        <supportedAccountType name="Individual"/>
      </supportedAccountTypes>
      <commands>
        <command name="ImportCreditCardTransactionsCommand"/>
        <command name="ImportAccountTransactionsCommand"/>
        <command name="ReuseMultipleAccessCommand"/>
        <command name="ImportCreditCardsCommand"/>
        <command name="DefaultImportCommand"/>
        <command name="EnterCredentialCommand"/>
        <command name="ImportOwnersDetailsCommand"/>
        <command name="ImportAccountsCommand"/>
      </commands>
      <credentialsMetadata>
        <credentialMetadata kind="API_SETUP">
          <name></name>
          <supported>true</supported>
          <asterisked>false</asterisked>
        </credentialMetadata>
      </credentialsMetadata>
    </target>
    <!-- ... more targets ... -->
  </targets>
</reply>

GET /v1/catalog.xml

Parameters:

Parameter Requirement Description
country optional Filters banks by the country they operate in
Accepted values: all, cz, ee, es, it, lt, lv, pl, pt, ro, se
Default value: pl

Response

The response includes a <targets> list which includes <target> nodes containing attributes and nodes within.

Please note that the response will also include other attributes and nodes not described below, but they shouldn’t be ever used in your implementation.

attributes

Attribute Availability Description
country always Country where the bank operates
name always Name of the target
institution always Name of the institution
officialName always Official name of the bank
officialUrl always Bank main website address
beta possibly none Information on whether the target is new and/or unstable yet
psd2 possibly none Information on whether the target is working based on PSD2 API connection

nodes

Node Availability Description
supportedAccountTypes always See: supportedAccountTypes section
commands always See: commands section

supportedAccountTypes section

The <supportedAccountTypes> node is a list of account types supported via the target. It may include multiple <supportedAccountType> elements with values describing the types.

Possible values:

Type Description
Individual Personal accounts not belonging to legal entities
SoleTrader Accounts belonging to small companies, usually sharing the online banking system with people who use personal accounts
Corporate Accounts belonging to big companies and enterprises, which usually have their own dedicated online banking system

Please note that this information is usually inferred from past user support interaction or taken from the bank’s API documentation. In some cases it will not reflect the actual list of supported account types.

commands section

The <commands> node is a list of available commands for the given target. It contains one or more <command> elements, each with a name attribute that identifies the command.

Available commands are as follows:

Command name Command enables
EnterCredentialCommand Logging in and authorization by the user via the SignIn Widget
DefaultImportCommand Default Import command
ImportOwnersDetailsCommand
ImportAccountsCommand
ImportAccountTransactionsCommand
ImportCreditCardsCommand
ImportCreditCardTransactionsCommand
SignOutCommand Sign Out command in Advanced Import
ReuseMultipleAccessCommand
DeleteMultipleAccessConsentCommand Remove Multiple Access command

PDF Catalog

Returns a list of banks we support in PDF Statements Parsing.

Do not hardcode a once-fetched list into your application. You should call the endpoint every time the list is needed.

Request

Request

curl --get \
  --header "X-Api-Key:YOUR_LONG_API_KEY_HERE" \
  --data "country=pl"
  https://test.api.kontomatik.com/v1/parser-catalog.xml

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://developer.kontomatik.com/schema/v1/get_parser_catalog.xsd" status="200 OK">
    <targets>
        <target country="PL" name="MBank" institution="MBank" officialName="mBank"> </target>
        <target country="PL" name="Bos" institution="Bos" officialName="BOŚ Bank"> </target>
        <target country="PL" name="KontoBank" institution="KontoBank" officialName="KontoBank"> </target>
        <!-- other targets -->
    </targets>
</reply>

GET /v1/parser-catalog.xml

Parameters:

Parameter Requirement Description
country optional Filters banks by the country they operate in.
Accepted values: all, cz, ee, es, it, lt, lv, pl, pt, ro, se
Default value: pl

Response

The response includes a <targets> list which includes <target> nodes with the following attributes:

Attribute Availability Description
name always Technical identifier of the parser
officialName always Official name of the bank

Data Summary Catalog

Returns a list of available Data Summary categories you can use in the request for summaries.

Request

Request

curl --get \
  --header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
  https://test.api.kontomatik.com/v1/owner-summary-catalog

Request

curl --get \
  --header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
  https://test.api.kontomatik.com/v1/accounts-summary-catalog

GET /v1/owner-summary-catalog

GET /v1/accounts-summary-catalog

The endpoints don’t accept any parameters.

Response

Example

{
    "requestId": "cc8676e8-2d37-11b2-9bb0-317cde85e59b",
    "content": [
        "balance",
        "label",
        "ibans",
        "negativeBalancePerTransaction",
        "activeSinceAtLeast",
        "daysInRange",
        "topIncomingInvoiceParties",
        "allTransactions",
        "directDebitAccounts",
        "positiveBalancePerTransaction",
        "balanceEndOfDay",
        "owners",
        "balancePerTransaction",
        "bailiffWithoutCompensation"
    ]
}

The content node in the response object will contain a list (Array) of category names to be used in Data Summary requests. Please see the example on the right.

Error handling

In case there’s an error during the handling of the API request, instead of the expected response as described in the documentation, the endpoint will return an Error Response.

Depending on the endpoint and the HTTP code (see: API conventions), the Error Response will follow a specific template: XML Error Response or a JSON Error Response.

The error names are based on a catalog of possible errors, whereas the error message may be generated, is not constant and should not be used for any automatic processing.

For errors like 429 or 5xx we suggest implementing additional request strategies such as queues and retry logic. We recommend this article for finding the best approach.

XML Error Response

Example

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://developer.kontomatik.com/schema/v1/command.xsd" status="200 OK" user="user-test" ownerExternalId="12345" responseTimestamp="2024-01-01T08:00:00Z">
  <command id="987654321" state="fatal" name="DefaultImportCommand"
           target="KontoBank_es"
           institution="KontoBank">
    <progress>
      <value>0</value>
    </progress>
    <exception name="KontoXBug">
      <message>Something went wrong with fetching data from bank. Please consult with Kontomatik support team.</message>
      <tag>KontoBank:DefaultImport:-2064441338</tag>
    </exception>
  </command>
</reply>

<?xml version="1.0" encoding="utf-8"?>
<reply status="400 Bad Request" user="user-test" responseTimestamp="2024-01-01T08:00:00Z">
   <exception name="InvalidStatementMetadata">
      <message>Metadata does not match any known template</message>
      <statementId>987654321</statementId>
   </exception>
</reply>

For API endpoints returning data in the XML format, the errors are provided in the <exception> structure which can appear directly in the <reply> node or under a <command> (if the response is related to importing commands in AIS).

<exception> contains the following:

Element Availability Description
name always [exception attribute] Name of the error as per the Errors list section
message optional More detailed information on the error
tag optional A tag assigned to KontoXBug responses. Problems with the same root cause will have the same value assigned.
statementId optional, PDF only ID assigned by Kontomatik to the processed document.
failedVerifications optional, PDF only List of possible document modification indicators discovered during the parsing of a provided statement.

JSON Error Response

Example

"exception": {
  "name": "InvalidArgument",
  "message": "Unrecognized category: balanced"
}

For API endpoints returning data in the JSON format, the errors are provided in the exception object of the main response, which is characterized by the following fields:

Field Availability Description
name always Name of the error as per the Errors list section
message optional More detailed information on the error

Errors list

Errors and exceptions are divided by types into the following categories:

Category Description
Integration errors Errors caused by invalid implementation of your API integration.
Errors caused by external factors Errors caused by external errors beyond Kontomatik’s control, for example bank API instability. Most of these will not occur again if you wait a while and repeat the command or ask your client to go through the process again.
User actions Errors caused by the end-user or related to their banking system activity.
Most of these will be returned in the widgets when the onError callback gets triggered.
PDF validation Indicates a correct API response, but the parsed documents returned validation errors indicating an unsupported file, layout changes introduced by the bank not implemented yet or potential tampering attempt by the user
Bugs in Kontomatik system Bugs caused by Kontomatik systems incorrectly handling a specific scenario, see: Kontomatik bugs

Below you’ll find the complete list of errors assigned to their respective categories. Some errors can appear in multiple categories depending on a possible root cause of the issue.

Name Category Description
CommandNotAvailable Integration The command is not available for the selected target
InvalidCommandId Integration Invalid command identifier (e.g. if client keeps polling a command that entered in a final state, after 60 seconds we return InvalidCommandId)
InvalidOwnerExternalId Integration Invalid identifier of the owner
NotSignedIn Integration The user has not yet signed in during this session
AlreadySignedIn Integration, User The user already signed in during this session
SessionExpired Integration, User The session with the online transaction system has expired, your system probably takes too long between the user logging in and calling for import
DefaultImportAlreadyExecuted Integration Default Import has already been executed once in this session, subsequent execution failed
InvalidIban Integration Invalid bank account number provided to fetch account transactions (e.g. empty, incorrect syntax)
InvalidCardNumber Integration Invalid card number provided to fetch credit card transactions (e.g. empty, incorrect syntax)
InvalidTarget Integration Invalid target identifier
InvalidSessionId Integration Invalid session identifier (e.g. client calls the production endpoint with a session created on the test environment)
InvalidSessionIdSignature Integration One or both of sessionId and sessionIdSignature passed parameters were malformed
InvalidSince Integration Invalid start date
InvalidArgument Integration The arguments passed to a command are either invalid or malformed
InvalidMultipleAccessId Integration, External Multiple Access expired or provided multipleAccessId is otherwise invalid
FileNotFound Integration Requested file doesn’t exist or has already been removed.
JobsQuotaExceeded Integration Your app has started too many imports simultaneously. Wait 10-15 seconds to allow some of the imports to finish and resubmit the command. If you get the same error, repeat the process until the command is accepted.
NoDataToCalculateScore Integration, External No data for scoring calculation (e.g. if the client does not have any transactions or they haven't been imported yet)
ClientScoringNotSupportedError Integration Scoring is disabled on your account
AisLicenseNotFound Integration No PSD2 AIS license has been assigned to your account
InvalidIpAddress Integration Provided IP address is incorrect
InvalidLabelingCommandId Integration Invalid commandId parameter provided to fetch labeling results
InvalidTimestampRange Integration The time range you have picked is invalid
InvalidUserName Integration Provided username is invalid
InvalidUserSessionId Integration Provided sessionid is incorrect
MissingArgument Integration Required argument for this request is missing
UserNotActivated Integration The user has not yet been activated
AccountNotFoundInDb Integration, External Requested account has not been found in the database
CreditCardNotFoundInDb Integration, External Requested credit card has not been found in the database
CommandAlreadyExecuted Integration, User This command has already been executed
InvalidEmail Integration, User Provided e-mail address is incorrect
IOException External Network issue between Kontomatik and the bank
InternalLabelingError External There was an error with the labeling system
MultipartException External Multipart resolution has failed
ApplicationOverloaded External The application is currently overloaded
UncheckedIOException External Network issue between Kontomatik and the bank
ConcurrentSessionsLimitExceed External, User User hasn’t logged out from the banking system before using Kontomatik or has logged in before the Kontomatik process ended
InsufficientOwnerPermission External, User The end-user doesn't have sufficient privileges to grant access to the requested account. It typically happens for accounts that have multiple owners. Kontomatik doesn't support such accounts.
MissingInformation External The statement does not contain information necessary to process it (e.g. currency)
ServiceTemporarilyUnavailable External Banking system is temporarily unavailable
ServiceMaintenance External Banking system is undergoing maintenance
MultipleAccessLimitExceeded External The number of imports allocated for 24 hours has been exceeded
AccessBlocked User, External Access to the account is blocked
AccessTemporarilyBlocked User, External Access to the account is temporarily blocked and expected to auto-unlock after a while
ManualActionRequired User, External A manual action in the online transaction system is required, e.g. accepting changes in terms of use
InvalidCredentials User End-user entered an invalid credential
TargetCredentialsMismatch User End-user entered credentials that match a different, possibly unsupported, transactional system. For example, company credentials are used instead of individual account credentials.
UnsupportedLoginMethod User, External This login scenario is not supported by Kontomatik
UnsupportedLanguage User, External The language of the bank UI is not supported
PSD2AuthProcessInterrupted User, External Indicates that the authorization process has been abruptly stopped by an external factor or agent, very often the end-user himself: rejecting consents on the bank page or providing bad credentials are common causes of this error.
UserAbortedAuthorization User The end-user closed the bank redirection pop-up window.
MaxUploadSizeExceededException User Size of the file you are trying to upload is too big
InvalidCardId User Invalid cardId parameter provided to fetch credit card transactions (e.g. empty, incorrect syntax)
MaxFilesSizeExceeded User File size limit has been exceeded by the user
LoginTimedOut User Process of authentication has timed out, e.g. user took too long going through the process
UnsupportedBrowser User The user is using an unsupported browser or outdated browser version
InvalidPdfTarget PDF validation Chosen statement target is different from the uploaded file or the target is unavailable
DoesntLookLikePDF PDF validation The file is not a PDF
FilePasswordProtected PDF validation Uploaded file is encrypted with a password and can't be parsed.
UnrecognizedStatementLayout PDF validation The bank was recognized, but the layout was not and is possibly not supported
InvalidStatementSignature PDF validation The digital signature is incorrect
UnrecognizedTarget PDF validation The bank couldn’t be determined based on the file metadata
InvalidStatementMetadata PDF validation The bank was recognized, but some metadata was changed
InvalidStatementConsistency PDF validation Some transaction and balance values were not consistent and possibly modified
InvalidStatementFonts PDF validation Fonts appearing on the statement are not whitelisted for this layout
InvalidStatementLogo PDF validation Bank logo on the statement is not whitelisted for this layout
UnsupportedStatement PDF validation The bank and the layout were recognized but aren’t supported by Kontomatik
PotentiallyModified PDF validation Contains a tamperReport list, which includes all the validation exceptions encountered.

Kontomatik bugs

In case the returned exception is named KontoXBug, consider the following reasons:

We monitor those bugs on our side and automatically look into cases that happen most frequently or in larger quantities.

Whenever this bug happens to you even after multiple attempts for one client or for multiple clients in the same scenario (e.g. in the same bank with the same error message), please report it to our Support.

Resources

XML Schemas (XSD)

Below you’ll find links to XSD files that describe our public XML-based endpoints.

In your implementation do not use those files to verify XML responses against XSDs - if you require validation, please follow the links that appear in the XML responses dynamically. The XSD files may change without notice when it comes to extensions or internally used elements.

Public list of XSD:

https://developer.kontomatik.com/schema/v1/401.xsd https://developer.kontomatik.com/schema/v1/403.xsd https://developer.kontomatik.com/schema/v1/404.xsd https://developer.kontomatik.com/schema/v1/aggregates.xsd https://developer.kontomatik.com/schema/v1/command.xsd https://developer.kontomatik.com/schema/v1/create_mock_session.xsd https://developer.kontomatik.com/schema/v1/default_import.xsd https://developer.kontomatik.com/schema/v1/errors.xsd https://developer.kontomatik.com/schema/v1/get_command_catalog.xsd https://developer.kontomatik.com/schema/v1/get_data.xsd https://developer.kontomatik.com/schema/v1/get_owner_features.xsd https://developer.kontomatik.com/schema/v1/get_owner_scores.xsd https://developer.kontomatik.com/schema/v1/get_parser_catalog.xsd https://developer.kontomatik.com/schema/v1/import_accounts.xsd https://developer.kontomatik.com/schema/v1/import_account_transactions.xsd https://developer.kontomatik.com/schema/v1/import_credit_card_transactions.xsd https://developer.kontomatik.com/schema/v1/import_credit_card.xsd https://developer.kontomatik.com/schema/v1/import_owners_details.xsd https://developer.kontomatik.com/schema/v1/reuse_multiple_access.xsd https://developer.kontomatik.com/schema/v1/statement.xsd https://developer.kontomatik.com/schema/v1/types.xsd https://developer.kontomatik.com/schema/v1/get_document_file.xsd https://developer.kontomatik.com/schema/v1/get_documents.xsd

Integration examples

The following are unofficial projects that may help develop your own integration. Kontomatik does not officially support these projects and will not offer any assistance or be responsible for any issues caused by the software.

Coverage

List of supported countries, banks and services can be found in this file.

Read more

Consider the following Kontomatik pages to find out more:

Deprecated features

The following features are not recommended for implementation as they are likely to be removed in the future.

Advanced Import

Advanced import methods allow you to fetch owner data from banks via the Account Information Service. Each method imports only partial results so you can decide not to continue importing at any stage.

The experience shows that most implementations of this option are incorrect and cause many problems for our clients, which is why we decided not to develop it further. Any new features available in Default Import might be absent in Advanced Import.

Importing methods described below are commands that need to be polled using the Get Import Result endpoint.

After having imported all data, you can use the Sign Out command to end the Kontomatik session with the bank.

Import Owners

Request

Request

curl \
  --header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
  --data "sessionId=999999" \
  --data "sessionIdSignature=ffff....ffff" \
  https://test.api.kontomatik.com/v1/command/import-owners.xml

POST /v1/command/import-owners.xml

Required parameters:

Parameter Description
sessionId ID of the session assigned by Kontomatik
sessionIdSignature Signature assigned to the sessionId ensuring protection against enumeration attacks

Response

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/command.xsd" status="202 Accepted">
  <command id="653643" state="setup" name="ImportOwnersCommand">
  <progress><value>0</value></progress>
  </command>
</reply>

Final result of polling for this command status

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/import_owners_details.xsd" status="200 OK">
<command id="653643" state="successful" name="ImportOwnersCommand" target="Alior" institution="Alior">
    <progress><value>1</value></progress>
    <result>
      <owners>
        <owner>
          <kind>OWNER</kind>
          <name>Jan Witkacy Kowalski</name>
          <address>Krótka 8, Wąchock</address>
          <polishNip>1258882345</polishNip>
          <phone>694234567</phone>
          <email>jan.kowalski@wachock-mail.pl</email>
          <citizenship>Kazakhstan</citizenship>
          <nationality>Polskie</nationality>
          <personalDocumentType>Passport</personalDocumentType>
          <personalDocumentNumber>FGH123456</personalDocumentNumber>
          <birthDate>1960-02-29</birthDate>
          <polishRegon>121260111</polishRegon>
        </owner>
      </owners>
    </result>
  </command>
</reply>

After calling the endpoint, you will receive a command identifier in the id attribute of the <command> node. You need to save this ID to poll the Get Import Result endpoint.

Once the command finishes successfully, Get Import Result will contain a <result> node with the Owners section inside.

Import Accounts

Request

Request

curl \
  --header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
  --data "sessionId=999999" \
  --data "sessionIdSignature=ffff....ffff" \
https://test.api.kontomatik.com/v1/command/import-accounts.xml

POST /v1/command/import-accounts.xml

Required parameters:

Parameter Requirement Description
sessionId obligatory ID of the session assigned by Kontomatik
sessionIdSignature obligatory Signature assigned to the sessionId ensuring protection against enumeration attacks
fast optional true by default, returns data faster without additional information that would be typically extracted from transactions

Response

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/command.xsd" status="202 Accepted">
  <command id="653643" state="setup" name="ImportAccountsCommand">
</reply>

Final result of polling for this command status

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/import_accounts.xsd" status="200 OK">
<command id="653643" state="successful" name="ImportAccountsCommand" target="Alior" institution="Alior">
    <progress><value>1</value></progress>
    <result>
      <accounts>
        <account>
          <name>eKONTO</name>
          <iban>PL32114020040000320250132522</iban>
          <currencyBalance>1467.39</currencyBalance>
          <currencyFundsAvailable>1407.39</currencyFundsAvailable>
          <currencyName>PLN</currencyName>
          <activeSinceAtLeast>2000-02-28</activeSinceAtLeast>
          <directDebit available="true"/>
          <owners>
            <owner>
              <name>Jan Kowalski</name>
              <address>Kwiatowa 8/97 Warszawa  PL</address>
                <kind>OWNER</kind>
            </owner>
            <owner>
               <name>Adam Nowak</name>
               <address>Robocza 1 M.14 Warszawa PL</address>
            </owner>
          </owners>
        </account>
        <!-- ... more accounts ... -->
      </accounts>
    </result>
  </command>
</reply>

After calling the endpoint, you will receive a command identifier in the id attribute of the <command> node. You need to save this ID to poll the Get Import Result endpoint.

Once the command finishes successfully, Get Import Result will contain a <result> node with the Accounts section inside.

Import Account Transactions

You need to call this command separately for each account found in the response of the Import Accounts command.

Request

Request

curl \
  --header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
  --data "sessionId=999999" \
  --data "sessionIdSignature=ffff....ffff" \
  --data "iban=PL00000000000000000000000000" \
  --data "since=2015-12-01" \
https://test.api.kontomatik.com/v1/command/import-account-transactions.xml

POST /v1/command/import-account-transactions.xml

Required parameters:

Parameter Description
sessionId ID of the session assigned by Kontomatik
sessionIdSignature Signature assigned to the sessionId ensuring protection against enumeration attacks
iban IBAN of the account for which you want to fetch transactions. Use the iban value from Import Accounts.
since Date in the YYYY-MM-DD format. The earliest date from which you want the transactions to be imported.
The date parameter must be set within a maximum range of five years. With any dates beyond this limit it will be automatically trimmed to five years in the past, or to the one passed in maxImportDate

Response

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/command.xsd" status="202 Accepted">
  <command id="653643" state="setup" name="ImportAccountTransactionsCommand">
    <progress><value>0</value></progress>
  </command>
</reply>

Final result of polling for this command status

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/import_account_transactions.xsd" status="200 OK">
<command id="653643" state="successful" name="ImportAccountTransactionsCommand" target="Alior" institution="Alior">
    <progress><value>97</value></progress>
    <result>
      <moneyTransactions>
        <moneyTransaction>
          <transactionOn>2012-06-28</transactionOn>
          <bookedOn>2012-06-30</bookedOn>
          <currencyAmount>20.00</currencyAmount>
          <currencyBalance>230.00</currencyBalance>
          <title>Return for beer in a pub</title>
          <party>Jan Kowalski</party>
          <partyIban>PL68249000050000400075212326</partyIban>
          <kind>EXTERNAL INCOMING TRANSFER</kind>
          <status>DONE</status>
          <labels>
            <label><!-- label type --></label>
            <!-- ... more labels ... -->
          </labels>
        </moneyTransaction>
        <!-- ... more transactions ... -->
      </moneyTransactions>
    </result>
  </command>
</reply>

After calling the endpoint, you will receive a command identifier in the id attribute of the <command> node. You need to save this ID to poll the Get Import Result endpoint.

Once the command finishes successfully, Get Import Result will contain a <result> node with the Account Transactions section inside.

Import Credit Cards

Request

Request

curl \
  --header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
  --data "sessionId=999999" \
  --data "sessionIdSignature=ffff....ffff" \
  https://test.api.kontomatik.com/v1/command/import-credit-cards.xml

POST /v1/command/import-credit-cards.xml

Required parameters:

Parameter Description
sessionId ID of the session assigned by Kontomatik
sessionIdSignature Signature assigned to the sessionId ensuring protection against enumeration attacks

Response

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/command.xsd" status="202 Accepted">
  <command id="653643" state="setup" name="ImportCreditCardsCommand"/>
</reply>

Final response for this command status (scraper target example)

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/import_credit_card.xsd" status="200 OK">
<command id="89817419" state="successful" name="ImportCreditCardsCommand">
  <progress><value>2</value></progress>
    <result>
      <creditCards>
        <creditCard>
          <name>Visa</name>
          <cardId>1234 **** **** 1234</cardId>
          <iban>PL32114020040000320250132522</iban>
          <number>1234 **** **** 1234</number>
          <currencyBalance>-2467.39</currencyBalance>
          <currencyName>PLN</currencyName>
          <owners>
            <owner>
              <name>Jan Kowalski</name>
              <address>Kwiatowa 8/97 Warszawa  PL</address>
              <kind>OWNER</kind>
            </owner>
            <owner>
               <name>Adam Nowak</name>
               <address>Robocza 1 M.14 Warszawa PL</address>
            </owner>
          </owners>
          <limit>5000.00</limit>
          <interest>20</interest>
          <dueDate>2013-10-26</dueDate>
        </creditCard>
       <!-- ... more credit cards ... -->
       </creditCards>
    </result>
  </command>
</reply>

Final response for this command status (PSD2 API target example)

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/import_credit_card.xsd" status="200 OK">
<command id="89817419" state="successful" name="ImportCreditCardsCommand">
  <progress><value>2</value></progress>
    <result>
      <creditCards>
        <creditCard>
          <name>Visa</name>
          <cardId>PL32114020040000320250132522</cardId>
          <iban>PL32114020040000320250132522</iban>
          <currencyBalance>-2467.39</currencyBalance>
          <currencyName>PLN</currencyName>
          <owners>
            <owner>
              <name>Jan Kowalski</name>
              <address>Kwiatowa 8/97 Warszawa  PL</address>
              <kind>OWNER</kind>
            </owner>
            <owner>
               <name>Adam Nowak</name>
               <address>Robocza 1 M.14 Warszawa PL</address>
            </owner>
          </owners>
          <limit>5000.00</limit>
          <interest>20</interest>
          <dueDate>2013-10-26</dueDate>
        </creditCard>
       <!-- ... more credit cards ... -->
       </creditCards>
    </result>
  </command>
</reply>

After calling the endpoint, you will receive a command identifier in the id attribute of the <command> node. You need to save this ID to poll the Get Import Result endpoint.

Once the command finishes successfully, Get Import Result will contain a <result> node with the Credit Cards section inside.

Import Credit Card Transactions

You need to call this command separately for each credit card found in the response of the Import Credit Cards command.

Request

Request

curl \
  --header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
  --data "sessionId=999999" \
  --data "sessionIdSignature=ffff....ffff" \
  --data "since=YYYY-MM-DD" \
  --data "cardId=2345***32" \
https://test.api.kontomatik.com/v1/command/import-credit-card-transactions.xml

POST /v1/command/import-credit-card-transactions.xml

Required parameters:

Parameter Description
sessionId ID of the session assigned by Kontomatik
sessionIdSignature Signature assigned to the sessionId ensuring protection against enumeration attacks
cardId ID of the credit card for which you want to fetch transactions. Use the cardId value from Import Credit Cards.
since Date in the YYYY-MM-DD format. The earliest date from which you want the transactions to be imported.
The date parameter must be set within a maximum range of five years. With any dates beyond this limit it will be automatically trimmed to five years in the past, or to the one passed in maxImportDate

Response

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/command.xsd" status="202 Accepted">
  <command id="653643" state="setup" name="ImportCreditCardTransactionsCommand"/>
</reply>

Final response for this command status

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/import_credit_card_transactions.xsd" status="200 OK">
  <command id="89817986" state="successful" name="ImportCreditCardTransactionsCommand">
    <progress><value>3</value></progress>
    <result>
      <moneyTransactions>
        <moneyTransaction>
          <transactionOn>2017-08-10</transactionOn>
          <bookedOn>2017-08-11</bookedOn>
          <currencyAmount>-20.00</currencyAmount>
          <currencyBalance>1100.99</currencyBalance>
          <title>Zwrot za Sylwestra</title>
          <party>Jan Kowalski Dunikowskiego 23B, 01-200 Warszawa</party>
          <partyIban>PL83130000002076700146310001</partyIban>
          <kind>PRZELEW ZEWNĘTRZNY</kind>
          <labels>
            <label>internal</label>
          </labels>
        </moneyTransaction>
        <!-- ... more transactions ... -->
      </moneyTransactions>
    </result>
  </command>
</reply>

After calling the endpoint, you will receive a command identifier in the id attribute of the <command> node. You need to save this ID to poll the Get Import Result endpoint.

Once the command finishes successfully, Get Import Result will contain a <result> node with the Credit Card Transactions section inside.

Sign Out

Logs out the user from the transactional system. Assuming that the bank supports the sign out command, it is advised to use it once you have imported all data to prevent blocking the online banking website for the end user.

Request

Request

curl \
  --header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
  --data "sessionId=999999" \
  --data "sessionIdSignature=ffff....ffff" \
https://test.api.kontomatik.com/v1/command/sign-out.xml

POST /v1/command/sign-out.xml

Required parameters:

Parameter Description
sessionId ID of the session assigned by Kontomatik
sessionIdSignature Signature assigned to the sessionId ensuring protection against enumeration attacks

Response

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/layout.xsd" status="200 OK">
</reply>

The response is an empty <reply> element. See the provided example.

code