Convert service

The function of the Convert service is to enrich one or more files with the following information:

• Categories
• Nace rev. 2 or SBI code
• Properties
• Information on the counterpart

Categories

Transactions are divided into categories. LinX uses a set of standard categories that are subdivided into groups, the main sections ("Hoofdrubrieken"). This is called the category scheme.

Main sections give a general grouping, for example household expenses ("HUISHOUDELIJKE UITGAVEN") and transport ("VERVOER").

Categories give a more refined grouping within a main section. The main section household expenses for example consists of several categories such as "Voeding en versnaperingen", "Persoonlijke verzorging" and "huisdieren". This scheme has been created collectively with the Nibud (National Institute for Family Finance Information). It is possible to create a personalized scheme that connects better to individual applications. This can be configured in consultation with Invers.

Nace rev. 2 or SBI

NACE is an abbreviation for "Nomenclature statistique des Activités économiques dans la Communauté Européenne" ("European Classification of Economic Activities"). The NACE code is a code that is assigned to a certain classification of economic activities, aimed to be a tool to construct economic statistics and overviews. For more information, see: http://ec.europa.eu/eurostat/web/nace-rev2/correspondence_tables

The Central Bureau of Statistics (CBS) and the Chamber of Commerce (KvK) use SBI codes (Standard Industrial Classifications) to categorize companies. SBI is derived from NACE, where the first four levels of codification are the same. Each company registered at LinX returns an SBI or NACE code.

Properties

LinX detects extra information on the transaction itself or on the 'owner' of the transactions. For example: customer, policy and contract numbers as well as license plates of vehicles. These properties are divisible in personal details, such as postal code and house number, relational properties (customer number at a counterpart) and transaction bound properties (invoice number for example). LinX uses these properties to calculate and determine extra information.

See Properties and transaction kinds for an overview of all the properties than can be detected.

Information on the counterpart

When a bank transaction connects to a business as a counterpart, additional information shall be available about counterparts. Available information:

• Name, address and geographic location of business
• Judicial information (Limited)
• Contact information (Website, telephone number and e-mail)
• GPS (latitude and longitude)
• Activities (optional) Note: If the transaction concerns a payment via a so-called payment provider, the transaction has a financial counterparty and a substantive counterparty. For classification, use is made of the substantive party (when available). Note that in the event that the transaction has a paymentprovider as a counterpart, then the transaction has a financial counterpart and a substantial counterpart. If the latter is available, this is used for determining a transaction's category.

Recurrence integration into Convert

Recurrence can be enabled on /convert by using the IncludeRecurrence flag in the headers of the request.

When set to true the Recurrence algorithm will be executed on the given transaction batch.

The Recurrence algorithm will only be executed if the Customer has the module enabled for Recurrence (Id 28).

When the IncludeRecurrence flag is enabled it will add 3 properties to each transaction that are recurrent:

• RecurrenceSequence => In which sequence the recurrence belongs in

• RecurrenceInterval => Is a number that states how often it occurs in a given time period

• RecurrenceType => The type of recurrence. The possible values are:

  • 0 => None

  • 1 => Second

  • 2 => Minute

  • 3 => Hour

  • 4 => Day

  • 5 => Week

  • 6 => Month

  • 7 => Quarter

  • 8 => Semester

  • 9 => Year

So for example if a transaction has a RecurrenceInterval of 3 and a RecurrenceType of 6 it means the transaction reoccurs every 3 months.

When the recurrence succeeds a Quota event will be generated to indicate that the customer used the IncludeRecurrence flag.

Machine Learning integration into Convert

Machine learning can be enabled on /convert by using the IncludeMachineLearning flag in the headers of the request.

When set to true the Machine learning (Ml) API will be called on the given transaction batch.

The Machine learning algorithm will only be executed if the Customer has the module enabled for MachineLearning (Id 29).

When the IncludeMachineLearning flag is enabled it will add 2 properties to each transaction:

MlCategory=> The id of the category that the machine learning API returned

MlProbability=> How certain the machine learning API is. Decimal from 0 to 1. 1 would state that the machine learning API was 100% sure about the result.

When the machine learning API call succeeds a Quota event will be generated to indicate that the customer used the IncludeMachineLearning flag.

Transaction dates

The bookDate and interestDate are extracted directly from the PSD2 file.

Several banks include a time, but not all. Invers includes the time if the bank provides it.

The transaction date is parsed from the description, and is only present if the parsing was successful.

If the parser also found a time, it is included.

The rationale is that we enrich the output with as much information as possible.

Calling the Convert

Endpoint:   https://linx.invers.nl:8100/api/linx/convert
Method:     POST

Header:     ApiKey:                 string      (required)
            X-Request-ID:           string      (required)
            ClientId:               string      (optional)
            ConsentCollectionId     string      (optional)
            Options:                int         (optional)
            KvK:                    json        (optional)
            SBI:                    string      (optional)
            IncludePending          bool        (optional)
            IncludeMachineLearning  bool        (optional)
            Businesses              string      (optional)
            Virtuals                string      (optional)

Body:       Data:               byte[]      (required)

Errors:     400, 403 or 500

Information

Field	Type	Description
Format	String	File format
From	Date	Date of the first transaction
To	Date	Date of the last transaction
Accounts	Array of accounts	Per account
Businesses	Array of businesses	businesses
Groups	Array of groups	Groups
Categories	Array of categories	Categories
Naces	Array of naces	Nace

Account

Field	Type	Description
number	String	Bank account number without layout formatting
formattedNumber	String	Bank account number with layout formatting
iban	String	IBAN
bic	String	BIC
beginBalanceDate	Date	Date of opening balance
beginBalance	Money	Value of opening balance
endBalanceDate	Date	Date of closing balance
endBalance	Money	Value of closing balance
transactions	Array	Transactions that belong to the account
bank	Integer	Properties of the bank
country	String	Country code in ISO 2 characters

Transaction

Field	Type	Description
id	Integer	Internal enumeration of transaction
bookDate	Date	Book date
interestDate	Date	Interest date
amount	Money	Amount of mutation
endBalance	Money	End balance
beneficiary	Beneficiary	Counterpart of the mutation
code	TransactionCode	Mutation type, see Properties and transaction types
description	String	Detected description of the transaction
originaldescription	String	Orginal, unrefined, description
flags	Flags	Internal parameter
sequence	Integer	serial number
categoryId	Category	category identifier
naceId	Integer	NACE identifier
nace	String	SBI or NACE rev 2
properties	Array of properties	Transaction properties, see Properties and transactie types
contract	String	Bank account number (IBAN)
externalTransactionId	String	Id given to the transaction by the bank. This is field may not exist or be empty. In PSD2 this field is unique per account.

TransactionCode

Field	Type	Description
type	String	Type of transaction
code	String	The transaction code provided by the bank
name	String	Name of transaction type or code

Beneficiary

PIN transaction

Field	Type	Description
date	DateTime	Transaction timestamp
device	String	Device identifier
city	String	Place of transaction
id	integer	Internal parameter
country	String	Country code ISO 2 characters
name	String	Name of the counterpart
originalName	String	Original, unrefined, name of the counterpart
reference	String	Reference of the transaction
businessId	Integer	Business identifier of the counterpart, may be empty

Transaction with a contra account

Field	Type	Description
number	String	Bank account number without layout formatting
formattedNumber	String	Bank account number with layout formatting
iban	String	IBAN
incassant	String	Identity in case of collection
mandate	String	Collection mandate
targetBusinessId	Integer	Identity of the real counterpart (in case of a payment service such as iDeal)
id	Integer	Internal parameter
country	String	Country code ISO 2 characters
name	String	Name Counterpart
originalName	String	Original, unrefined, name of counterpart
reference	String	Reference of the transaction
businessId	Integer	Business identifier of the counterpart, may be empty

Bank

Field	Type	Description
id	Integer	Bank identifier
country	String	Coutnry code ISO 2 characters
bic	string	BIC
name	string	Bank name
formats	string	Supported download formats
downloadUrl	string	Link to the download page
iconUrl	string	Internal parameter
infoUrl	string	Internal parameter
isActive	Boolean	Internal parameter
isVisisble	Boolean	Internal parameter
syncKey	UUID	Internal parameter

Businesses

Field	Types	Description
id	Integer	Identifier counterpart
name	String	Name of counterpart
country	String	Country code ISO 2 characters
number	String	Official Chamber of Commerce (KvK) number
subsidiary	String	Branch number
addresses	Array of addresses	Addresses of counterpart
contacts	Array	Contact information of counterpart
activities	Array	Activities (NACE) of counterpart
tradenames	Array	Trade name

Addresses

Field	Type	Description
default	Boolean	True if this is the default adres
street	String	Street name
houseNumber	String	House number
houseNumberAddition	String	House number addition
zipcode	String	Zip/Postal Code
city	String	Place
country	String	Country
type	String	Address type denotation, country and language dependent
latitude	Float	If available
longitude	Float	If available

Groups

Field	Types	Description
id	Integer	Group identifier
name	String	Group name
type	Enum	Income Expenses
isInternal	Boolean	Internal parameter
color	Integer	Internal parameter
SyncKey	UUID	Internal parameter

Categories

Field	Type	Description
id	Integer	Category identifier
name	String	Category name
type	Enum	None Income Expenses
costType	Enum	None Fix Variable
isInternal	Boolean	Internal transaction
isStrict	Boolean	Internal parameter
color	Integer	Internal parameter
taxpost	String	tax item
SyncKey	UUID	Internal parameter
groupId	Group	Group identifier to which the category belongs

Naces

Field	Type	Description
id	Integer	Nace Identifier
code	String	SBI or NACE code
description	String	Description

Output (Example)

{
  "format": "string",
  "from": "YYYY-MM-DDTHH:MM:SS+HH:MM",
  "to": "YYYY-MM-DDTHH:MM:SS+HH:MM",
  "accounts": [
    {
      "iban": "string",
      "bic": "string",
      "id": 0,
      "country": "string",
      "name": "string",
      "originalName": "string",
      "reference": "string",
      "businessId": 0,
      "business": {
        "id": 0,
        "name": "string",
        "country": "string",
        "number": "string",
        "subsidiary": "string",
        "addresses": [
          {
            "id": "string",
            "default": true,
            "street": "string",
            "houseNumber": "string",
            "houseNumberAddition": "string",
            "zipcode": "string",
            "city": {
              "id": "string",
              "name": "string"
            },
            "municipality": {
              "id": "string",
              "name": "string"
            },
            "province": {
              "id": "string",
              "name": "string"
            },
            "country": "string",
            "type": "string",
            "purpose": "unknown",
            "surface": 0,
            "surfaceArea": 0,
            "latitude": 0,
            "longitude": 0
          }
        ],
        "contacts": [
          {
            "type": "email",
            "value": "string"
          }
        ],
        "activities": [
          {
            "code": "string",
            "name": "string",
            "isMain": true
          }
        ],
        "tradenames": [
          "string"
        ]
      },
      "number": "string",
      "formattedNumber": "string",
      "beginBalanceDate": "YYYY-MM-DDTHH:MM:SS+HH:MM",
      "beginBalance": 0,
      "endBalanceDate": "YYYY-MM-DDTHH:MM:SS+HH:MM",
      "endBalance": 0,
      "transactions": [
        {
          "id": "string",
          "bookDate": "YYYY-MM-DDTHH:MM:SS+HH:MM",
          "interestDate": "YYYY-MM-DDTHH:MM:SS+HH:MM",
          "amount": 0,
          "endBalance": 0,
          "beneficiary": {
            "id": 0,
            "country": "string",
            "name": "string",
            "originalName": "string",
            "reference": "string",
            "businessId": 0,
            "business": {
              "id": 0,
              "name": "string",
              "country": "string",
              "number": "string",
              "subsidiary": "string",
              "addresses": [
                {
                  "id": "string",
                  "default": true,
                  "street": "string",
                  "houseNumber": "string",
                  "houseNumberAddition": "string",
                  "zipcode": "string",
                  "city": {
                    "id": "string",
                    "name": "string"
                  },
                  "municipality": {
                    "id": "string",
                    "name": "string"
                  },
                  "province": {
                    "id": "string",
                    "name": "string"
                  },
                  "country": "string",
                  "type": "string",
                  "purpose": "unknown",
                  "surface": 0,
                  "surfaceArea": 0,
                  "latitude": 0,
                  "longitude": 0
                }
              ],
              "contacts": [
                {
                  "type": "email",
                  "value": "string"
                }
              ],
              "activities": [
                {
                  "code": "string",
                  "name": "string",
                  "isMain": true
                }
              ],
              "tradenames": [
                "string"
              ]
            }
          },
          "code": {
            "id": 0,
            "type": "aC",
            "code": "string",
            "numeric": 0,
            "name": "string"
          },
          "description": "string",
          "originalDescription": "string",
          "flags": "none",
          "sequence": 0,
          "categoryId": 0,
          "category": {
            "id": 0,
            "name": "string",
            "type": "none",
            "costType": "none",
            "isInternal": true,
            "isStrict": true,
            "color": 0,
            "taxPost": "string",
            "syncKey": "string",
            "groupId": 0,
            "nibuds": [
              0
            ],
            "posten": [
              {
                "id": 0,
                "name": "string",
                "description": "string",
                "years": [
                  0
                ]
              }
            ]
          },
          "naceId": 0,
          "nace": {
            "id": 0,
            "code": "string",
            "description": "string"
          },
          "properties": [
            {
              "id": 0,
              "type": "none",
              "context": "transaction",
              "name": "string",
              "value": "string",
              "properties": [
                null
              ]
            }
          ],
          "contract": "string",
          "externalTransactionId": "string"
        }
      ]
    }
  ],
  "businesses": [
    {
      "id": 0,
      "name": "string",
      "country": "string",
      "number": "string",
      "subsidiary": "string",
      "addresses": [
        {
          "id": "string",
          "default": true,
          "street": "string",
          "houseNumber": "string",
          "houseNumberAddition": "string",
          "zipcode": "string",
          "city": {
            "id": "string",
            "name": "string"
          },
          "municipality": {
            "id": "string",
            "name": "string"
          },
          "province": {
            "id": "string",
            "name": "string"
          },
          "country": "string",
          "type": "string",
          "purpose": "unknown",
          "surface": 0,
          "surfaceArea": 0,
          "latitude": 0,
          "longitude": 0
        }
      ],
      "contacts": [
        {
          "type": "email",
          "value": "string"
        }
      ],
      "activities": [
        {
          "code": "string",
          "name": "string",
          "isMain": true
        }
      ],
      "tradenames": [
        "string"
      ]
    }
  ],
  "groups": [
    {
      "id": 0,
      "name": "string",
      "type": "none",
      "isInternal": true,
      "color": 0,
      "syncKey": "string",
      "categories": [
        {
          "id": 0,
          "name": "string",
          "type": "none",
          "costType": "none",
          "isInternal": true,
          "isStrict": true,
          "color": 0,
          "taxPost": "string",
          "syncKey": "string",
          "groupId": 0,
          "nibuds": [
            0
          ],
          "posten": [
            {
              "id": 0,
              "name": "string",
              "description": "string",
              "years": [
                0
              ]
            }
          ]
        }
      ]
    }
  ],
  "categories": [
    {
      "id": 0,
      "name": "string",
      "type": "none",
      "costType": "none",
      "isInternal": true,
      "isStrict": true,
      "color": 0,
      "taxPost": "string",
      "syncKey": "string",
      "groupId": 0,
      "nibuds": [
        0
      ],
      "posten": [
        {
          "id": 0,
          "name": "string",
          "description": "string",
          "years": [
            0
          ]
        }
      ]
    }
  ],
  "naces": [
    {
      "id": 0,
      "code": "string",
      "description": "string"
    }
  ]
}