NAV
code

Introduction

Overview

The Kontomatik PDF parsing API enables checking PDF statements against tampering attempts and parsing them to deliver clear banking data for credit scoring.

The common use case of this API is for assessing end-user creditworthiness. As such, the service requires user-uploaded PDF statements.

Please note that no end-user GUI for file upload is provided. You are expected to develop a user interface on your own.

Anti-tampering verification

Verification is done on every file upload via POST /v1/statement.xml. The following things are automatically checked against expected values:

Clients can also use for verification the following values in the returned data:

Supported targets

The PDF-parsing technology is currently available only in Poland. Coverage details are available here:

PDF-Parsing API - supported targets

API Conventions

Get API access

Authentication

Kontomatik API is protected by two-factor authentication:

Test environment

Start with the test environment to test and develop your credit scoring app. The test environment is fully-featured and unrestricted, returning real data. We kindly ask you to not use it for your production deployments.

The test API endpoint is:

https://test.api.kontomatik.com/

Request test API access.

Production environment

The production API endpoint is:

https://api.kontomatik.com/

Once the agreement is signed, please request your production API access at [email protected]. Use your official company e-mail and provide:

Tutorial

We recommend you to get API access before reading further, if you haven’t done so already.

For the purpose of this tutorial we assume that you are a lender (for example a bank or a lending company) and you need the data as input for your credit scoring engine.

Example flow:

API reference

Parse PDF statement

Test request

curl -F "apiKey=<YOUR_API_KEY_FILE" \
     -F "pdfAsBase64=<YOUR_BASE64_ENCODED_PDF_FILE" 
     https://test.api.kontomatik.com/v1/statement.xml

Response

<?xml version="1.0" encoding="utf-8"?>
<reply status="200 OK">
  <result>
    <statement>
      <owner>John Fitcha<owner>
      <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>
            <owner>John Fitcha</owner>
            <activeSinceAtLeast>2014-11-12</activeSinceAtLeast>
            <currencyBalance>1467.39</currencyBalance>
            <currencyName>GBP</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>
      <!-- ... more targets if statements came from different banks ... -->
    </statement>
  </result>
</reply>

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

The command recognizes the source bank, parses the file, verifies authenticity and reads the owner, period, account(s) and transactions.

The command takes one PDF file. To aggregate multiple PDF files, call it several times with the same ownerExternalId parameter.

HTTP Request

POST /v1/statement.xml

Parameters

Parameter Default Description
apiKey obligatory API key
pdfAsBase64 obligatory PDF file encoded as Base64.
ownerExternalId optional data owner identifier (for example your internal credit-application-id). Data will be grouped around this parameter so that it can later be fetched together. If omitted, data won’t be persisted to the database and must be retrieved immediately after an individual command completion.

Data returned

Description of the <statement> element.

Data Availability Description
owner guaranteed the first and the last name of the owner
period guaranteed the start and end dates of the statement as read from the PDF
type guaranteed a type of statement, either MONTHLY_STATEMENT or ACCOUNT_HISTORY
target guaranteed the originating bank of the statement

Description of the <target> element.

Data Availability Description
name guaranteed the name of a target bank as parsed from the submitted statement(s)
accounts guaranteed parent element containing data abstracts for each of the individual bank accounts

Description of the <account> element.

Data Availability Description
name optional internal bank descriptor for this account type
iban guaranteed full account number (with country code for ‘true’ IBAN accounts)
owner guaranteed the name of the account owner
activeSinceAtLeast guaranteed the date when the account was opened or the date of the oldest transaction found
currencyBalance guaranteed account balance at the end of the period
currencyName possibly missing the 3-letter acronym for the native currency of the bank account
moneyTransactions guaranteed list of money transactions for the given period

Description of the <moneyTransaction> element.

Data Availability Description
transactionOn possibly missing actual transaction date. If missing, it’s guaranteed that <bookedOn> element will be present.
bookedOn possibly missing transaction’s booking date (sometimes even 10 days after the actual transaction date). If missing, it’s guaranteed that <transactionOn> element will be present.
currencyAmount guaranteed transaction amount expressed in the account currency (it can be different from the currency of the country where the bank is located)
currencyBalance possibly missing account balance expressed in the account currency
partyIban possibly missing full account number of the other party of the transaction. The field is often present but not in all cases. A small number of banks do not include this information.
party possibly missing name and surname of the other party of the transaction
kind possibly missing transaction type, as presented in the online transaction system (e.g. “INTEREST COMPOUNDING”)

Fetch aggregated data

HTTP Request

<reply status="200 OK">
  <owner externalId="653643">
    <target name="MBank">
      <owners>
      </owners>
      <accounts>
        <account>
          <name>eKONTO</name>
          <iban>PL32114020040000320250132522</iban>
          <currencyBalance>1467.39</currencyBalance>
          <currencyName>PLN</currencyName>
          <owner>Jan Kowalski, Adam Nowak</owner>
          <activeSinceAtLeast>2000-02-28</activeSinceAtLeast>
          <moneyTransactions>
            <moneyTransaction>
              <id>666</id>
              <transactionOn>2012-06-28</transactionOn>
              <bookedOn>2012-06-30</bookekOn>
              <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>
              <uid>2012-06-30__20.00</uid>
            </moneyTransaction>
            <!-- ... more transactions ... -->
          </moneyTransactions>
        </account>
        <!-- ... more accounts ... -->
      </accounts>
    </target>
  </owner>
</reply>

GET /v1/data.xml?ownerExternalId=653643

Returns all imported and aggregated data associated with the user identified by an ownerExternalId.

Parameter Default Description
apiKey obligatory API key
ownerExternalId obligatory parameter to identify the data owner (here: 653643)
only optional an optional parameter to filter the results returned by the command. It can have one of the following values: owners, accounts, transactions

The command returs a response with the same data fields as the Parse PDF statement command.

Push data

Push complete data

HTTP Request

POST /v1/push-data.xml

Response

<?xml version="1.0" encoding="utf-8"?>
<reply status="200 OK">
</reply>

Pushes complete data to the given customer service (as specified by the Kontomatik Service configuration file).

Parameter Default Description
apiKey obligatory API key
ownerExternalId obligatory parameter to identify the data owner

Push calculated aggregates

HTTP Request

POST /v1/push-aggregates.xml?periodMonths=12

Response

<?xml version="1.0" encoding="utf-8"?>
<reply status="200 OK">
</reply>

Pushes calculated aggregates to the given customer service (as specified by the Kontomatik Service configuration file).

Parameter Default Description
apiKey obligatory API key
ownerExternalId obligatory parameter to identify the data owner
periodMonths obligatory period in months that the aggregates will be calculated for, including current month

Error handling

We can divide possible errors into three categories:

Errors caused by incorrect API calls

Command execution may fail when there is a problem with the given ownerExternalId.

Response

<?xml version="1.0" encoding="utf-8"?>
<reply status="404 Not Found">
  <exception name="InvalidCommandId">
  </exception>
</reply>
Exception Description
InvalidOwnerExternalId Invalid identifier of the data owner

Errors caused by a problem with the uploaded PDF files

Exception Description
DoesntLookLikePDF The file is not a PDF (user mistake - probably uploaded some garbage file instead of a PDF)
UnrecognizedStatementLayout The file is a PDF but it doesn’t have the expected layout of a bank statement (user probably uploaded a different document, like a payment confirmation or an e-book)
InvalidStatementSignature The digital signature is incorrect (most likely the file was tampered by the user or, less likely, the target bank changed its signing certificate)
UnrecognizedTarget Target for PDF could not be defined. Either we don’t support PDF parsing for the chosen bank or the PDF has invalid metadata
InvalidStatementMetadata The PDF was edited/saved with a different tool than the one which the bank uses (most likely it was tampered by the user or, less likely, the bank changed its tool set for PDF generation)
InvalidStatementConsistency The PDF has inconsistent data. For example amounts don’t sum up or transaction dates don’t match the header period. This exception is also thrown if there are filters on statement that are not allowed. Most likely the file was tampered by the user or, less likely, consistency check doesn’t work correctly.
InvalidStatementFonts Fonts family, size or color are different than expected (either the PDF was edited by the user or the bank changed the fonts)
InvalidStatementLogo Bank logotype is different than expected (either the PDF was edited by the user or the bank changed its logotype picture)

Bugs in Kontomatik

The following should be considered bugs in the Kontomatik Service. Most likely, some edge case condition occurred and our software was not prepared for this. Kontomatik should be improved to cover this case. The error should be reported to Kontomatik, attaching the XML reply and logs of the application server.

Exception Description
KontoXPdfBug Some unhandled condition occurred. What to do: send us the whole XML response (which will include the stacktrace).