API overview
Intro
Our services are divided into two main categories:
The first category includes services that import data from different sources: bank integration, PDF parsing or an upload coming directly from our clients. Each action of getting the data from a single source is called an import.
Analytical Services however all work on data coming from the Importing Services. Some of them return simple calculations, others base their results on our Machine Learning solutions.
Apart from those main services, our API offers additional endpoints, e.g.:
- Aggregation - combines all data from different imports for a single owner and aggregates them together
- Catalogs - get a list of currently available assets, sources or categories within a specified service
- Data removal - by default Kontomatik retains imported data for 24 hours, however you can request its removal sooner if you’ve already downloaded it and won’t need to perform any additional operations on it via Kontomatik API
Importing Services
Account Information Service
Account Information Service lets you download end-user’s (owner) data from their live bank account. In order to do so, the user has to authorize access to their data via Kontomatik SignIn widget by signing into their account. Then, once the bank session has been established between Kontomatik and the bank, you can request a data import.
This service exists in two versions:
- Single Access - you can download the data one time only immediately after the user authorizes this action in their bank
- Multiple Access - you will receive a token that you can use later to create new bank sessions (refresh) and download the data again including newer transactions without the need of repeated user authorization
With the Single Access you can also optionally use the Auto import feature if you don’t want to implement a full integration with our API.
PDF Parsing
We offer a PDF parsing solution in Poland that lets you transform PDF files coming from banks into a machine-readable format. This solution is split into two features.
Both features are based on reverse engineering of the documents coming from banks.
PDF Statements Parsing
Statements Parsing transforms monthly bank statements and account history statements into XML format similar to what you would get from Account Information Service.
On top of that, we verify each document to find traces of potential user modification, preventing you from accepting fraudulent statements. This verification is mostly based on whitelists created over years of our experience with the documents.
You can later pass the extracted data through our Analytical Services.
PDF Confirmation Parsing
If you don’t want to parse the whole statements from users, you can just ask them to provide a single transaction confirmation PDF from the bank, e.g. containing confirmation of a salary transfer. As a result, after a tampering verification, you will receive the confirmation details in a JSON format.
This product is a bit different to our other Importing Services. While it also extracts data from PDFs, the data is not later added to our database, it can’t be aggregated with other data sources and it can’t be subject to our Analytical Services, except for the Labeling service.
Owner Upload
In case you possess financial data about owners from other sources than Kontomatik, but you want to use our Analytical Services, you can just upload this data to our servers.
Using the dedicated endpoint and providing the data in a specific format, this information will be integrated into our database just like any other data from our other Importing Services. This means that you can later get any analysis from our API that you would get for Account Information Service or PDF Parsing.
Aggregated Data
The aggregated data endpoint will return all data coming from different imports. In order to do so, you need to:
- Specify the
ownerExternalIdparameter in Widget or via API (depending on the specific service used) - Perform all necessary imports
- Call the endpoint for aggregated data
You can mix and match data from all available Importing Services*. It will be aggregated per “target” (usually technical bank name) and account number.
It is crucial to run this endpoint after all Importing Services have finished. Calling this endpoint earlier might result in erroneous data returned.
*Except for PDF Confirmation Parsing as it’s not based on our regular Owner Data Model.
Analytical Services
Labeling
Labeling is a service that analyzes transactions and assigns labels to them. You can think of these labels like hashtags in social media that describe posts in various ways. Each transaction can have multiple labels assigned or simply none of them.
If you have the labeling enabled, the labels will be automatically assigned to all your transactions when an Importing Service finishes. You will receive them with the import or when you fetch aggregated data.
Vendors Recognition
Similarly to the Labeling service, this one assigns company names to transactions and specifies which labels apply to them.
To receive the vendors alongside transactions, you just need to have this service enabled and you will get them within an import result or with aggregated data.
Scoring
Scoring is a service that calculates the probability of repayment for a given owner. It uses Machine Learning models and is based on our transaction data and repayment information we get from our partners.
Once all Importing Services have finished, you can call a dedicated endpoint to receive our calculation.
Data Summary
Data Summary is a simple aggregation tool that you can use to receive calculations in certain categories, either for the whole owner data or per account (called Owner Summary and Accounts Summary respectively) and you can get each of them in a monthly split (making them into a total of 4 endpoints).
After all Importing Services have finished, you can call one of the Data Summary endpoints, providing a list of categories to be calculated to receive the aggregates, e.g. balances, summary of outgoing or incoming transactions, summary for transactions with a specific label. Depending on the category, you will get metrics within, like totals, averages, daily averages etc.
Income confirmation
This service returns a set of aggregates focused on income only. Calling its endpoint after Importing Services, you will receive summarized income divided into 4 timespans:
- Average from last 90 days
- Totals from 1 month ago
- Totals from 2 months ago
- Totals from 3 months ago
Each of these are divided further into income categories, e.g. regular salary, extra pay (bonuses), alimony etc.
