NAV Navbar
cURL

BANKSapi BANKS/Connect

Interface strategy

The APIs are created according to the REST paradigm with respect to the architectural style HATEOAS. Because of the addressing logic shifted to the server, it is possible to extend the API organically without causing breaks for the callers.

If a modification cannot be implemented in a downward-compatible manner, previous versions of the interface are provided in parallel as required over a reasonable transition period.

The interface is always called via HTTPS encryption. We currently offer JSON as a data exchange format, but if required, an extension by further formats in the future is not excluded.

Structure of interface and documentation

The interface is divided into three sub-APIs Banks/Connect Customer, Banks/Connect Providers API and BANKSapi Auth API, which are briefly described in the following sections. For further information please refer to the comprehensive Sub-API documentation.

Central concepts of the BANKSapi Banks/Connect interface like Authentication are described in the chapter of the same name within this document. Furthermore, concepts applicable to the respective sub-API are described in the respective API documentation.

Before it gets started

{
  "left": "navigation",
  "center": "text",
  "right": "code"
}

In addition to the explanatory texts, examples of the data in JSON format are providedwhere we found it helpful.

$ curl https://banksapi.io/hello/ \
  -X GET \
  -H 'Expect: ' \
  -H 'Accept: application/json'

To show an example of the interface calls, we use the command line tool curl(1) in version 7.43.0. Unless otherwise stated, these examples can be executed directly in the command line and return data according to the success case.

Feedback

This documentation is primarily intended to be helpful. We are therefore pleased to receive your criticism and suggestions, which you can send to support@banksapi.de.

APIs

BANKS/Connect Auth API

The protection of personal data has the highest priority at BANKSapi. Encryption and security tokens used throughout the entire process are central components of our security concept.

The BANKSapi Auth API provides functions for managing Users. Using the OAuth2 protocol, you can create tokens to enable only those functions that are necessary for the respective use case.

For comprehensive information about the BANKSapi Auth API, see the Interface Documentation.

BANKS/Connect Customer API

{
    "1cb1126d-360d-412d-a74f-985414f57ea3": {
        "status": "VOLLSTAENDIG",
        "aktivesSicherheitsverfahren": {
            "kodierung": 1,
            "name": "Mock-TAN",
            "hinweis": "Mock-TAN"
        },
        "aktualisierungszeitpunkt": "2016-06-10 17:17:40",
        "timeout": "2016-12-24 13:37:42",
        "bankprodukte": [],
        "sync": false,
        "tanMedien": [{
            "gueltigVon": "2016-06-03 17:17:41",
            "gueltigBis": "2016-06-03 17:17:41",
            "name": "Mobil",
            "medienklasse": "MOBIL"
        }],
        "sicherheitsverfahren": [{
                "kodierung": 2,
                "name": "mTAN",
                "hinweis": "mTAN"
            },
            {
                "kodierung": 1,
                "name": "Mock-TAN",
                "hinweis": "Mock-TAN"
            }
        ],
        "messages": [{
            "level": "INFO",
            "code": "BA3010",
            "message": "SCA benötigt",
            "details": "Bitte wählen Sie eine SCA-Methode aus"
        }],
        "relations": [{
            "rel": "set_method",
            "href": "https://banksapi.io/v2/customer/consent/1345340218050910215PSDDE-BAFIN-152070CO4960JJ"
        }]
    }
}

At the heart of BANKSapi Banks/Connect is the BANKS/Connect Customer API, which enables your end customers to access their financial life and perform transactions within your product.

Comprehensive information about the API can be found in the interface documentation.

BANKS/Connect Providers API

Not all banks are the same. Therefore we provide you a comprehensive configuration database of data on the banks and service providers supported by BANKSapi BANKS/Connect via the BANKS/Connect Providers API

In addition to general master data such as the name, bank group, BLZ and BIC, you also receive detailed machine-readable information on login modalities so that you can optimize the user experience of your application when creating bank accounts.

Comprehensive information about the BANKS/Connect Providers API can be found in the interface documentation.

AI/Connect

Every user is different. AI/Connect solutions translate account information for financial service providers into specific information about the customers’ finances. This allows financial service providers to offer individual financial solutions to each user.

AI/Connect differs from our other APIs mainly in that it contains derived data. Through artificial intelligent this data is extrapolated and interpreted. Therefore, BANKSapi AI Endpoints first categorizes individual transactions along the dimensions of spending type, spending frequency and business partner.

Later, these transactions of a specific user are aggregated and used as inputs to the next level of machine learning models to categorize the user along different dimensions such as monthly budget structure, spending habits across time and across spending categories, life stages.

Comprehensive information about AI/Connect can be found in the interface documentation

Central Concepts

Authentication

Authentication is a very important topic, but in the end it is only a means to an end. Therefore, we avoid this topic in our Quickstart guide as far as possible without bothering you. So you can concentrate on the core of your requirement and move the details to a little later.

With BANKSapi BANKS/Connect there are generally three types of authentication:

Furthermore, the BANKSapi Auth API has its own admin client with which you can create and manage users.

Which form of authentication is used when, can be found at the appropriate place in the sub-API documentation As a general rule, every inquiry is to BANKSapi BANKS/Connect in the context of a client. This is already sufficient for a few, e.g. for the provider query. The entire functionality is developed by BANKSapi Banks/Connect using a user token and a few bank access points.

Bank

In conjunction of BANKSapi BANKS/Connect, we refer to the banking institutions from which we collect the data on your behalf as "bank". In the context of BANKSapi BANKS/Connect they are grouped together with the service providers as Providers.

The banks activated for you in BANKSapi Banks/Connect can be accessed via the Banks/Connect Providers API.

User

The unique user is also the central billing criterion. Further details are regulated by your cooperation agreement.

A user forms a bracket around the data retrieved about a person from the various banks or service providers.

With BANKSapi BANKS/Connect the users belong to you, the client. Access to the financial data of your users is provided via the Banks/Connect Customer API.

With the Banks/Connect Auth API you can manage your users.

Client

We use the term client for both, your application(s) and an "admin-client" which you allows you to manage your users. From our point of view a client is therefore a set of access data for BANKSapi BANKS/Connect.

With a client ID, client tokens can be obtained via the BANKS/Connect Auth API via OAuth2. These tokens can then be used to access the other functions in the BANKS/Connect Customer API or BANKS/Connect Providers API.

Correlation ID

GET / HTTP/1.1
x-correlation-id: c129b93a-9b5c-11e6-a112-480fcfb9550f

The Correlation-ID is used to track requests across all systems. The Correlation-ID can be passed to the BANKSapi APIs as HTTP header X-Correlation-ID.

If it is not passed, the BANKSapi APIs generate their own ID.

In any case, the value is also returned as the HTTP response header X Correlation ID.

CORS

More information about CORS on Wikipedia.

BANKSapi Banks/Connect supports Cross Origin Resource Sharing (CORS). This makes it possible to call our APIs directly from the browser, for example in a single-page app.

Error

Wikipedia has an excellent list of HTTP status codes.

Unfortunately, mistakes cannot always be avoided, but they can be treated. Especially with external dependencies such as banks and service providers, which are connected via BANKSapi BANKS/Connect, we have no influence on their (generally very high) availability.

Therefore we provide you in the BANKS/Connect Customer API message objects next to a code, a error description for your end customer as well as an informative detail message for you. This also includes queries with errors with an HTTP status code from the Range 2XX answered.

If things get stuck with us, we work with the whole range of HTTP status codes.

For details about the possible message objects and the HTTP status codes, see the "Errors and Messages" section in the Sub-API documentation.

HATEOAS

More information about HATEOAS on Wikipedia.

HATEOAS stands for "Hypermedia as the Engine of Application State". Here the client of a REST interface navigates only via URLs provided by the server. Accordingly, there are only a few fixed URLs that must be known to the calling party. Each additional Interaction takes place via URLs that contain within the return of interface calls and have only limited validity.

These URLs are communicated to the caller either in the HTTP response header "Location" or more often in the form of Relations in the returned document.

Timestamp

for example:
2016-09-03 04:27:00
2019-12-04 13:37:00
2010-01-01 22:03:54

Time stamps are always output without time zone information. They correspond to the format ISO 8601 in the form YYYY-MM-DD hh:mm:ss. Data is to be interpreted according to the time zone Europe/Berlin.

JSON

{
  "aString": "Lorem ipsum dolor annat",
  "anInteger":42,
  "aFloat":42.1337,
  "aBool":true,
  "aDate": "1969-07-20",
  "aTimestamp": "2016-09-03 04:27:00",
  "anArrayOfInteger":[1,2,3],
  "anArrayOfStrings":["one", "two", "three"],
  "anObject":{
     "cat": "kitten",
     "dog": "puppy"
  }
}

The BANKSapi Banks/Connect interfaces use the JSON (JavaScript Object Notation) for data exchange. Attributes without values are not delivered as "zero", but "missing" in the document. We deliver and expect date values according to ISO 8601 formatted as string.

In the case of exchanged JSON documents, it should also be noted that every consumer must ignore unknown attributes. This applies in particular to enumeration types whose extension is regarded as downward compatible. Unknown values in Enumeration types must therefore also be ignored by the Client or encrypted to a more general value.

When JSON is delivered, the Content-Type header "Content-Type: application/json" must always be included. With "zero" values, it does not matter whether the fields be sent as "zero" or not at all, unless they are mandatory fields.

When JSON is delivered, the Content-Type header "Content-Type: application/json" must always be included. With "null" values it does not matter if the fields are sent as "null" or not at all, as long as they are not mandatory fields.

Client

There is also a demo client, which is used for example in our Quick Start Guide.

This is you or the company that has concluded a cooperation agreement with us. The client includes Clients and Users.

As a client you have access to our first-class support and benefits from the permanent development of BANKSapi BANKS/Connect. And of course you will see more data than just our demo bank.

If you are interested, please contact with us.

OAuth2

All calls to the BANKSapi interfaces must be made with a valid OAuth2 token. For some operations, a client token (without a specific user) is sufficient.

Details on user and client management are described in the BANKSapi Auth API.

Token types

BANKSapi is working in a 2-legged OAuth2 setting. This means you will be supplied a refresh token. With this, you will have to fetch a fresh access token for almost all calls within our APIs.

The refresh token (actually a set of Basic Auth credentials) is valid for a long time and used exclusively to fetch new access tokens. It is a Basic token, you will have to authenticate with Authorization: Basic <base64EncodedCredentials>

An access token has a validity of 24hrs, after which you will need to create a new token. Depending on your design and use case, we recommend that you either keep track of the validity and fetch a new token in time, or you fetch a new access token per business transaction, in which case you can go without persistence of the token. You will have to authenticate with Authorization: Bearer <bearerToken>

Token levels

Access tokens can be on client or on user level. If nothing is explicitly documented in the corresponding use case, the call with a unique user is assumed. Bear in mind you can't do calls like e.g. add a new bank account on a client (i.e. management) level as these would be available for all users, but only on user level. But a user can't create new users, this must be done on a management level.

Token usage

When calling, the token must be transferred according to the OAuth2 standard in the header "Authorization: Bearer ...". If this header is missing or the token is invalid, the interface responds with the HTTP status code 401 (Unauthorized). If the token does not contain the necessary authorizations, the HTTP status code 403 (Forbidden) is reported.

Provider

As providers we refer to the connected banks and service providers in a very abstract way. The connection is made using a wide variety of technologies and at the end the collected data will be converted into a uniform format for you.

Relation

{
    "rel": "say_hello",
    "href": "https://banksapi.io/hello/"
}

A relation corresponds to an application or business transaction that is supported by the surrounding data object. For every application and business transaction, there is a separate documentation that describes both the call and the return or the possible alternative response scenarios in the in detail.

Each relation consists of a keyword (e.g. "get_kontoumsaetze") and a URL. A client that is interested in the account transactions calls the specified URL with the HTTP verb specified in the documentation.

REST

Recommended reading: Roy Fielding: REST APIs must be hypertext-driven

Our APIs are implemented as REST patterns (Representational State Transfer). Consequently, they are usable via the HTTP protocol and use more HTTP verbs as GET and POST only.

Furthermore, we strive to meet the requirements of the REST inventor Roy Fielding for a REST API by reflecting on the HATEOAS architectural style to do justice to this.

Service Provider

Service providers are connected financial institutions that are not a bank. In the context of BANKSapi Banks/Connect they are also more generally referred to as Provider.

Information about service providers can be obtained through the BANKS/Connect Providers API.

Language

The German banking landscape is very German-speaking, and therefore one lands in detail quite fast in the search for an appropriate translation in a dead end (or half-silk translation). However, as engineers it is also obvious to us to "program in English".

In order to get out of this dilemma, we decided to leave technical terms from the banking environment in German and to use all other terms from English to import. To avoid a too heavy "Denglish", we have decided to import German as well.

Otherwise BANKSapi Banks/Connect is mainly programmed in Java and some other JVM languages.

Encryption

{
  "plaintext": "BANKSapi",
  "Ciphertext": "ONAXFncv"
}

In order for BANKSapi BANKS/Connect to access the data of the banks, the access data must be available. Since this information is extremely sensitive, the access data is protected by strong asymmetric encryption. You will receive an RSA public key at the beginning of the cooperation. The secret counterpart lies with us. Thus the access data can be encrypted but not decrypted.

The procedure is described in detail in the documentation for the Banks/Connect Customer API.

We check the quality of our TLS configuration with the tool Qualys SSL Labs.

Otherwise, of course, the transport route is encrypted using TLS (HTTPS).

Versioning

Semantic versioning even has its own semantically versioned manifest.

The interfaces are semantically versioned (X.Y, e.g. 2.0). If the Y value increases, a correctly implemented Client will continue to work without restrictions, but of course does not use the new functions. In the event of a change of X, the client must be adapted, since the change was not backward compatible. Previous major versions (X) will be is still supported for a while after the introduction of the incompatible subsequent versions, if this makes sense from a technical point of view.

Quick Start

What We're Going to Do

We'd like to guide you through the first steps you're probably going to take with our interface: You will probably want to create a first user and add a bank access for them. This will give you a good first impression on what data is available through our API, how to interact with it in general as well as some of the concepts we're using.

For starters, bear in mind we're basing our authentication on the (2-legged) OAuth2 protocol. Therefore, you will be supplied with a "refresh token" in order to fetch a new access token.

Create a Client Token

POST /auth/oauth2/token HTTP/1.1
Host: banksapi.io
Authorization: Basic c29<...>U=
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

The first step will be to fetch a fresh access token on management level in order to be able to create a new user. For this, we will use the Create Token call. You can see the call on the right.

The only required field of this call is grant_type, which we fill with client_credentials, because we want to create a token on management (i.e. client) level. The scope parameter can be left out, in which case we will receive the full scope. If at a later point we want to limit this for security or design reasons, we can add the scopes that we'd like this token to have.

{
    "scope": "http://banksapi.io/customer/read http://banksapi.io/provider/read http://banksapi.io/customer/modify http://banksapi.io/customer/ueberweisung auth/tenants/users/create",
    "tenant": "demotenant",
    "client": "demoTenantClient",
    "additionalData": {},
    "validTo": "2020-10-08 09:16:03",
    "access_token": "edbc0a13-19c3-4a10-ac96-bbfe900a0a06",
    "token_type": "Bearer"
}

The response we can see on the right: Together with some additional data, we receive an access_token of type Bearer, valid for 24hrs, for our tenant demotenant. Make note of the tenant name, we'll need it in the next call.

Create a User

With the new token we've just created, we will now create our first user.

POST /auth/mgmt/v1/tenants/demotenant/users HTTP/1.1
Host: banksapi.io
Content-Type: application/json
Authorization: Bearer edbc0a13-19c3-4a10-ac96-bbfe900a0a06

{
    "username": "user1",
    "password": "password1"
}

For this, we will use the Create User call. You can see the call on the right. The required fields are username and password, so we will set these values.

The Content-Type is application/json in this (as in every other) case, and we use the new Bearer token as Authorization. As a last parameter, note the tenant id in the URL, because we're creating a user for that (your) tenant. This is the same tenant that we have received in the response of the previous call.

The response will be an HTTP 201 Created success status response with no body, indicating the user has been created.

Create a User Token

POST /auth/oauth2/token HTTP/1.1
Host: banksapi.io
Authorization: Basic c29<...>U=
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=user1&password=password1

Now we need to fetch a fresh access token on the user level. As in the first call, we will use the Create Token call, but with different parameters. You can see the call on the right.

This time, as we're fetching a token on user level, we are using grant_type=password, not client_credentials. This is according to the OAuth2 password grant. Of course, for username and password we're using the values that we have specified in the previous call.

{
    "scope": "http://banksapi.io/provider/read http://banksapi.io/customer/read http://banksapi.io/customer/modify http://banksapi.io/customer/ueberweisung auth/tenants/users/create",
    "tenant": "demotenant",
    "client": "demoTenantClient",
    "user": "0049e4d6-824f-4839-823d-7a2ad4660c4e",
    "additionalData": {
        "username": "user1"
    },
    "validTo": "2020-10-08 10:56:47",
    "access_token": "0bac1d52-4eb0-4fe2-951e-cf6ff9dc4235",
    "token_type": "Bearer"
}

As a response, we receive a similar JSON object as before. This time, as additionalData we receive the username to indicate it's a token on user level.

That's it for the Auth API, all subsequent calls we'll make with the Customer API with our new Bearer token on user (i.e. customer) level.

Create Bank Access

With the new token, we can access the full range of customer interactions. But as the user has not added a bank access yet, our options are somewhat limited. So next we're going to add a bank access for that user.

Now it gets tricky: For this operation, you will need to differentiate whether you are a regulated or a non-regulated customer. Non-regulated customers will not be allowed to receive the credentials to a provider (e.g. a bank) on their own domain. These are considered sensitive payment information and the handling of this is regulated by the authorities. Therefore, they will have to redirect the customer to us, the customer will select a bank and enter sensitive payment information on a BANKSapi frontend (REG/Protect) and complete the authorization flow, then the customer is redirected back to you.

POST /customer/v2/bankzugaenge HTTP/1.1
Host: banksapi.io
Content-Type: application/json
Authorization: Bearer 0bac1d52-4eb0-4fe2-951e-cf6ff9dc4235

{
    "629e4510-5331-47d4-9bad-8902039ff762": {
    }
}

For adding a new bank access, we will use the Add Bank Access call. You can see the call on the right.

No surprises in the headers, Content-Type is application/json as with all the calls in the Customer API, Authorization is our new Bearer token on user level.

The payload requires a bit of explanation: A bank access is referenced by a UUID. Because it might be necessary for you to query the bank access object without any response from BANKSapi, this UUID needs to be chosen and set by you. Therefore, the UUID visible in the body is a new UUID that you need to create with a suitable UUID generator.

The banks access object (referenced by the UUID) is empty in this case as in {}. The reason is that in the REG/Protect case, you can neither send us a credentials object (this would require a regulatory license to handle sensitive payment data) nor a provider ID (the user will be able to select the bank in the REG/Protect wizard). The last optional flag, sync, indicates whether the bank access should be persisted on BANKSapi end. For REG/Protect clients, this must be true (which is also the default value) and can therefore be omitted.

HTTP/1.1 451 Unavailable For Legal Reasons
Location: https://banksapi.io/customer/v2/webform?session=ef2fdd3b-a087-447b-843c-670325d003f4&useCase=CREATE_ACCOUNT

The result will be an HTTP 451 Unavailable for Legal Reasons status response with no body. Admittedly used rarely, for this case it's the perfect response code, indicating you are not allowed to create a bank access yourself (for legal reasons) but will have to have us do it for you.

In the background, we have created the corresponding frontend session already and are prepared to have the user come to our domain for completing the process. The URL of our frontend will be delivered through the Location respone header.

In order for us to know where to redirect the user after completion, you will need to add a callbackUrl query parameter to the URL before redirecting the user there, as indicated in the docs on Adding and authenticating bank accounts. This callback URL needs to be URL encoded

In our example, we would therefore redirect the user to https://banksapi.io/customer/v2/webform?session=ef2fdd3b-a087-447b-843c-670325d003f4&useCase=CREATE_ACCOUNT&callbackUrl=http%3A%2F%2Fexample.com (or, for the first tests, open it in the browser ourself).

Now you can relax for a bit, the user will be completing the process on our frontend:

Step Screenshot
Accepting our T&Cs (only once per user, for the second bank access this step will be omitted) AGB
Selecting a provider Select a bank Select demo provider
Entering the credentials Entering credentials
Confirming accounts Confirming accounts
Being redirected back to you Redirect

The user will be redirect back to the URL you specified previously in callbackUrl, together with a query parameter baReentry indicating the result (normally ACCOUNT_CREATED).

That's it, the account has been created. In the background, we were already communicating with the user's bank or provider, fetching and analyzing data. You can now query the data, continuing with the next requests.

Query Bank Access

GET /customer/v2/bankzugaenge HTTP/1.1
Host: banksapi.io
Authorization: Bearer 0bac1d52-4eb0-4fe2-951e-cf6ff9dc4235

Next up, let's check if the bank access is there and what options we have to go on. We'll use the Get Bank Accesses call, so query all bank accesses of that user instead of a specific one referenced by the ID you chose earlier. You can see the call on the right.

{
    "629e4510-5331-47d4-9bad-8902039ff762": {
        "id": "629e4510-5331-47d4-9bad-8902039ff762",
        "providerId": "00000000-0000-0000-0000-000000000000",
        "aktualisierungszeitpunkt": "2020-10-07 13:26:13",
        "tanMedien": [
            {
                "name": "Mobil",
                "medienklasse": "MOBIL",
                "gueltigVon": "2020-10-07 13:26:13",
                "gueltigBis": "2020-10-07 13:26:13"
            }
        ],
        "sicherheitsverfahren": [
            {
                "kodierung": 902,
                "name": "mockPhotoTAN",
                "hinweis": "Scanne das Bild. Das Ergebnis ist \"8534842\""
            },
            {
                "kodierung": 1,
                "name": "mockTAN",
                "hinweis": "Gib eine durch 2 teilbare Zahl ein"
            }
        ],
        "aktivesSicherheitsverfahren": {
            "kodierung": 1,
            "name": "mockTAN",
            "hinweis": "Gib eine durch 2 teilbare Zahl ein"
        },
        "relations": [
            {
                "rel": "self",
                "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762"
            },
            {
                "rel": "delete_bankzugang",
                "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762"
            },
            {
                "rel": "get_issues",
                "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/issues"
            }
        ],
        "status": "VOLLSTAENDIG",
        "bankprodukte": [
            {
                "id": "DE00123456789012345678",
                "status": "VOLLSTAENDIG",
                "bezeichnung": "Girokonto",
                "kategorie": "GIROKONTO",
                "saldo": 2145.78,
                "aktualisierungszeitpunkt": "2020-10-07 13:26:13",
                "saldoDatum": "2020-10-07 00:00:00",
                "waehrung": "EUR",
                "kontonummer": "9012345678",
                "iban": "DE00123456789012345678",
                "bic": "XXX12345678",
                "blz": "12345678",
                "kreditinstitut": "Demo Provider",
                "inhaber": "Fritz Testmüller",
                "relations": [
                    {
                        "rel": "start_ueberweisung",
                        "href": "https://banksapi.io/customer/v2/ueberweisung/00000000-0000-0000-0000-000000000000/DE00123456789012345678"
                    },
                    {
                        "rel": "self",
                        "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/DE00123456789012345678"
                    },
                    {
                        "rel": "get_kontoumsaetze",
                        "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/DE00123456789012345678/kontoumsaetze"
                    },
                    {
                        "rel": "get_kontoumsaetze_tagged",
                        "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/DE00123456789012345678/kontoumsaetze?tag=true"
                    },
                    {
                        "rel": "get_kontoumsaetze_insurances",
                        "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/DE00123456789012345678/kontoumsaetze?tag=insurances"
                    },
                    {
                        "rel": "get_kontoumsaetze_business_partners",
                        "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/DE00123456789012345678/kontoumsaetze?tag=business-partners"
                    }
                ],
                "messages": [],
                "ueberziehungslimit": 3000.0,
                "verfuegungsrahmen": 2045.78,
                "verfuegterBetrag": 100.0
            },
            {...}
        ],
        "sync": true
    }
}

As a response, the server will return the (now filled) bank access object we created earlier. Find a sample response on the right.

Wow, there's is a lot going on, so let's dissect:

Top level, we have an object representing a collection of all bank accesses of that user. In this case, we have yet only created one, so the collection has one entry with the key 629e4510-5331-47d4-9bad-8902039ff762, which is the UUID we chose earlier for the bank access.

In that object, representing this specific bank access, we have some attributes: There's the id again, no surprise there, there is a providerId, which we could use to query some info on the bank the user chose through a Get Provider call, there is an aktualisierungszeitpunkt which represents the timestamp of the last update (in which we fetched fresh data from the bank), there is some meta info on SCA (sicherheitsverfahren and aktivesSicherheitsverfahren) which is probably not interesting for you right now, a status flag which should be VOLLSTAENDIG by now and an indication of the sync flag, i.e. whether this bank access is persisted on BANKSapi side, can be queried by you any time in the future and will be refreshed from the bank up to four times a day.

Next, there is an array relations, that contains actions that you can take with this bank access and the corresponding URL. See our chapter on HATEOAS for more info on this design.

Then there is another array, bankprodukte. Remember, under one bank access can be multiple bank products, as you can have several accounts with a bank that you can all access with the same set of credentials.

{
    "id": "DE00123456789012345678",
    "status": "VOLLSTAENDIG",
    "bezeichnung": "Girokonto",
    "kategorie": "GIROKONTO",
    "saldo": 2145.78,
    "aktualisierungszeitpunkt": "2020-10-07 13:26:13",
    "saldoDatum": "2020-10-07 00:00:00",
    "waehrung": "EUR",
    "kontonummer": "9012345678",
    "iban": "DE00123456789012345678",
    "bic": "XXX12345678",
    "blz": "12345678",
    "kreditinstitut": "Demo Provider",
    "inhaber": "Fritz Testmüller",
    "relations": [{
            "rel": "start_ueberweisung",
            "href": "https://banksapi.io/customer/v2/ueberweisung/00000000-0000-0000-0000-000000000000/DE00123456789012345678"
        },
        {
            "rel": "self",
            "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/DE00123456789012345678"
        },
        {
            "rel": "get_kontoumsaetze",
            "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/DE00123456789012345678/kontoumsaetze"
        },
        {
            "rel": "get_kontoumsaetze_tagged",
            "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/DE00123456789012345678/kontoumsaetze?tag=true"
        },
        {
            "rel": "get_kontoumsaetze_insurances",
            "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/DE00123456789012345678/kontoumsaetze?tag=insurances"
        },
        {
            "rel": "get_kontoumsaetze_business_partners",
            "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/DE00123456789012345678/kontoumsaetze?tag=business-partners"
        }
    ],
    "messages": [],
    "ueberziehungslimit": 3000.0,
    "verfuegungsrahmen": 2045.78,
    "verfuegterBetrag": 100.0
}

This array contains (probably multiple) bank products. Let's dissect also one of the bank products, e.g. the one on the right.

Again, there is an id, this time of this specific product, there is a status which is the same as for the bank access. Again there is a lot of meta info (see the corresponding Bank Product Schema for a complete list). And there are some relations in the relations array, indicating which actions you can take next:

Relation Explanation Corresponding call
self Query only this bank product Get Bank Product
start_ueberweisung Initiate a wire transfer from this account. This relation is only returned for accounts from which BANKSapi supports transfers, mainly payment accounts Create Transfer
get_kontoumsaetze Get turnovers for this product Get Transactions
get_kontoumsaetze_tagged Get turnovers for this product, tagged (categorized) Get Spending Tags
get_kontoumsaetze_insurances Get turnovers for this product, tagged with insurance tags (only the ones that are insurance turnovers of course) Get Insurance Tags
get_kontoumsaetze_business_partners Get turnovers for this product, tagged with normalized business partners

We're interested in the turnovers of this account, so we'll fetch those next, using the get_kontoumsaetze relation.

Query Turnovers

GET /customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/DE00123456789012345678/kontoumsaetze HTTP/1.1
Host: banksapi.io
Authorization: Bearer 0bac1d52-4eb0-4fe2-951e-cf6ff9dc4235

The turnovers we can query with a bank-product-specic URL, given to us through the get_kontoumsaetze relation earlier. We'll use that URL with the Get Transactions call. You can see the call on the right.

[
    {
        "id": "1975f080-0001-b4f7-727b-aec310895541",
        "betrag": -100.0,
        "verwendungszweck": "GA NR00006110 BLZ70020270 3 07.02/14.29UHR MÜNCHEN,KARD EUR 100,00 ENTGELT 0,00 Ref. 3QL15041A1357856/83343",
        "buchungstext": "",
        "buchungsdatum": "2020-10-05 00:00:00",
        "wertstellungsdatum": "2020-10-02 00:00:00",
        "gegenkontoInhaber": "",
        "gegenkontoIban": "",
        "gegenkontoBic": "",
        "primanotaNummer": "0",
        "hash": "1b4f7727-baec-3107-9554-1cf472933ccf"
    },
    {...}
]

As a result, we're greeted with an array of turnovers. For details on the attributes, head over to the Transaction Schema

Force a Refresh of Data From the Bank

POST /customer/v2/bankzugaenge?refresh=true HTTP/1.1
Host: banksapi.io
Content-Type: application/json
Authorization: Bearer 0bac1d52-4eb0-4fe2-951e-cf6ff9dc4235

{
    "629e4510-5331-47d4-9bad-8902039ff762": {
    }
}

Although we refresh synced bank accesses up to four times a day, in some cases, you might want to force BANKSapi to fetch fresh data from the provider. It is therefore a good idea to implement some kind of refresh button for the user, which in turn should force an actual refresh from the bank and not just return cached data from BANKSapi.

In order to force BANKSapi to fetch fresh data, we will use the same call that we used when creating a bank access, only this time we are using the UUID of the bank access we want to refresh, and add a refresh=true as a query parameter, as in the example on the right.

This time, this will be confirmed by a 201 Created HTTP status, indicating the refresh has been triggered. You can now query the bank access again and should see fresh data.

At some point, the user consent we create implicitly with the previous calls will run out. Bear in mind, this is the consent the users gave to us to fetch data from the bank, so the bank will honour this consent and we have no choice but to renew it. Usually, under PSD2, the consent is valid for 90 days, although some products from some banks require more frequent renewals (some even for every refresh) and there are always things that can prevent us from fetching fresh data from the bank, e.g. a locked account or the user manually removing the consent.

A renewal of consent is a fancy way of saying the user has to enter a TAN or going through a similar process with a TAN-less SCA method such as AppTAN.

We will indicate the necessity of SCA renewal with a start_sca relation. In this case, we might have been able to refresh some but not all bank products, or none at all, and will remain in this state until the user refreshes their consent. In the meantime, you will still be able to query data from BANKSapi, but it will not be the most recent but the last state that we were still be able to fetch.

{
    "rel": "start_sca",
    "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/consent/59f168d6-3a45-4db5-bcd5-94f29d64bbfa"
},

Therefore, if you encounter a start_sca relation, you will have to have the user go through the SCA process again, similar to when they added the bank account, but without them having to chose the provider or enter their credentials. In this case, it's just the SCA process they will have to go through

HTTP/1.1 451 Unavailable For Legal Reasons
Location: https://banksapi.io/customer/v2/webform?session=c2a71efd-71b0-47ea-951a-2abcea1c8578&useCase=AUTHENTICATE_ACCOUNT

So we realize the consent has expired and the user has to complete the SCA process, because we received a start_sca relation with the bank access. Now we proceed as documented in Operations with SCA and POST to the start_sca relation. In response, we will receive a response like the one on the right. Now, the HTTP 451 Unavailable for Legal Reasons status code seems familiar, doesn't it? Now, we follow the same procedure as before while Creating the bank access, adding a callbackUrl and sending the user over to BANKSapi. When the user returns, the bank access should be fully accessible again and start_sca gone.

Query Issues

The bank access, bank products and transactions we return are in a so-called “stable” state, meaning that this is the best data that is available to us. We update this stable state only if a refresh from a bank is successful. However, if fetching a bank access yields any issues, e.g. when the user has changed their login credentials without our knowledge, the stable state is unchanged because we do not want to taint the data with “bad” new data, potentially removing transactions from the storage you are relying on because we do not “see“ them.

Inevitably, there will be an account that is not refreshed any more. It is therefore a good practice to implement the call to fetch potentials issues as well. Best case, the list of messages is returned empty and there is nothing to do.

{
    "rel": "get_issues",
    "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762/issues"
}

To fetch bank access issues, we will use get_issues relation that is returned as part of the bank access. We will receive what will look like a subset of a bank access, but in this case it is not in the "stable" state but in a state we call "tentative", i.e. containing not the best data available to us, but the latest state, and thus any issues that might have arisen during fetching updated data from the bank.

{
    "id": "629e4510-5331-47d4-9bad-8902039ff762",
    "tanMedien": [],
    "providerId": "00000000-0000-0000-0000-000000000000",
    "sicherheitsverfahren": [],
    "aktualisierungszeitpunkt": "2020-10-07 13:26:13",
    "messages": [{
        "code": "BA1011",
        "level": "ERROR",
        "details": "Ungültige Zugangsdaten",
        "message": "Zugangsdaten nicht korrekt"
    }],
    "relations": [{
        "rel": "delete_bankzugang",
        "href": "https://banksapi.io/customer/v2/bankzugaenge/629e4510-5331-47d4-9bad-8902039ff762"
    }]
}

For all errors and issues that can arise, head over to the docs on Message codes.

Where to Go From Here

You've done the first steps with our API - why not explore a bit yourself? HATEOAS makes it very easy to start exploring the API through relations - or you can go on reading this documentation.

Some hints on what to do next:

BANKSapi Auth API

If you are more interested in the customer data, we would like to recommend our quick start guide.

The BANKSapi Auth API provides functions for managing users. Using the OAuth2 protocol you can create tokens to enable only those functions that are necessary for the respective use case.

The API is similar in structure to the other BANKSapi Banks/Connect APIs. That means above all, that everything written in the Banks/Connect API Overview applies to this API.

The use of this API is a basic requirement for the connection of all APIs offered by BANKSapi.

BANKS/Connect Customer API

This API forms the core of BANKSapi Banks/Connect. This allows your end customers to access your financial life and make transactions within your product.

The core element of the API is the Customer, which you can use to Relations dive in detail into the data that can be determined about your customer can.

This document contains the API Reference. But before you get into the details. you may use the API with our Quick Start Guide directly and without any further hurdles.

Topics & Concepts

REG/Protect (redirect solution)

The BANKSapi "REG/Protect-as-a-Service", allows users to perform authorization completely in the front end of the BANKSapi. The account information is stored by BANKSapi. The sensitive payment data is transferred directly from the end user to the BANKSapi systems, processed by BANKSapi and stored by BANKSapi. It is not possible to read the sensitive payment data from BANKSapi.

In addition to regulated clients, as a non-regulated client you can also use BANKSapi REG/Protect to extend your range of services to include use cases based on the use of an account information service (KID) and a payment initiation service (ZAD), but without your own ZAD licence or KID registration. Since 2018, BaFin has been obliged to register/license payment accounts if online banking is used to access payment account data and trigger payments.

Parallel requests

BANKSapi tries as hard as possible to avoid restrictions regarding parallel calls. Unfortunately, some banks and service providers do not allow parallel calls. Therefore, a client should make sure that multiple business transactions such as transfers and/or data updates are not triggered in parallel for a set of access data. Otherwise the respective banks will terminate already running queries, which can lead to problems in further processing.

Background update

A background update can be requested when adding a bank account. The bank access and its turnover are then queried and updated four times (4x) a day by the provider.

Notifications (Webhooks)

If the background update for a bank access is active, a webhook can be specified. In case of new transactions during an update, an external URL can be called with a reference to the bank access.

Notifications are not guaranteed: If the endpoint is not available, the HTTP call is stored in a queue and the system tries to execute it several times until the remote server on your side can accept the call. However, if this is not the case even after a few minutes, the notification will be discarded.

You can use the sequential integer sequence number serial to check whether there have been gaps or failures since the last notification.

Strong customer authentication

SCA is used to determine the identity of the end customer. SCA uses two out of three factors of:

We differentiate between TAN and TAN-less security mechanisms.

The TAN procedures such as smsTAN, eTAN, chipTAN, photoTAN, pushTAN etc. are most frequently used.

TAN-less / decoupled methods include apps provided by the banks to the end customers that can be used to just approve of activities. In this case, the phone itself is the posession factor. Another name for this method is BestSign. For Submit SCA Authentication Data, this means that an empty object can be submitted to indicate the user indicated that he meanwhile confirmed the activity, e.g. through the bank app.

Please note that not all safety procedures are supported by HBCI.

TAN medium

The TAN medium has the function of an intermediary. For example, the TAN itself (smsTAN) or the instruction for generating or determining a TAN is forwarded to the customer.

The TAN medium can also be used to generate customer-specific TANs. (e.g. chipTAN procedure by using the EC card).

Here are a few examples of TAN procedures and TAN media:

TAN procedure Media class Name
mobileTAN (mTAN) Mobile phone +49-1111-1111111
smsTAN Mobile +49-1111-111111
chipTAN Generator with EC Card Sample Bank Card 1234567890
Sm@rtTAN Generator with bank card Sample bank card 1234567890
e-TAN Generator Generator
photoTAN App or generator Phone of User X
PushTAN / appTAN App Phone of User X

REG/Protect

The REG/Protect redirect solution provides an HTML frontend for adding bank accounts and triggering payments.

Context info when returning to your app

The return of the user can take place for different reasons, the reason is communicated in the query parameter baReentry:

Type of return Reason Example Value for baReentry
Process successfully completed professional FINISHED
User does not agree with AGB/DSE technical LEGAL_NOT_ACCEPTED
Click on "Go to customer portal" Business Click on page "Select bank" USER_CANCELLED
Termination of the process Business Termination on "Your accounts" page USER_CANCELLED
Unexpected HTTP Repsonse Code technical HTTP 200 expected but HTTP 500 delivered BACKEND_ERROR
Unexpected HTTP response (body) Technical Valid JSON expected but invalid delivered ACKEND_ERROR
Access data incorrectly entered three times technical INVALID_CREDENTIALS
TAN incorrectly entered three times domain name INVALID_TAN
General error Technical Guard prevents mask access; possible manipulation attempt ERROR
No accounts found for bank transfer Depreciation area No accounts or no accounts suitable for bank transfer were found when the bank transfer was started NO_ACCOUNTS

Adding and authenticating bank accounts

$ curl https://banksapi.io/customer/v2/bankzugaenge \
    -X POST \
    -H 'Expect: ' \
    -H 'authorization: Bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json' \
    -H 'content-type: application/json' \
    -d '{"637a3945-bb02-4e82-ac9e-f7c26d2568ce": {}}'

< HTTP/1.1 451
< Content-Length: 0
< Location: https://banksapi.io/customer/v2/webform?session=b19c3937- ... -3b861be7e71e
    &useCase=CREATE_ACCOUNT

When you create a bank access as a non-regulated client, you will receive the URL for this call with a 451 HTTP-Response in the Location-Header. The status code serves as an indicator that the use case must be continued in the context of the BANKSapi REG/Protect. During usage, at any time one or many consents of the customer might expire. Therefore, expect a URL to the REG/Protect frontend with an authenticate relation. In this case, the use case (see parameters below) will be AUTHENTICATE_ACCOUNT, the rest will stay the same.

The location header then contains the URL to be called on the BANKSapi page. The Web Form should be called up in the same browser window and replace the current content. For security reasons, it can only be called up once. This starts the RegProtect process at BANKSapi and the end customer has the possibility to select a provider and enter his online banking access data in the following masks delivered by BANKSapi.

You must append a query parameter callbackUrl to this URL (URL-encoded), which is called again by BANKSapi after the successful (or failed) registration of the end customer's account.

All query parameters of the REG/Protects for adding a bank account in the overview:

Field Type Included Description
useCase String Always CREATE_ACCOUNT or AUTHENTICATE_ACCOUNT
callbackUrl String Always The URL on your page that the user will be redirected to after registering with BANKSapi. *Warning: Must be URL-encoded **

The callbackUrl is then the URL to which the user is forwarded after registration. It is called by the user's browser (in the popup window you open, as GET) with the entire query string you supply, so you can also specify your own parameters, which are then handled transparently by BANKSapi. Logically, there should be a frontend page under the URL, since it is then displayed to the user.

In addition to the query string you specified in the callbackUrl, the following query parameters are also sent (appended to the URL, ?parameter1=value1&parameter2=value2`):

Field Type Included Description
baReentry String Always If successful FINISHED

Triggering a payment

&lt;font color="#ffff00"&gt;-=https://banksapi.io/customer/v2/ueberweisung/e1f30693-=- proudly presents -bab3bc2/DE00123456789012345679 \
    -X POST \
    -H 'authorization: Bearer 9df54960-f678-47ec-84dc-6c771f9c980c' \
    -H 'content-type: application/json' \
    -d '{}'

< HTTP/1.1 451
< Content-Length: 0
< Location: https://banksapi.io/customer/v2/webform?session=b19c3937- ... -3b861be7e71e
    &useCase=START_TRANSFER

A payment is triggered in the same way as an account is added, first by calling the end point documented under Create transfer using HTTP POST. Since all payment data is determined during the process at BANKSapi, it is sufficient here to transfer only an empty JSON object as a payload.

As in the use case before, a 451 (Unavailable For Legal Reasons) is delivered with Location-HTTP header.

To this URL you have to append a query parameter callbackUrl (https://de.wikipedia.org/wiki/URL-Encoding), which is called again by BANKSapi after the successful or failed triggering of the transfer.

All query parameters of the REG/Protects for adding a bank account in the overview:

Field Type Included Description
useCase String Always START_TRANSFER
callbackUrl String Always The URL on your page that the user will be redirected to after the BANKSapi referral process. *Warning: Must be URL-encoded **

The callbackUrl is then the URL to which the user is redirected after the transfer. It is called by the user's browser (in the window you open, as GET) with the entire query string you provide, so you can also specify your own parameters, which are then handled transparently by BANKSapi. Logically, there should be a frontend page under the URL, since it is then displayed to the user.

In addition to the query string you specified in the callbackUrl, the following query parameters are also sent (appended to the URL, ?parameter1=value1&parameter2=value2`):

Field Type Included Description
baReentry String Always If successful FINISHED

Operations with SCA

Due to the PSD2 requirements in respect to SCA, there is a multi-step process involved in order to add a bank access.

The process differs depending on whether you are using REG/Protect or not:

REG/Protect Task Process description
Yes Create a bank access When creating a bank access, the multi-step process will be covered by us through the REG/Protect frontend. Find the documentation in Adding bank accounts with REG/Protect
Yes Refresh a bank access During usage, the consent of the customer might expire at some point and new data can't be fetched from the bank. You can refresh with new data from the bank with a refresh-flag as documented. Whenever there is a relation start_sca, POST to the start_sca relation to indicate the user is ready to start an SCA process. You will receive a 451 status with a Location-header. Display the contents of the Location-Header to the user in the same way you would with the Location-Header when adding a bank account. This is to refresh the SCA with the bank in order to get up-to-date data from the bank.
No Create a bank access When using the embedded approach (without REG/Protect), there are several steps you need to undertake.

When creating the bank access, there will may be the following relations in this order, if applicable (some might be skipped, e.g. if there is only one possible SCA method, it will be selected automatically):
  • set_method: This relation is sent with appropriate sicherheitsverfahren in the bank access. Use it as documented in Set SCA Method
  • set_medium: Not to be confused with set_method, this relation is sent with appropriate tanMedien in the bank access. Use it as documented in Set SCA Method
  • authenticate: This relation serves two purposes: For TAN procedures as described in Strong Customer Authentication, this hrefshould be called with PUT as described in Submit SCA Authentication Data. For TAN-less methods, POST an empty object to this href to indicate the user has completed the decoupled challenge on bank side, e.g. when he has confirmed the activity in the bank app.
  • No Refresh a bank access During usage, the consent of the customer might expire at some point and new data can't be fetched from the bank. In this case, the BankAccess object will contain a relation start_sca. POST an empty object to this relation in order to indicate that the user is ready to start an SCA process.

    There are two cases what can happen, depending on which SCA approach the bank is imposing:

    Embedded SCA (standard case): The process will be the same as for creating a bank access as documented above (set_method, set_medium, authenticate)

    Redirect SCA: Redirect means that although we are not using REG/Protect, the bank imposes a redirect-approach similar to 3DS for card payments. This means that an HTML-page served by the bank server must be displayed to the user, in the bank's look & feel. This will be indicated by a Location header returned with the POST to the start_sca relation. To the URL that is returned a callbackURL should be appended as a GET parameter as described in REG/Protect: Adding and authenticating bank accounts, the rest of the process follows the pattern described in this chapter as well, although no BANKSapi UI will be shown to the user at any time. At the end pof the SCA process, the user will be returned to the callbackUrl with the appropriate parameters.

    Encryption

    To encrypt the Credentials, the asymmetric crypto procedure RSA is used. If you become our customer, you will receive a public key from us with which the encryption is performed.

    Since the concrete implementation of encryption in the different programming environments is different from each other the characterizing properties of the process (specified in the following table) are used. PKCS #1), with which the conversion in your preferred development environment should not be a problem:

    Notifications

    Webhook calls ("notifications") can be made as POST in the following incidents during a background update (independently of each other):

    Event Description
    Transaction New transaction(s) found
    Balance, the balance's changed.
    Error Error
    POST /your-notification endpoint HTTP/1.1
    User Agent: BANKSapi Notifier
    &lt;font color="#ffff00"&gt;Sync by honeybunny &lt;font color="#ffff00"&gt;www.ihre-domain.com
    Content-Type: application/json
    Accept: */*
    Connection: close
    

    The POST`-HTTP call looks like this during the call:

    Header Value
    User-Agent `BANKSapi Notifier
    Content-Type application/json
    Accept, accept.

    Notification object

    The payload, i.e. the BODY of the POST-Requests contains at least the following fields for all types of notifications:

    Field Type Included Description
    userId String Always userid`` of the user as OAuth-Token
    accountId String Always id of [bank access]
    tenant String Always name` of [Tenant]
    notificationType String Always Contains the Notification Type
    occurred timestamp Always Time of triggering the notification
    serial Integer Always Consecutive, integer sequence number of the notification for checking missed notifications

    Notification Type

    Event Type
    Transaction `TRANSACTION
    Balance `BALANCE
    Error `ERROR

    Transaction Notification

    {
        "userId": "mOd2uKYr+2 ... TWOPCAt5zP",
        "accountId": " 3671fbf6-c752-4107-a9c0-61ea77cd7f5e",
        "tenant": "demo",
        "notificationType": "TRANSACTION",
        "occurred": "2019-05-11 09:05:00",
    
        "productId": "DE1235233452324553423442A",
        "newTransactions": [{
            "payeeName": "La Sopia GmbH Munich",
            "amount": -70
        }, {
            "payeeName": "netzpolitik.org e. V.",
            "amount": -1337.42
        }]
    }
    

    In the event that one or more new transactions are found, this object is sent by the notifier. It contains additional to the fields of the Notification object:

    Field Type Included Description
    productId String Always Contains the id of the [bank product]
    newTransactions Array of Transaction objects Always Contains the new turnovers in the form of Transaction objects

    Transaction object

    {
        "payeeName": "La Sopia GmbH Munich",
        "amount": -70
    }
    
    Field Type Included Description
    payeeName String Always Contains the id of the [#get-bank-product]
    amount Number If available Amount of turnover, negative for outputs if applicable

    Request-Body

    The request body consists of a Transaction Notification Object.

    Balance Notification

    {
        "userId": "mOd2uKYr+2 ... TWOPCAt5zP",
        "accountId": " 3671fbf6-c752-4107-a9c0-61ea77cd7f5e",
        "tenant": "demo",
        "notificationType": "BALANCE",
        "occurred": "2019-05-11 09:05:00",
    
        "productId": "DE1235233452324553423442A",
        "oldBalance": 200000.00,
        "newBalance": 205000.00
    }
    

    If the account balance or position of a bank product has changed, this object is sent by the notifier. It contains additional to the fields of the Notification object

    Field Type Included Description
    productId String Always Always
    oldBalance Number Always Contains the old account balance or balance before the last background update.
    newBalance Number Always Contains the new account balance or position determined by the current background update.

    Request-Body

    The request body consists of a Balance Notification Object.

    Error Notification

    {
        "userId": "mOd2uKYr+2 ... TWOPCAt5zP",
        "accountId": " 3671fbf6-c752-4107-a9c0-61ea77cd7f5e",
        "tenant": "demo",
        "notificationType": "ERROR",
        "occurred": "2019-05-11 09:05:00",
    
        "level": "ERROR",
        "Code": "BA1010",
        "message": "Access blocked"
    }
    

    If an error occurred during the Background update, this object is sent by the notifier. It contains additional to the fields of the Notification object

    Field Type Included Description
    level** String Always one of INFO``,WARNING,ERROR```
    code String Always See Errors and Messages
    message String Always See Errors and Messages
    data String If available Further information as String

    Request-Body

    The request body consists of an Error Notification Object.

    Transaction tags (categorization)

    The current list of categories for the Classification can change at any time, even without changing the version number of the API.

    Parent Category Category Display Name (de_DE)
    BANKFINANCE Bank und Finanzen
    BANKFINANCE BANKFINANCE_CASHWITHDRAWAL Barauszahlung
    BANKFINANCE BANKFINANCE_CREDITPAYMENT Kredittilgung
    BANKFINANCE BANKFINANCE_CURRENCY Devisen- / Sortengeschäfte
    BANKFINANCE BANKFINANCE_OTHER Bank und Finanzen - Sonstiges
    BANKFINANCE BANKFINANCE_INVESTMENT Investment
    BANKFINANCE BANKFINANCE_TAXES Steuern
    BILLS Vertragsrechnungen
    BILLS BILLS_PUBLICRADIO Öffentlich-rechtlicher Rundfunk
    BILLS BILLS_WATERANDDISPOSAL Wasser und Entsorgung
    BILLS BILLS_TELECOMMUNICATIONS Internet und Telekommunikation
    BILLS BILLS_OTHER Vertragsrechnungen - Sonstiges
    BILLS BILLS_ENERGY Energiekosten
    EDUCATION Bildungswesen
    EDUCATION EDUCATION_TRAINING Fortbildung
    EDUCATION EDUCATION_SCHOOL Schulbildung
    EDUCATION EDUCATION_ACADEMIC Universität
    EDUCATION EDUCATION_OTHER Bildungswesen - Sonstiges
    FAMILY FAMILY_TOYS Spielwaren
    FAMILY Kinder und Familie
    FAMILY FAMILY_CHILDACTIVITIES Kinderaktivitäten
    FAMILY FAMILY_CHILDCARE Kinderbetreuung
    FAMILY FAMILY_CHILDNECESSITIES Kinder- und Babybedarf
    FAMILY FAMILY_OTHER Familie - Sonstiges
    FAMILY FAMILY_SUPPORT Unterhalt
    HEALTH HEALTH_CONSUMABLES Arznei und Heilmittel
    HEALTH HEALTH_OPTICS Augenoptik
    HEALTH Gesundheit
    HEALTH HEALTH_SERVICES Arzt/Krankenhaus/Pflege
    HEALTH HEALTH_OTHER Gesundheit - Sonstiges
    HOUSING HOUSING_RENOVATION Renovierung
    HOUSING HOUSING_FURNISHING Möbel und Haushaltsgeräte
    HOUSING HOUSING_OTHER Wohnen - Sonstiges
    HOUSING Wohnen
    HOUSING HOUSING_ANCILLARYCOSTS Nebenkosten
    HOUSING HOUSING_RENT Miete/Wohngeld
    HOUSING HOUSING_SERVICES Haushaltsdienstleistungen
    HOUSING HOUSING_FINANCING Immobilienkredit
    INCOME INCOME_REFUND Gutschriften und Erstattungen
    INCOME Einnahmen
    INCOME INCOME_RETURNDEBIT Rücklastschriften
    INCOME INCOME_CASHDEPOSIT Bareinzahlung
    INCOME INCOME_CREDIT Krediteinnahme
    INCOME INCOME_OTHER Einnahmen - Sonstiges
    INCOME INCOME_PENSION Rente und Pension
    INCOME INCOME_RENTAL Vermietung und Verpachtung
    INCOME INCOME_SALARY Gehalt
    INCOME INCOME_STATEEDUCATION Staatliche Förderung für Bildung
    INCOME INCOME_STATEFAMILY Staatliche Förderung für Familie und Kinder
    INCOME INCOME_SOCIALBENEFIT Sozialleistung
    INCOME INCOME_INSURANCE Versicherungseinnahmen/-gutschriften/-rückzahlungen
    INCOME INCOME_INVESTMENT Kapitaleinkommen
    INSURANCE INSURANCE_ACCIDENT Unfallversicherung
    INSURANCE Versicherungen
    INSURANCE INSURANCE_HEALTH Krankenversicherung
    INSURANCE INSURANCE_LEGAL Rechtsschutzversicherung
    INSURANCE INSURANCE_LIABILITY Haftpflichtversicherung
    INSURANCE INSURANCE_LIFE Lebensversicherung
    INSURANCE INSURANCE_TRAVEL Reiseversicherung
    INSURANCE INSURANCE_VEHICLE KFZ-Versicherung
    INSURANCE INSURANCE_OTHER Versicherungen - Sonstiges
    INSURANCE INSURANCE_PROPERTY Sachversicherung
    INSURANCE INSURANCE_TRANSPORT Transportversicherung
    LIVING LIVING_OTHER Lebenshaltung - Sonstiges
    LIVING Lebenshaltung
    LIVING LIVING_DRUGSTORE Drogerie
    LIVING LIVING_CHARITY Spenden & Wohltätigkeit
    LIVING LIVING_GROCERIES Lebensmittel
    MOBILITY MOBILITY_BIKESHARE Bike-Sharing
    MOBILITY MOBILITY_PUBLICTRANSPORT ÖPNV
    MOBILITY MOBILITY_VEHICLEACQUISITION KFZ - Kredit/Kauf/Leasing
    MOBILITY MOBILITY_PARKING Parken
    MOBILITY MOBILITY_TAXI Taxi
    MOBILITY MOBILITY_FUEL Kraftstoffe und Schmiermittel
    MOBILITY MOBILITY_SERVICES Wartung, Pflege und Reparaturen
    MOBILITY MOBILITY_CARSHARE Car-Sharing
    MOBILITY MOBILITY_OTHER Mobilität - Sonstiges
    MOBILITY Mobilität
    OTHER Sonstiges
    OTHER OTHER_OTHER Sonstiges
    RECREATION RECREATION_PRINTED Bücher und Zeitschriften
    RECREATION RECREATION_CULTURAL Kultur
    RECREATION RECREATION_FOODANDDRINKS Ausgehen und Essen
    RECREATION RECREATION_OTHER Freizeit und Unterhaltung - Sonstiges
    RECREATION RECREATION_SPORTS Sport und Fitness
    RECREATION RECREATION_PETS Haustier
    RECREATION Freizeit und Unterhaltung
    RECREATION RECREATION_ONLINE Spiele und Online-Unterhaltung
    RECREATION RECREATION_HOBBYANDSOCIAL Hobbys und soziale Aktivitäten
    SAVINGS SAVINGS_BUILDING Bausparguthaben
    SAVINGS SAVINGS_ACCOUNT Sparguthaben
    SAVINGS SAVINGS_OTHER Sparen - Sonstiges
    SAVINGS Sparen
    SERVICES SERVICES_MAIL Offline-Dienstleistungen
    SERVICES SERVICES_OTHER Dienstleistungen - Sonstiges
    SERVICES SERVICES_PERSONAL Persönliche Dienstleistungen
    SERVICES SERVICES_PROFESSIONAL Professionelle Dienstleistungen
    SERVICES Dienstleistungen
    SHOPPING SHOPPING_OTHER Shopping - Sonstiges
    SHOPPING Shopping
    SHOPPING SHOPPING_ONLINE Online-Shopping
    SHOPPING SHOPPING_ELECTRONICS Elektrogeräte
    SHOPPING SHOPPING_BEAUTY Schönheitsprodukte
    SHOPPING SHOPPING_CLOTHINGACCESSORIES Kleidung und Accessoires
    SHOPPING SHOPPING_DEPARTMENTSTORE Kaufhaus
    TRANSFER TRANSFER_BANKFINANCE Kontotransfer
    TRANSFER TRANSFER_OTHER Transfer - Sonstiges
    TRANSFER TRANSFER_CREDITCARDSETTLEMENT Kreditkartenabrechnung
    TRANSFER Transfer
    TRAVEL Reisen
    TRAVEL TRAVEL_INCLUSIVEOFFERS Pauschalreisen
    TRAVEL TRAVEL_TRANSPORT Transport
    TRAVEL TRAVEL_ACCOMMODATION Unterkunft
    TRAVEL TRAVEL_OTHER Reise - Sonstiges

    Errors and messages

    In the communication between client, BANKSapi Banks/Connect and the providers, errors can occur. which can be caused by a wide variety of constellations. We are always makes every effort to transport the cause of an error to you as informatively as possible so that can be reacted to accordingly quickly.

    A simple use case is, for example, that the login of a customer to his bank is not worked. As an error message, the system returns, for example, that the user ID is not was 10 digits long and so the login data was not correct. The customer is thus in a position to "problem" quickly.

    HTTP status codes

    Status Name Meaning API Handling
    200 OK The request has been successfully executed -
    201 Created The request was executed successfully and the data object was created Evaluate and call location header
    400 Bad Request The request is syntactically wrong Program error at the caller, manual intervention necessary
    401 Unauthorized The authorization: bearer TOKEN header was not sent Send header
    403 Forbidden The OAuth2 token has expired, is invalid or the required scope is missing Request new token, extend scopes
    404 Not found The URL does not point to a valid object Start new data retrieval and update relations
    451 Unavailable for Legal Reasons The requested resource cannot be returned for regulatory reasons. This is used in the course of the REG/Protects, the HTTP response contains a Location` header with the URL for the redirect
    500 Internal Server Error This shouldn't have happened We're already working on it
    504 Gateway Timeout The started request could not be answered within the specified time Repeat request shortly

    Message codes

    {
       "level": "ERROR",
       "code": "BA1011",
       "message": "Access data not correct ",
       "details": "Please check your access data and try again. Please note that your access data will be blocked if you enter it incorrectly three times."
    }
    
    Code Level Message Details
    BA999 ERROR Internal error
    BA1010 ERROR Access blocked Your PIN for Internet banking was entered incorrectly three times. So we've temporarily suspended your access for security reasons
    BA1011 ERROR Access data not correct Please check your access data and try again. Please note that your access data will be blocked after three incorrect entries.
    BA1012 ERROR Incomplete access data The following access data is required: Authfields 1 = Example user name 2 = Example PIN 3 = Example key
    BA1051 ERROR Bank access not available Maintenance: A technical malfunction has occurred at your bank. Please update your bank account at a later date.
    BA1052 ERROR Bank account not fully accessible
    BA1060 ERROR Product could not be updated
    BA1062 ERROR Revenues could not be updated
    BA1063 ERROR Depot positions could not be updated
    BA1100 ERROR Invalid bank transfer data Please check your entries. Transfers are only possible to the reference account.
    BA1101 ERROR Invalid TAN procedure
    BA1103 ERROR TAN invalid Error during transmission, or mTan not (any longer) valid
    BA1104 ERROR Bank transfer not possible Bank transfers are only supported for checking accounts or HBCI message 9390 Order rejected due to double submission.
    BA1110 INFO TAN input required Please enter the SMS-TAN
    BA1111 INFO The transfer was successfully completed
    BA2002 INFO There are messages from your bank There are messages from your bank, please log into your online banking.
    BA3000 INFO SCA required SCA required
    BA3010 INFO Select SCA method Select SCA method
    BA3020 INFO Select SCA medium Select SCA medium
    BA3030 INFO SCA Challenge SCA Challenge
    BA3040 INFO SCA failed SCA failed
    BA3060 INFO No supported SCA method found No supported SCA method found

    BANKS/Connect Providers API

    If you are more interested in the customer data, we would like to recommend our quick start guide.

    Via the Banks/Connect Providers API you get access to a comprehensive configuration database for the banks and service providers supported by us.

    The API is similar in structure to the other BANKSapi Banks/Connect APIs. That means above all, that everything written in the Banks/Connect API Overview applies to this API.

    In addition to general master data such as name, bank group, bank code and BIC, you also receive detailed machine-readable information on the login modalities for your users, so that you can optimize the user experience of your application when creating bank accounts.

    A concrete example of this data can be found in the Provider section.


    title: BANKS/

    BANKS/Connect API Reference v2.0

    Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

    Base URLs:

    Authentication

    Auth API

    Create User

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/auth/mgmt/v1/tenants/{tenant-name}/users \
      -H 'Content-Type: application/json'
    
    

    POST /auth/mgmt/v1/tenants/{tenant-name}/users

    Creates a technical user corresponding (one-to-one) a tenant's user. Users are needed to use BANKSapi's core features like adding accounts or performing payments. After creating a user, they're automatically activated.

    Body parameter

    {
      "username": "demouser",
      "password": "secret",
      "firstname": "demo",
      "lastname": "user"
    }
    

    Parameters

    Name In Type Required Description
    tenant-name path string true Tenant name plays a role in using the API. The tenant name is a URL component in the management API.
    body body CreateUser true The request body is a JSON object containing data required for user creation

    Responses

    Status Meaning Description Schema Possible relations
    201 Created Returns with a location header under which the user data can be retrieved. None none

    Response Headers

    Status Header Type Format Description
    201 Location string none

    Get Users

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/auth/mgmt/v1/tenants/{tenant-name}/users \
      -H 'Accept: application/json'
    
    

    GET /auth/mgmt/v1/tenants/{tenant-name}/users

    Get all activated users

    Parameters

    Name In Type Required Description
    tenant-name path string true Name of the tenant

    Example responses

    200 Response

    [
      {
        "userReference": "1c5b33f6-9c4d-11e6-ba80-480fcfb9550f",
        "username": "demo-user"
      }
    ]
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns an array of User Inline none

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    anonymous [User] false none [This object represents a unique user.]
    » User User false none This object represents a unique user.
    »» userReference string true none Technical ID for the user, is also used in URLs (user-id)
    »» username string true none Username for creating an OAuth2 token

    Create Token

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/auth/oauth2/token \
      -H 'Content-Type: application/x-www-form-urlencoded' \
      -H 'Accept: application/json' \
      -H 'Authorization: Basic {banksapi-prod-base64-client-credentials}'
    
    

    POST /auth/oauth2/token

    Creates a client or user token valid for 24 hours. Client tokens are needed for administrative use cases such as creating users. User tokens are needed when creating or querying banking accounts.

    Body parameter

    oneOf:
      - title: CreateClientToken
        required:
          - grant_type
        type: object
        description: Parameters to supply upon client token request
        properties:
          grant_type:
            type: string
            description: Must always be **client_credentials**
          scope:
            type: string
            description: >-
              Space-separated list of desired scopes. A scope names a class of
              access rules. It is a string, usually in the form of a (fictitious)
              URL. The available scopes depend on the scope of services booked. You
              therefore receive the scope list together with your cooperation
              agreement.
        example:
          grant_type: client_credentials
          scope: 'http://banksapi.io/provider/read'
      - title: CreateUserToken
        required:
          - grant_type
          - username
          - password
        type: object
        description: Parameters to supply upon client token request
        properties:
          grant_type:
            type: string
            description: Must always be **password**
          username:
            type: string
            description: Username of user
          password:
            type: string
            description: Password of user
          scope:
            type: string
            description: >-
              Space-separated list of desired scopes. A scope names a class of
              access rules. It is a string, usually in the form of a (fictitious)
              URL. The available scopes depend on the scope of services booked. You
              therefore receive the scope list together with your cooperation
              agreement.
        example:
          grant_type: client_credentials
          scope: 'http://banksapi.io/provider/read'
    
    

    Parameters

    Name In Type Required Description
    Authorization header string true The Authorization header contains the client credentials to authenticate a tenant
    body body any true The request body contains form object with following parameters

    Example responses

    200 Response

    {
      "scope": "http://banksapi.io/customer/read http://banksapi.io/customer/modify",
      "tenant": "demo",
      "client": "demo-client",
      "access_token": "0defaced-1337-d00d-c0de-face8badcafe",
      "token_type": "Bearer"
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns token object Token none
    401 Unauthorized The header authorization: Bearer TOKEN was not sent None none

    Get Tenants

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/auth/mgmt/v1/tenants \
      -H 'Accept: application/json'
    
    

    GET /auth/mgmt/v1/tenants

    Get all tenants

    Example responses

    200 Response

    [
      {
        "name": "demo",
        "description": "A Tenant for demonstration purposes"
      }
    ]
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns an array of Tenant Inline none

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    anonymous [Tenant] false none [The tenant object represents our client. It plays a role in using the API only insofar that the tenant name is a URL component in the management API.]
    » Tenant Tenant false none The tenant object represents our client. It plays a role in using the API only insofar that the tenant name is a URL component in the management API.
    »» name string true none Tenant technical name becomes URL component
    »» description string false none Optional human readable description

    Get User

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/auth/mgmt/v1/tenants/{tenant-name}/users/{user-id} \
      -H 'Accept: application/json'
    
    

    GET /auth/mgmt/v1/tenants/{tenant-name}/users/{user-id}

    This function can be used to retrieve a single activated user.

    Parameters

    Name In Type Required Description
    tenant-name path string true Tenant name plays a role in using the API. The tenant name is a URL component in the management API.
    user-id path string true User reference of the user

    Example responses

    200 Response

    {
      "userReference": "1c5b33f6-9c4d-11e6-ba80-480fcfb9550f",
      "username": "demo-user"
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns a User object User none

    Deactivate User

    Code samples

    ## You can also use wget
    curl -X PUT https://banksapi.io/auth/mgmt/v1/tenants/{tenant-name}/users/{user-id}/deactivate
    
    

    PUT /auth/mgmt/v1/tenants/{tenant-name}/users/{user-id}/deactivate

    Deactivates a single user

    Parameters

    Name In Type Required Description
    tenant-name path string true Tenant name plays a role in using the API. The tenant name is a URL component in the management API.
    user-id path string true User reference of the user

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns HTTP status of 200 (OK) None none

    Reactivate User

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/auth/mgmt/v1/tenants/{tenant-name}/users/{user-id}/reactivate \
      -H 'Content-Type: application/json'
    
    

    POST /auth/mgmt/v1/tenants/{tenant-name}/users/{user-id}/reactivate

    Reactivate a single deactivated user

    Body parameter

    {
      "username": "demouser",
      "password": "secret",
      "firstname": "demo",
      "lastname": "user"
    }
    

    Parameters

    Name In Type Required Description
    tenant-name path string true Tenant name plays a role in using the API. The tenant name is a URL component in the management API.
    user-id path string true User reference of the user
    body body CreateUser true The request body is a JSON object containing data required for user reactivation (same as user creation)

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns HTTP status of 200 (OK) None none

    Revoke Token

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/auth/oauth2/revoke \
      -H 'Content-Type: application/x-www-form-urlencoded' \
      -H 'Authorization: Basic {banksapi-prod-base64-client-credentials}'
    
    

    POST /auth/oauth2/revoke

    To revoke a token, the user token is sent to the URL https://banksapi.io/auth/oauth2/revoke via a POST request.

    Body parameter

    type: object
    properties:
      token:
        type: string
        format: uuid
        description: The token to be withdrawn
    
    

    Parameters

    Name In Type Required Description
    Authorization header string true The Authorization header contains the client credentials to authenticate a user with a server for token.
    body body object true The request body contains form object with following parameters
    » token body string(uuid) false The token to be withdrawn

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns HTTP status 200 None none

    Customer API

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/consent/{consent-id} \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json'
    
    

    GET /customer/v2/consent/{consent-id}

    Retrieves consent info for a specific consent

    Name In Type Required Description
    Content-Type header string true none
    consent-id path string true none

    Example responses

    200 Response

    {
      "access": {
        "balances": [
          {
            "iban": "DE2310010010123456789"
          }
        ],
        "transactions": [
          {
            "iban": "DE2310010010123456789"
          }
        ]
      },
      "recurringIndicator": "true",
      "validUntil": "2017-11-01",
      "frequencyPerDay": "4",
      "consentStatus": "valid"
    }
    
    Status Meaning Description Schema Possible relations
    200 OK none Consent none

    Set SCA Method or Medium

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/customer/v2/consent/{consent-id} \
      -H 'Content-Type: application/json' \
      -H 'Accept: text/plain'
    
    

    POST /customer/v2/consent/{consent-id}

    Submits a SCA method or medium for a previously created consent, e.g. when creating a bank access. Valid strings to send are chosenScaMethodId or chosenScaMedia

    Body parameter

    {
      "chosenScaMethodId": "942"
    }
    

    Parameters

    Name In Type Required Description
    consent-id path string true none
    body body CreateScaMethod true none

    Example responses

    200 Response

    Responses

    Status Meaning Description Schema Possible relations
    200 OK none Inline none

    Response Schema

    Submit SCA Authentication Data

    Code samples

    ## You can also use wget
    curl -X PUT https://banksapi.io/customer/v2/consent/{consent-id} \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json'
    
    

    PUT /customer/v2/consent/{consent-id}

    Call this endpoint to answer an SCA challenge with a response

    Body parameter

    {
      "scaAuthenticationData": "123456"
    }
    

    Parameters

    Name In Type Required Description
    Content-Type header string true The Content-Type header is used to specify the nature of the data in the body of a HTTP request.
    consent-id path string true none
    body body ScaAuthenticationData true none

    Example responses

    200 Response

    {
      "scaStatus": "finalised",
      "gueltigBis": "2019-05-02 18:20:48"
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK none Sca none

    Get Customer

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2 \
      -H 'Accept: application/json'
    
    

    GET /customer/v2

    Retrieves the customer object for the authenticated user. It is also the entry point to the deeper functions of the interface.

    Example responses

    200 Response

    {
      "messages": [
        {
          "level": "INFO",
          "code": "BA3010",
          "message": "SCA benötigt",
          "details": "Bitte wählen Sie eine SCA-Methode aus"
        }
      ],
      "bankzugaenge": {
        "4000fda7-18af-463f-b694-bbafe5d23a48": {
          "messages": [
            {
              "level": "INFO",
              "code": "BA3010",
              "message": "SCA benötigt",
              "details": "Bitte wählen Sie eine SCA-Methode aus"
            }
          ],
          "sicherheitsverfahren": [
            {
              "kodierung": 980,
              "name": "mTAN",
              "hinweis": "mTAN"
            },
            {
              "name": "SMS_OTP",
              "kodierung": "942",
              "hinweis": "SMS OTP"
            }
          ],
          "relations": [
            {
              "rel": "startSCA",
              "href": "https://banksapi.io/v2/customer/consent/1345340218050910215PSDDE-BAFIN-152070CO4960JJ"
            }
          ]
        }
      },
      "relations": [
        {
          "rel": "self",
          "href": "https://banksapi.io/customer/v2"
        },
        {
          "rel": "get_bankzugaenge",
          "href": "https://banksapi.io/customer/v2/bankzugaenge"
        },
        {
          "rel": "add_bankzugaenge",
          "href": "https://banksapi.io/customer/v2/bankzugaenge"
        },
        {
          "rel": "delete_bankzugaenge",
          "href": "https://banksapi.io/customer/v2/bankzugaenge"
        }
      ]
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns customer object of the user. Customer self: Get Customer
    get_bankzugaenge: Get bank accesses
    add_bankzugaenge: Add bank access
    delete_bankzugaenge: Delete bank access

    Delete Bank Accesses

    Code samples

    ## You can also use wget
    curl -X DELETE https://banksapi.io/customer/v2/bankzugaenge
    
    

    DELETE /customer/v2/bankzugaenge

    Removes all bank accesses of the authenticated user.

    Responses

    Status Meaning Description Schema Possible relations
    200 OK The HTTP status 200 returns without any further response body. None none

    Get Bank Accesses

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/bankzugaenge \
      -H 'Accept: application/json'
    
    

    GET /customer/v2/bankzugaenge

    Retrieves all bank accesses for this user.

    Example responses

    200 Response

    {
      "85f78300-d993-4b7e-a8d0-8d39a4ba9d2a": {},
      "4000fda7-18af-463f-b694-bbafe5d23a48": {
        "status": "VOLLSTAENDIG",
        "tanMedien": [
          {
            "gueltigVon": "2016-06-03 17:17:41",
            "gueltigBis": "2016-06-03 17:17:41",
            "name": "Mobil",
            "medienklasse": "MOBIL"
          }
        ],
        "sicherheitsverfahren": [
          {
            "kodierung": 2,
            "name": "mTAN",
            "hinweis": "mTAN"
          },
          {
            "kodierung": 1,
            "name": "Mock-TAN",
            "hinweis": "Mock-TAN"
          }
        ],
        "aktivesSicherheitsverfahren": {
          "kodierung": 1,
          "name": "Mock-TAN",
          "hinweis": "Mock-TAN"
        },
        "aktualisierungszeitpunkt": "2016-06-10 17:17:40",
        "timeout": "2016-12-24 13:37:42",
        "messages": [],
        "bankprodukte": [],
        "relations": [],
        "sync": false
      }
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK The success response contains an collection of bank accesses. ListOfBankAccesses self: Querying bank access
    delete_bankzugang: Delete bank access
    set_method: Sent when a SCA is required and a SCA method must be selected.
    set_medium: Sent when a SCA is required and a SCA medium must be selected. If a SCA method had to be selected, this relation always appears after set_method.
    authenticate: Sent when a SCA is required and a challenge response must be sent, e.g. a TAN (embedded case).

    Add Bank Access

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/customer/v2/bankzugaenge \
      -H 'Content-Type: application/json'
    
    

    POST /customer/v2/bankzugaenge

    Adds a bank access for the given user and set of credentials. The request returns with HTTP 201 Created as soon as the account's head data such as products and balances could be retrieved.

    Body parameter

    {
      "d48744c0-132c-4ae4-a909-1ff771f61503": {
        "providerId": "00000000-0000-0000-0000-000000000000",
        "credentials": {
          "userid": "mOd2uKYr+2 ... TWOPCAt5zP",
          "pin": "Hhnc+aW/eM ... 7F+XRSHasW"
        },
        "sync": true
      }
    }
    

    Parameters

    Name In Type Required Description
    refresh query boolean false If the bank access already exists, regardless of the background update, all revenues and information are retrieved by the provider, if true
    body body CreateBankAccess true test

    Responses

    Status Meaning Description Schema Possible relations
    201 Created HTTP status 201 (Created) is returned together with the HTTP header Location. Under the URL specified in the header, the added bank accesses can be queried analogously by means of an HTTP GET call. None none
    504 Gateway Time-out The started request could not be answered in the given time None none

    Response Headers

    Status Header Type Format Description
    201 Location string none

    Delete Bank Access

    Code samples

    ## You can also use wget
    curl -X DELETE https://banksapi.io/customer/v2/bankzugaenge/{access-id}
    
    

    DELETE /customer/v2/bankzugaenge/{access-id}

    Removes a specific bank access.

    Parameters

    Name In Type Required Description
    access-id path string true ID of the bank access to delete.

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns without any further response body. None none

    Get Bank Access

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/bankzugaenge/{access-id} \
      -H 'Accept: application/json'
    
    

    GET /customer/v2/bankzugaenge/{access-id}

    Retrieves a specific bank access for this user.

    Parameters

    Name In Type Required Description
    access-id path string true ID of the bank access of which you want to retrieve details.

    Example responses

    200 Response

    {
      "status": "VOLLSTAENDIG",
      "tanMedien": [
        {
          "gueltigVon": "2016-06-03 17:17:41",
          "gueltigBis": "2016-06-03 17:17:41",
          "name": "Mobil",
          "medienklasse": "MOBIL"
        }
      ],
      "sicherheitsverfahren": [
        {
          "kodierung": 2,
          "name": "mTAN",
          "hinweis": "mTAN"
        },
        {
          "kodierung": 1,
          "name": "Mock-TAN",
          "hinweis": "Mock-TAN"
        }
      ],
      "aktivesSicherheitsverfahren": {
        "kodierung": 1,
        "name": "Mock-TAN",
        "hinweis": "Mock-TAN"
      },
      "aktualisierungszeitpunkt": "2016-06-10 17:17:40",
      "timeout": "2016-12-24 13:37:42",
      "messages": [],
      "bankprodukte": [],
      "relations": [],
      "sync": false
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns a bank access object BankAccess self: Querying bank access
    delete_bankzugang: Delete bank access
    504 Gateway Time-out The started request could not be answered in the given time None none

    Get Bank Access Issues

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/bankzugaenge/{access-id}/issues \
      -H 'Accept: application/json'
    
    

    GET /customer/v2/bankzugaenge/{access-id}/issues

    Retrieves last known issues for a specific bank access for this user.

    Parameters

    Name In Type Required Description
    access-id path string true ID of the bank access of which you want to retrieve details.

    Example responses

    200 Response

    {
      "id": "815251d6-c062-4f61-bec0-182bc14a48fb",
      "providerId": "00000000-0000-0000-0000-000000000000",
      "tanMedien": [
        {
          "gueltigVon": "2016-06-03 17:17:41",
          "gueltigBis": "2016-06-03 17:17:41",
          "name": "Mobil",
          "medienklasse": "MOBIL"
        }
      ],
      "sicherheitsverfahren": [
        {
          "kodierung": 2,
          "name": "mTAN",
          "hinweis": "mTAN"
        },
        {
          "kodierung": 1,
          "name": "Mock-TAN",
          "hinweis": "Mock-TAN"
        }
      ],
      "aktivesSicherheitsverfahren": {
        "kodierung": 1,
        "name": "Mock-TAN",
        "hinweis": "Mock-TAN"
      },
      "challenge": {
        "name": "Mock-TAN-Verfahren",
        "content": {
          "instructions": "Enter a TAN that is divisible by 2"
        }
      },
      "aktualisierungszeitpunkt": "2016-06-10 17:17:40",
      "messages": [
        {
          "level": "INFO",
          "code": "BA3010",
          "message": "SCA benötigt",
          "details": "Bitte wählen Sie eine SCA-Methode aus"
        }
      ],
      "relations": [
        {
          "rel": "set_method",
          "href": "https://banksapi.io/v2/customer/consent/1345340218050910215PSDDE-BAFIN-152070CO4960JJ"
        }
      ]
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns a bank access issues object BankAccessIssues self: Querying bank access
    delete_bankzugang: Delete bank access

    Get Transactions

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/bankzugaenge/{access-id}/{product-id}/kontoumsaetze \
      -H 'Accept: application/json'
    
    

    GET /customer/v2/bankzugaenge/{access-id}/{product-id}/kontoumsaetze

    Retrieves all transactions for a specific product of a specific access of this user.

    Parameters

    Name In Type Required Description
    from query IsoDateTime false Only return transactions after this Date/Time, may be used with to to specify a time window
    to query IsoDateTime false Only return transactions after this Date/Time, may be used with from to specify a time window
    tag query boolean false Whether the sales should be categorized (tagged) at runtime. The resulting account sales then each contain Classification objects
    access-id path string true ID of the bank access
    product-id path string true ID of the bank product

    Example responses

    200 Response

    [
      {
        "betrag": -70,
        "verwendungszweck": "EC 68096654 140215204106OC3 Ref. 5CC15048A1824480/89280",
        "buchungsdatum": "2016-11-17 00:00:00",
        "wertstellungsdatum": "2016-11-15 00:00:00",
        "gegenkontoInhaber": "La Sopia GmbH München",
        "gegenkontoIban": "DE00123456789012345679",
        "gegenkontoBic": "XXX12345678",
        "primanotaNummer": "421337",
        "classifications": [
          {
            "category": "recreation_restaurants",
            "parentCategory": "recreation",
            "displayName": "Ausgehen und Essen",
            "confidenceLevel": 0.9
          },
          {
            "category": "recreation",
            "displayName": "Freizeit und Unterhaltung",
            "confidenceLevel": 0.8
          }
        ]
      }
    ]
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns an array of transactions. Inline none

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    anonymous [Transactions] false none none
    » Transactions Transactions false none none
    »» betrag number true none Amount with two decimal places.
    »» verwendungszweck string true none The purpose of sales
    »» buchungsdatum DateTime true none This object represents a timestamp. Format: YYYY-MM-DD hh:mm:ss. Data will be interpreted according to the time zone Europe/Berlin.
    »» wertstellungsdatum DateTime false none This object represents a timestamp. Format: YYYY-MM-DD hh:mm:ss. Data will be interpreted according to the time zone Europe/Berlin.
    »» gegenkontoInhaber string true none Owner of the counter account
    »» gegenkontoIban string false none IBAN of the counter account
    »» gegenkontoBic string false none BIC of the counter account
    »» primanotaNummer string false none Primanota number of sales
    »» classifications [Classification] false none [A Classification object corresponds to a classification for a sales category]
    »»» Classification Classification false none A Classification object corresponds to a classification for a sales category
    »»»» category string true none Unique system name of sales category
    »»»» parentCategory string false none If it is a subcategory, this field includes the system name of the main category
    »»»» displayName string true none User friendly name of sales category
    »»»» confidenceLevel string false none Probability value (0-1) that account sales belong to this category

    Get Portfolio

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/bankzugaenge/{access-id}/{portfolio-id}/depotpositionen \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer 0defaced-1337-d00d-c0de-face8badcafe'
    
    

    GET /customer/v2/bankzugaenge/{access-id}/{portfolio-id}/depotpositionen

    Retrieves all investments in a specific banking product of type brokerage account (portfolio depot) for this user.

    Parameters

    Name In Type Required Description
    Authorization header string true The Authorization header contains the client token to authenticate a user with a server.
    access-id path string true ID of the bank access
    portfolio-id path string true ID of the portfolio

    Example responses

    200 Response

    [
      {
        "name": "Aberdeen Global - Emer. Markets Equity E2",
        "menge": 210.819609,
        "handelseinheit": "STUECK",
        "isin": "LU0498181733",
        "wkn": "A1C5UV",
        "kurs": 15.4117,
        "kursDatum": "2015-05-11 00:00:00",
        "waehrung": "EUR",
        "waehrungskurs": 1,
        "handelsplatz": "KAG",
        "gesamtwert": 3249.09
      }
    ]
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns an array of investments, e.g. stocks, bonds and other positions. Investment none

    Submit TAN

    Code samples

    ## You can also use wget
    curl -X PUT https://banksapi.io/customer/v2/ueberweisung/{provider}/{product-id}/{transfer-token} \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json'
    
    

    PUT /customer/v2/ueberweisung/{provider}/{product-id}/{transfer-token}

    Submits a TAN for a previously created payment.

    Body parameter

    {
      "tan": "4103582"
    }
    

    Parameters

    Name In Type Required Description
    Content-Type header string true The Content-Type header is used to specify the nature of the data in the body of a HTTP request.
    provider path string true ID of the provider
    product-id path string true ID of the banking product the transfer was initialized from
    transfer-token path string true Transfer token as created previously when initializing the transaction
    body body CreateTextTan true Object required to submit a TAN.

    Example responses

    200 Response

    {
      "hinweis": "Bitte geben Sie die SMS-TAN ein",
      "timeout": "2016-12-24 20:00:00",
      "relations": [
        {
          "rel": "submit_text_tan",
          "href": "https://banksapi.io/customer/v2/ueberweisung/DE1235233452324553423442/9b90127c-9b85-11e6-82d8-480fcfb9550f"
        }
      ]
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns the transfer status. If the TAN was wrong, the hint has changed accordingly and there is still a timeout and the relation submit_text_tan. If the TAN was correct then Timeout and the Relations disappear. Interaction submit_text_tan: Submit TAN

    Create Transfer

    Code samples

    ## You can also use wget
    curl -X POST https://banksapi.io/customer/v2/ueberweisung/{provider}/{product-id} \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json'
    
    

    POST /customer/v2/ueberweisung/{provider}/{product-id}

    Creates a payment (i.e. initializes a SEPA transfer).

    Body parameter

    {
      "credentials": {
        "userid": "mXlkGe+ukAEs+2iHjcM8PM7B94SIXgGlt95JOao+cWdWDJkzjlGhFChkNT3NsVy7oskVDq4omgkAhf84FV2udD6ObRuFla7KcTyKeVYD1+N8yegK620B920sSPb+md0Sdia85+DMbnqFTkxsG+FUzsAA3hFSHsGKUgI6awMWbPdX5eDzR7b6qnSI+uOjee4hWp+ht9ecYy5msAk6TKFwzmvfLEy52afpBdjtGNpiRFnPbyRkkPvlihA3Bcv5leBdLD8uy8+AV1l4gC+ASv/qSiR31/5ZwMUr4jrP1kE9vMfvPQK1ZE8g3x/zcvl/cqz02OYATlDQejhacuWmJtU37W1Pvcq3fltTcGZmps1dcIo9BnWA2Vwl9laecJzOejij5LL8+shk+a/973JknvAtejH8McW3zNbQf8gPpXnkINoHhS5njZ5RseQljlMcYRgpqcGwjuxfAPkguifR2st5zC2VJjlRhR/qXolYWzghy06o5gxnDeQKMCo1K1kihxzlUznk/KAcr7AmjgLHRgoftS2GOtR0GJxI49jojQ5lbIeY9CSzVae0clqMqpbeKFyYRT2F/f7ZaNMMCrEzcCRTSjJUMemPDWi0o2iVo+n3WBk8coLXXEkv0xTV2G5Pxz2lFhgJm2oFHteqFRgZktdagz+ft6uyURWRD/MOfGsd8HY=",
        "pin": "XO2jgZX9V5GvB9rg8w6px0r/gypl5fL07ne7fX5/OolxScRo9opQqrmv90Bo2fT2ej9JQ27jWF3ltrZXLrtil2NoKmwwsVB9YuW6NEr3bw/d3jwOlJEyvQawul0tSte+nL18sWXTHPB9vPv1ATQviOmxgJUmu8iBnwND1x46iwwUSZemVng2yBExZvsaCBZS+5aMi1mQyf5b70woxtaAVhkL2nXUddSQMNiqAgyETZBFzu71M0+crBPz2hcZk4s2L90EjZ35DdkW8MmxSPH5dtvccxjmuT6HjBfilSeeNicE+U7vSkmGO4LTJ/RaTNF/F2BQkDG1j8w4gnNgEzl9J1ZplJMA+/kFrQSoWVtotUO0STI0l+x0xmHP1GkYQgYxoEVvlz1PvHYDxqao4NKWQGEqAh7a34NzSBfIccpLeTyNI9DZvJLIPLw/jTHTKui0uz0UcLEYV71yJnZ5LwazZGrESYppsI6FD6Ex9Y+tF4cjkodRvjLSx1bWkyvPj1m2e0U/DaSLs5708eZj1dJTJAmpz+flOStSaY0RIF7RdbVlCfMRljd/AMfvpAyEW63tHGV/KXqryIfysNE+SI+cG8HNHwVDmPe2jAGEkAQpCTnLruEn8+KQgv9V4oWMYhE3OgHFtH1vzccqCbzjWKilAXdeBXVHC9W1Rv5GfhKpZmw="
      },
      "empfaenger": "netzpolitik.org e. V.",
      "verwendungszweck": "Spende netzpolitik.de",
      "iban": "DE62430609671149278400",
      "bic": "GENODEM1GLS",
      "waehrung": "EUR",
      "betrag": 1337.42,
      "ausfuehrungsdatum": "2016-12-24",
      "sicherheitsverfahrenKodierung": "1",
      "tanMediumName": "Mobil",
      "tanMedien": [
        {
          "gueltigVon": "2016-06-03 17:17:41",
          "gueltigBis": "2016-06-03 17:17:41",
          "name": "Mobil",
          "medienklasse": "MOBIL"
        }
      ],
      "sicherheitsverfahren": [
        {
          "kodierung": 2,
          "name": "mTAN",
          "hinweis": "mTAN"
        },
        {
          "kodierung": 1,
          "name": "Mock-TAN",
          "hinweis": "Mock-TAN"
        }
      ],
      "messages": [
        {
          "level": "INFO",
          "code": "BA3010",
          "message": "SCA benötigt",
          "details": "Bitte wählen Sie eine SCA-Methode aus"
        }
      ],
      "relations": [
        {
          "rel": "set_method",
          "href": "https://banksapi.io/v2/customer/consent/1345340218050910215PSDDE-BAFIN-152070CO4960JJ"
        }
      ]
    }
    

    Parameters

    Name In Type Required Description
    Content-Type header string true The Content-Type header is used to specify the nature of the data in the body of a HTTP request.
    provider path string(uuid) true ID of provider
    product-id path string true ID of the banking product the transfer should be initialized from
    body body CreateTransfer true The request body object carries the data for a payment. It is expected when creating a payment.

    Example responses

    200 Response

    {
      "messages": [
        {
          "code": "BA1110",
          "level": "INFO",
          "message": "TAN-Eingabe nötig",
          "details": "Bitte geben Sie die TAN ein"
        }
      ],
      "timeout": "2017-08-31 16:08:55",
      "relations": [
        {
          "rel": "submit_text_tan",
          "href": "https://banksapi.io/customer/v2/ueberweisung/00000000-0000-0000-0000-000000000000/DE00123456789012345679/c612b2f3-f797-4f66-bec4-2064812c8736"
        }
      ],
      "challenge": {
        "name": "chipTAN optisch",
        "content": {
          "HHD": "11048714955205123456789F14302C303107",
          "HHDUC": "1234567891234567891234567890,01"
        }
      }
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns object with the transfer status Interaction submit_text_tan: Submit TAN

    Get Bank Product

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/bankzugaenge/{access-id}/{product-id} \
      -H 'Accept: application/json'
    
    

    GET /customer/v2/bankzugaenge/{access-id}/{product-id}

    Retrieve information for a single bank product.

    Parameters

    Name In Type Required Description
    access-id path string true ID of the bank access
    product-id path string true ID of the banking product

    Example responses

    200 Response

    {
      "kategorie": "GIROKONTO",
      "produktbezeichnung": "Demo-Girokonto",
      "produktId": "DE1235233452324553423442A",
      "inhaber": "Dan Cooper",
      "aktualisierungsdatum": "2016-05-23 13:37:00",
      "saldo": "200000.00",
      "waehrung": "USD",
      "saldoDatum": "2016-05-23 13:37:00",
      "kontonummer": "0123456789",
      "iban": "DE1235233452324553423442",
      "bic": "BICIS133742",
      "blz": "12345678",
      "kreditinstitut": "Demo-Bank",
      "messages": [],
      "relations": []
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns data of the bank product. Product none
    504 Gateway Time-out The started request could not be answered in the given time None none

    Providers API

    Get Providers

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/providers/v2 \
      -H 'Accept: application/json'
    
    

    GET /providers/v2

    Retrieve a list of and information for all providers.

    Example responses

    200 Response

    [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "Demo Provider",
        "group": "demo",
        "blz": "12345678",
        "bic": "DEMO1234",
        "relations": [
          {
            "rel": "self",
            "href": "https://banksapi.io/providers/v2/00000000-0000-0000-0000-000000000000"
          },
          {
            "rel": "logo",
            "href": "https://banksapi.io/providers/v2/demo.svg"
          }
        ],
        "capabilities": [
          "KONTEN",
          "KARTEN",
          "DEPOTS"
        ],
        "channels": [
          [
            "GIROKONTO"
          ],
          [
            "KREDITKARTE",
            "TAGESGELDKONTO"
          ]
        ],
        "authenticationInfo": {
          "loginHint": "Der Demo Provider bietet drei Zugänge demo1/demo1, demo2/demo2 und demo3/demo3",
          "fields": [
            {
              "fieldkey": "userid",
              "label": "Demo-User",
              "secret": false,
              "hint": "demo1, demo2 oder demo3",
              "format": "|5"
            },
            {
              "fieldkey": "pin",
              "label": "Demo-Passwort",
              "secret": true,
              "hint": "demo1, demo2 oder demo3",
              "format": "|5"
            }
          ]
        }
      }
    ]
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns an array of providers. Inline self: Get providers

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    anonymous [Provider] false none [Provider information]
    » Provider Provider false none Provider information
    »» id string true none Unique key for this provider in BANKSapi Banks/Connect
    »» name string true none Name for the provider, not unique
    »» group string false none Grouping term for providers. If several providers have the same group, eg the same logo can be displayed
    »» blz string false none The bank code of the bank was the primary key for banks in Germany before SEPA
    »» bic string false none The BIC (Business Identifier Code) of the bank
    »» relations [Relation] true none Relations indicate which operation the provider resource supports
    »»» Relation Relation false none A relation corresponds to an application or business transaction that is supported by the enclosing data object. Each application or business transaction has its own documentation, which describes the call as well as the return or the possible alternative answer scenarios in detail.
    »»»» rel string true none Machine readable string to differentiate the relations
    »»»» href string true none URL where the relation links to
    »»» capabilities [string] true none Shows which technical objects with the Provider on the Banks / Connect Customer API are available
    »»» channels [ProductCategories] false none Shows which product categories are queried by BANKSapi to the bank through which channel. Items in the same array are queried through the same channel, e.g. FinTS. If you are requesting products that are listed in the same array (going through the same channel), you might save on a number of SCA processes, because there will be at least one SCA per channel at least every 90 days.
    »»»» ProductCategories [ProductCategory] false none A list of product categories
    »»»»» ProductCategory ProductCategory false none Categories:
  • GIROKONTO - Checking account: Account for payment transactions, as well as for the settlement / processing of eg deposit-related bookings, fees, interest, etc.
  • SPARKONTO - Savings account: Interest-bearing account with an unlimited term and fixed period of notice, as a rule an immediate withdrawal is limited to a maximum value
  • FESTGELDKONTO - Fixed deposit account: Interest-bearing account with a contractually agreed term
  • KREDITKONTO - Credit account: Account for managing the loan balance
  • TAGESGELDKONTO - Overnight money account: Interest-based account for an investment with daily availability
  • BAUSPARVERTRAG - Building loan account: Savings and possibly loan account for a home savings contract
  • SONSTIGESKONTO - Account that can not be assigned by the provider or our product heuristic
  • KREDITKARTE - Credit card: Payment card with credit line, billing takes place via an agreed current account / clearing account
  • SONSTIGEKARTE - Other card: Payment card that can not be assigned by the provider or our product heuristic
  • DEPOT - Brokerage account
  • SONSTIGESPRODUKT - Bank product that can not be assigned by the provider or our product heuristic
  • »»»» authenticationInfo AuthenticationInfo true none The AuthenticationInfo object provides detailed information about the sign-in process to the provider. With the included data, it is possible to optimize the user experience of the own application in the provider system, which on the one hand reduce the nerve factor for the user but can also minimize their own support expenses due to login problems.
    »»»»» loginHint string false none Note text for the registration process, which applies to the complete registration process
    »»»»» fields [Field] true none Array with login parameters
    »»»»»» Field Field false none none
    »»»»»»» fieldkey string true none Name of the parameter in the Credentials object
    »»»»»»» label string true none Name of the field for the ad
    »»»»»»» secret boolean true none Specifies whether the field contains a secret, for example, should be hidden or only optionally stored
    »»»»»»» hint string false none An explanation text for display next to the field
    »»»»»»» format string true none A format description for the input field
    Enumerated Values
    Property Value
    ProductCategory GIROKONTO
    ProductCategory SPARKONTO
    ProductCategory FESTGELDKONTO
    ProductCategory KREDITKONTO
    ProductCategory TAGESGELDKONTO
    ProductCategory BAUSPARVERTRAG
    ProductCategory SONSTIGESKONTO
    ProductCategory KREDITKARTE
    ProductCategory SONSTIGEKARTE
    ProductCategory DEPOT
    ProductCategory SONSTIGESPRODUKT

    Get Provider

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/providers/v2/{provider} \
      -H 'Accept: application/json'
    
    

    GET /providers/v2/{provider}

    Retrieve information for a specific provider.

    Parameters

    Name In Type Required Description
    provider path string true ID of the provider

    Example responses

    200 Response

    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "Demo Provider",
      "group": "demo",
      "blz": "12345678",
      "bic": "DEMO1234",
      "relations": [
        {
          "rel": "self",
          "href": "https://banksapi.io/providers/v2/00000000-0000-0000-0000-000000000000"
        },
        {
          "rel": "logo",
          "href": "https://banksapi.io/providers/v2/demo.svg"
        }
      ],
      "capabilities": [
        "KONTEN",
        "KARTEN",
        "DEPOTS"
      ],
      "channels": [
        [
          "GIROKONTO"
        ],
        [
          "KREDITKARTE",
          "TAGESGELDKONTO"
        ]
      ],
      "authenticationInfo": {
        "loginHint": "Der Demo Provider bietet drei Zugänge demo1/demo1, demo2/demo2 und demo3/demo3",
        "fields": [
          {
            "fieldkey": "userid",
            "label": "Demo-User",
            "secret": false,
            "hint": "demo1, demo2 oder demo3",
            "format": "|5"
          },
          {
            "fieldkey": "pin",
            "label": "Demo-Passwort",
            "secret": true,
            "hint": "demo1, demo2 oder demo3",
            "format": "|5"
          }
        ]
      }
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Returns a single provider object. Provider logo: Provider logo in SVG format
    self: Get provider
    404 Not Found If the URL does not point to a provider, you will get the HTTP status 404 (Not found). None none

    Schemas

    ConsentAccess

    {
      "balances": [
        {
          "iban": "DE2310010010123456789"
        }
      ],
      "transactions": [
        {
          "iban": "DE2310010010123456789"
        }
      ],
      "productCategories": [
        "GIROKONTO",
        "TAGESGELDKONTO"
      ]
    }
    
    

    ConsentAccess

    Properties

    Name Type Required Restrictions Description
    accounts ConsentAccount false none Is asking for detailed account information.
    balances ConsentAccount false none Is asking for balances of the addressed accounts.
    transactions ConsentAccount false none Is asking for transactions of the addressed accounts.
    availableAccounts string false none Optional if supported by API provider. Only the value "allAccounts" is admitted.
    allPsd2 string false none Optional if supported by API provider. Only the value "allAccounts" is admitted.
    productCategories [ProductCategory] false none May be sent with a list containing product categories. This attribute can be used to indicate to the user for which product categories he needs to fulfill SCA.

    ConsentAccount

    {
      "iban": "DE2310010010123456789"
    }
    
    

    ConsentAccount

    Properties

    Name Type Required Restrictions Description
    iban string true none IBAN of an account.
    bban string false none BBAN of an account.
    pan string false none Account number of an account (not PAN in credit card context, we never touch credit card PANs).
    currency string false none ISO 4217 Alpha 3 currency code

    AuthenticationInfo

    {
      "loginHint": "Die User-ID setzt sich aus Ihrer 8-stelligen Hauptkontonummer und der 2-stelligen Unterkontonummer zusammen.",
      "fields": [
        {
          "fieldkey": "userid",
          "label": "KOMnet-Key",
          "secret": false,
          "hint": "Der DEMOnet-Key ist ist auf Ihrer DEMO-EC-Karte aufgedruckt",
          "format": "|5"
        },
        {
          "fieldkey": "pin",
          "label": "Demo-Passwort",
          "secret": true,
          "hint": "demo1, demo2 oder demo3",
          "format": "|5"
        }
      ]
    }
    
    

    AuthenticationInfo

    Properties

    Name Type Required Restrictions Description
    loginHint string false none Note text for the registration process, which applies to the complete registration process
    fields [Field] true none Array with login parameters

    Job

    {
      "jobType": "SAMMLER",
      "engine": "SCRAPER",
      "prio": 1
    }
    
    

    Job

    Properties

    Name Type Required Restrictions Description
    jobType string true none none
    engine string true none none
    prio integer(int32) false none none

    Relation

    {
      "rel": "self",
      "href": "https://banksapi.io:443/providers/v2/00000000-0000-0000-0000-000000000000"
    }
    
    

    Relation

    Properties

    Name Type Required Restrictions Description
    rel string true none Machine readable string to differentiate the relations
    href string true none URL where the relation links to

    Credentials

    {
      "userid": "mOd2uKYr+2 ... TWOPCAt5zP",
      "pin": "Hhnc+aW/eM ... 7F+XRSHasW"
    }
    
    

    Credentials

    Properties

    Name Type Required Restrictions Description
    userid string true none Encrypted and Base64-encoded username of the user at the bank, e.g. used in his online banking
    pin string true none Encrypted and Base64-encoded pin / password of the user at the bank, e.g. used in his online banking

    Tag

    {
      "tagScope": "transaction",
      "tagId": "36d394ba-edef-4075-97e7-b19d1fae3702",
      "tagType": "CATEGORY",
      "tagVersion": "2.5",
      "systemName": "HOUSING_RENT",
      "displayName": "Miete/Wohngeld",
      "parent": "HOUSING"
    }
    
    

    Tag

    Properties

    Name Type Required Restrictions Description
    tagScope string true none Object of tagging. User or Transaction
    tagId string(uuid) true none Random unique id according to RFC4122 for identification
    tagType TagType true none Type according to usage purpose
    tagVersion integer(int32) true none BANKSapi version of the tag hierarchy.
    systemName SystemName true none Machine-readable name of the tag, for a list check e.g. the transaction categories
    displayName string true none User-friendly and human readable name of the category in German
    parent SystemName true none Parent Tag systemName, if one exists

    Transactions

    {
      "betrag": -70,
      "verwendungszweck": "EC 68096654 140215204106OC3 Ref. 5CC15048A1824480/89280",
      "buchungsdatum": "2016-11-17 00:00:00",
      "wertstellungsdatum": "2016-11-15 00:00:00",
      "gegenkontoInhaber": "La Sopia GmbH München",
      "gegenkontoIban": "DE00123456789012345679",
      "gegenkontoBic": "XXX12345678",
      "primanotaNummer": "421337",
      "classifications": [
        {
          "category": "recreation_restaurants",
          "parentCategory": "recreation",
          "displayName": "Ausgehen und Essen",
          "confidenceLevel": 0.9
        },
        {
          "category": "recreation",
          "displayName": "Freizeit und Unterhaltung",
          "confidenceLevel": 0.8
        }
      ]
    }
    
    

    Transactions

    Properties

    Name Type Required Restrictions Description
    betrag number true none Amount with two decimal places.
    verwendungszweck string true none The purpose of sales
    buchungsdatum DateTime true none Date of value date
    wertstellungsdatum DateTime false none Date of booking
    gegenkontoInhaber string true none Owner of the counter account
    gegenkontoIban string false none IBAN of the counter account
    gegenkontoBic string false none BIC of the counter account
    primanotaNummer string false none Primanota number of sales
    classifications [Classification] false none [A Classification object corresponds to a classification for a sales category]

    CreateUser

    {
      "username": "demouser",
      "password": "secret",
      "firstname": "demo",
      "lastname": "user"
    }
    
    

    CreateUser

    Properties

    Name Type Required Restrictions Description
    username string true none The unique username
    password string true none The password
    firstname string false none The first name
    lastname string false none Last name

    CreateTextTan

    {
      "tan": "4103582"
    }
    
    

    CreateTextTan

    Properties

    Name Type Required Restrictions Description
    tan string true none The TAN to confirm the transfers

    Consent

    {
      "access": {
        "balances": [
          {
            "iban": "DE2310010010123456789"
          }
        ],
        "transactions": [
          {
            "iban": "DE2310010010123456789"
          }
        ]
      },
      "recurringIndicator": "true",
      "validUntil": "2017-11-01",
      "frequencyPerDay": "4",
      "consentStatus": "valid"
    }
    
    

    Consent

    Properties

    Name Type Required Restrictions Description
    access ConsentAccess true none none
    recurringIndicator boolean false none Support for recurring requests with the same consent
    validUntil string false none Consent valid until; ISO 8601 date
    frequencyPerDay integer(int32) false none Number of requests per day without PSU involvement
    combinedServiceIndicator boolean false none Support for combined PIS/AIS processes
    lastActionDate string(date) false none Date of last action that had animpact on the consent status
    consentStatus ConsentStatus false none This is the overall life cycle status of the consent.

    Valid values are:
  • RECEIVED: The consent data have been received and are technically correct. The data is not authorised yet.
  • REJECTED: The consent data have been rejected e.g. since no successful authorisation has taken place.
  • VALID: The consent is accepted and valid for GET account data calls and others as specified in the consent object.
  • REVOKED_BY_USER: The consent has been revoked by the PSU towards the ASPSP.
  • EXPIRED: The consent expired.
  • Field

    {
      "fieldkey": "pin",
      "label": "Demo-Passwort",
      "secret": true,
      "hint": "demo1, demo2 oder demo3",
      "format": "|5"
    }
    
    

    Field

    Properties

    Name Type Required Restrictions Description
    fieldkey string true none Name of the parameter in the Credentials object
    label string true none Name of the field for the ad
    secret boolean true none Specifies whether the field contains a secret, for example, should be hidden or only optionally stored
    hint string false none An explanation text for display next to the field
    format string true none A format description for the input field

    CreateTransfer

    {
      "credentials": {
        "userid": "mXlkGe+ukAEs+2iHjcM8PM7B94SIXgGlt95JOao+cWdWDJkzjlGhFChkNT3NsVy7oskVDq4omgkAhf84FV2udD6ObRuFla7KcTyKeVYD1+N8yegK620B920sSPb+md0Sdia85+DMbnqFTkxsG+FUzsAA3hFSHsGKUgI6awMWbPdX5eDzR7b6qnSI+uOjee4hWp+ht9ecYy5msAk6TKFwzmvfLEy52afpBdjtGNpiRFnPbyRkkPvlihA3Bcv5leBdLD8uy8+AV1l4gC+ASv/qSiR31/5ZwMUr4jrP1kE9vMfvPQK1ZE8g3x/zcvl/cqz02OYATlDQejhacuWmJtU37W1Pvcq3fltTcGZmps1dcIo9BnWA2Vwl9laecJzOejij5LL8+shk+a/973JknvAtejH8McW3zNbQf8gPpXnkINoHhS5njZ5RseQljlMcYRgpqcGwjuxfAPkguifR2st5zC2VJjlRhR/qXolYWzghy06o5gxnDeQKMCo1K1kihxzlUznk/KAcr7AmjgLHRgoftS2GOtR0GJxI49jojQ5lbIeY9CSzVae0clqMqpbeKFyYRT2F/f7ZaNMMCrEzcCRTSjJUMemPDWi0o2iVo+n3WBk8coLXXEkv0xTV2G5Pxz2lFhgJm2oFHteqFRgZktdagz+ft6uyURWRD/MOfGsd8HY=",
        "pin": "XO2jgZX9V5GvB9rg8w6px0r/gypl5fL07ne7fX5/OolxScRo9opQqrmv90Bo2fT2ej9JQ27jWF3ltrZXLrtil2NoKmwwsVB9YuW6NEr3bw/d3jwOlJEyvQawul0tSte+nL18sWXTHPB9vPv1ATQviOmxgJUmu8iBnwND1x46iwwUSZemVng2yBExZvsaCBZS+5aMi1mQyf5b70woxtaAVhkL2nXUddSQMNiqAgyETZBFzu71M0+crBPz2hcZk4s2L90EjZ35DdkW8MmxSPH5dtvccxjmuT6HjBfilSeeNicE+U7vSkmGO4LTJ/RaTNF/F2BQkDG1j8w4gnNgEzl9J1ZplJMA+/kFrQSoWVtotUO0STI0l+x0xmHP1GkYQgYxoEVvlz1PvHYDxqao4NKWQGEqAh7a34NzSBfIccpLeTyNI9DZvJLIPLw/jTHTKui0uz0UcLEYV71yJnZ5LwazZGrESYppsI6FD6Ex9Y+tF4cjkodRvjLSx1bWkyvPj1m2e0U/DaSLs5708eZj1dJTJAmpz+flOStSaY0RIF7RdbVlCfMRljd/AMfvpAyEW63tHGV/KXqryIfysNE+SI+cG8HNHwVDmPe2jAGEkAQpCTnLruEn8+KQgv9V4oWMYhE3OgHFtH1vzccqCbzjWKilAXdeBXVHC9W1Rv5GfhKpZmw="
      },
      "empfaenger": "netzpolitik.org e. V.",
      "verwendungszweck": "Spende netzpolitik.de",
      "iban": "DE62430609671149278400",
      "bic": "GENODEM1GLS",
      "waehrung": "EUR",
      "betrag": 1337.42,
      "ausfuehrungsdatum": "2016-12-24",
      "sicherheitsverfahrenKodierung": "1",
      "tanMediumName": "Mobil",
      "tanMedien": [
        {
          "gueltigVon": "2016-06-03 17:17:41",
          "gueltigBis": "2016-06-03 17:17:41",
          "name": "Mobil",
          "medienklasse": "MOBIL"
        }
      ],
      "sicherheitsverfahren": [
        {
          "kodierung": 2,
          "name": "mTAN",
          "hinweis": "mTAN"
        },
        {
          "kodierung": 1,
          "name": "Mock-TAN",
          "hinweis": "Mock-TAN"
        }
      ],
      "messages": [
        {
          "level": "INFO",
          "code": "BA3010",
          "message": "SCA benötigt",
          "details": "Bitte wählen Sie eine SCA-Methode aus"
        }
      ],
      "relations": [
        {
          "rel": "set_method",
          "href": "https://banksapi.io/v2/customer/consent/1345340218050910215PSDDE-BAFIN-152070CO4960JJ"
        }
      ]
    }
    
    

    Properties

    allOf

    Name Type Required Restrictions Description
    anonymous ScaInteraction false none BankAccess and Transfer inherit from this object. It indicates that in some cases, SCA may be needed to interact with the inheriting object.

    and

    Name Type Required Restrictions Description
    anonymous object false none Request data to start a transfer
    » credentials Credentials true none The Credentials object is a map of encrypted and Base64-encoded access data, corresponding to the provider's authentication fields. The Base64 encoding must not use line wrapping. The encryption method used is described in the chapter Encryption.
    » empfaenger string true none Receiver of the transfer
    » verwendungszweck string true none Purpose of the transfer.
    » iban string true none IBAN of the recipient account
    » bic string true none BIC of the recipient account
    » waehrung string true none Currency of the transfer ( Alphabetic Code ISO 4217 )
    » betrag string true none Transfer amount
    » sicherheitsverfahrenKodierung integer(int32) true none Coding of the security procedure to use , see Bank product
    » ausfuehrungsdatum DateTime false none Date on which the transfer should be made
    » tanMediumName string false none The TAN medium to be used

    SecurityProcedures

    {
      "kodierung": 980,
      "name": "mTAN",
      "hinweis": "mTAN"
    }
    
    

    SecurityProcedures

    Properties

    Name Type Required Restrictions Description
    kodierung integer(int32) true none Code of the SCA method
    name string true none Human-readable name of the SCA method
    hinweis string true none Additional helpful hint that must be displayed to the user

    ScaAuthenticationData

    {
      "scaAuthenticationData": "123456"
    }
    
    

    ScaAuthenticationData

    Properties

    Name Type Required Restrictions Description
    scaAuthenticationData string false none none

    Backends

    {
      "scraperName": "mock",
      "defaultProcess": "SCRAPER",
      "accountsAccess": "SCRAPER",
      "loginAccess": "SCRAPER",
      "saldoAccess": "SCRAPER",
      "turnoverAccess": "SCRAPER",
      "transactionAccess": "SCRAPER",
      "bausparListAccess": "SCRAPER",
      "bausparDetailAccess": "SCRAPER",
      "bausparTurnoverAccess": "SCRAPER",
      "creditcardsListAccess": "SCRAPER",
      "creditcardsDetailAccess": "SCRAPER",
      "creditcardsTurnoverAccess": "SCRAPER",
      "depotsListAccess": "SCRAPER",
      "depotsDetailAccess": "SCRAPER",
      "depotsSecuritiesAccess": "SCRAPER",
      "tanmethodAccess": "SCRAPER",
      "maxSyncsPerDayAndUser": 4
    }
    
    

    Backends

    Properties

    Name Type Required Restrictions Description
    scraperName string true none none
    defaultProcess string true none none
    accountsAccess string true none none
    loginAccess string true none none
    saldoAccess string true none none
    turnoverAccess string true none none
    transactionAccess string true none none
    bausparListAccess string true none none
    bausparDetailAccess string true none none
    bausparTurnoverAccess string true none none
    creditcardsListAccess string true none none
    creditcardsDetailAccess string true none none
    creditcardsTurnoverAccess string true none none
    depotsListAccess string true none none
    depotsDetailAccess string true none none
    depotsSecuritiesAccess string true none none
    tanmethodAccess string true none none
    maxSyncsPerDayAndUser integer(int32) true none none

    Provider

    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "Demo Provider",
      "group": "demo",
      "blz": "12345678",
      "bic": "DEMO1234",
      "relations": [
        {
          "rel": "self",
          "href": "https://banksapi.io/providers/v2/00000000-0000-0000-0000-000000000000"
        },
        {
          "rel": "logo",
          "href": "https://banksapi.io/providers/v2/demo.svg"
        }
      ],
      "capabilities": [
        "KONTEN",
        "KARTEN",
        "DEPOTS"
      ],
      "channels": [
        [
          "GIROKONTO"
        ],
        [
          "KREDITKARTE",
          "TAGESGELDKONTO"
        ]
      ],
      "authenticationInfo": {
        "loginHint": "Der Demo Provider bietet drei Zugänge demo1/demo1, demo2/demo2 und demo3/demo3",
        "fields": [
          {
            "fieldkey": "userid",
            "label": "Demo-User",
            "secret": false,
            "hint": "demo1, demo2 oder demo3",
            "format": "|5"
          },
          {
            "fieldkey": "pin",
            "label": "Demo-Passwort",
            "secret": true,
            "hint": "demo1, demo2 oder demo3",
            "format": "|5"
          }
        ]
      }
    }
    
    

    Provider

    Properties

    Name Type Required Restrictions Description
    id string true none Unique key for this provider in BANKSapi Banks/Connect
    name string true none Name for the provider, not unique
    group string false none Grouping term for providers. If several providers have the same group, eg the same logo can be displayed
    blz string false none The bank code of the bank was the primary key for banks in Germany before SEPA
    bic string false none The BIC (Business Identifier Code) of the bank
    relations [Relation] true none Relations indicate which operation the provider resource supports
    capabilities [string] true none Shows which technical objects with the Provider on the Banks / Connect Customer API are available
    channels [ProductCategories] false none Shows which product categories are queried by BANKSapi to the bank through which channel. Items in the same array are queried through the same channel, e.g. FinTS. If you are requesting products that are listed in the same array (going through the same channel), you might save on a number of SCA processes, because there will be at least one SCA per channel at least every 90 days.
    authenticationInfo AuthenticationInfo true none The AuthenticationInfo object provides detailed information about the sign-in process to the provider. With the included data, it is possible to optimize the user experience of the own application in the provider system, which on the one hand reduce the nerve factor for the user but can also minimize their own support expenses due to login problems.

    CreateScaMethod

    {
      "chosenScaMethodId": "942"
    }
    
    

    CreateScaMethod

    Properties

    Name Type Required Restrictions Description
    chosenScaMethodId string false none Code of the SCA method
    chosenScaMedia string false none Name of the SCA medium

    ChallengeContent

    {
      "instructions": "Nutzen sie Ihren TAN-Generator und geben sie anschließend Ihre TAN ein.",
      "HHD": "11048714955205123456789F14302C303107",
      "HHDUC": "1234567891234567891234567890,01"
    }
    
    

    ChallengeContent

    Properties

    Name Type Required Restrictions Description
    instructions string false none Textual description on how to perform authentication
    HHD string false none Textual representation of flicker code when using optical ChipTAN
    HHDUC string false none Textual representation of code when using FlickerTAN
    photo string(byte) false none Base64-encoded png of the mosaic photo to be displayed to the user when using PhotoTAN

    Challenge

    {
      "challenge": {
        "name": "chipTAN optisch",
        "content": {
          "instructions": "Nutzen sie Ihren TAN-Generator und geben sie anschließend Ihre TAN ein.",
          "HHD": "11048714955205123456789F14302C303107",
          "HHDUC": "1234567891234567891234567890,01"
        }
      }
    }
    
    

    Challenge

    Properties

    Name Type Required Restrictions Description
    name string true none Name of the TAN procedure
    content ChallengeContent true none Challenge data needed to perform the authentication with the chosen authentication method
    decoupled boolean false none Indicates whether the TAN-method is decoupled, thus not expecting scaAuthenticationData for Submit SCA Authentication Data, but just an empty object to confirm the user indicated that he meanwhile confirmed the activity, e.g. through the bank app, independently.

    Message

    [
      {
        "level": "INFO",
        "code": "BA3010",
        "message": "SCA benötigt",
        "details": "Bitte wählen Sie eine SCA-Methode aus"
      }
    ]
    
    

    Message

    Properties

    Name Type Required Restrictions Description
    level MessageLevel true none Level of the message, INFO or ERROR
    code MessageCode true none Code of the message

    Message Codes:
  • BA999 - Internal error
  • BA1000 - Maintenance work provider
  • BA1001 - Provider no longer active
  • BA1010 - Access blocked
  • BA1011 - Access data incorrect
  • BA1012 - Access data incomplete
  • BA1050 - The bank account does not answer
  • BA1051 - Bank access unavailable
  • BA1052 - Bank access not fully available
  • BA1060 - Product could not be updated
  • BA1061 - Product could not be completely updated
  • BA1062 - Sales could not be updated
  • BA1063 - Depot positions could not be updated
  • BA1064 - Message bank
  • BA1100 - Transfer data invalid
  • BA1101 - Invalid TAN procedure
  • BA1103 - TAN invalid
  • BA1104 - Bank transfer not possible
  • BA1110 - TAN input required
  • BA1111 - The transfer has been completed successfully
  • BA2001 - SEPA server not accessible
  • BA2002 - There are notifications from your bank
  • BA3000 - SCA required
  • BA3010 - Select SCA method
  • BA3020 - Select SCA medium
  • BA3030 - SCA Challenge
  • BA3040 - SCA failed
  • BA3060 - No supported SCA method found
  • message string true none Error text for display by the end customer according to errors and messages
    details string false none Further information on the display at the end customer, which can change from message to message.

    ListOfBankAccesses

    {
      "85f78300-d993-4b7e-a8d0-8d39a4ba9d2a": {},
      "4000fda7-18af-463f-b694-bbafe5d23a48": {
        "status": "VOLLSTAENDIG",
        "tanMedien": [
          {
            "gueltigVon": "2016-06-03 17:17:41",
            "gueltigBis": "2016-06-03 17:17:41",
            "name": "Mobil",
            "medienklasse": "MOBIL"
          }
        ],
        "sicherheitsverfahren": [
          {
            "kodierung": 2,
            "name": "mTAN",
            "hinweis": "mTAN"
          },
          {
            "kodierung": 1,
            "name": "Mock-TAN",
            "hinweis": "Mock-TAN"
          }
        ],
        "aktivesSicherheitsverfahren": {
          "kodierung": 1,
          "name": "Mock-TAN",
          "hinweis": "Mock-TAN"
        },
        "aktualisierungszeitpunkt": "2016-06-10 17:17:40",
        "timeout": "2016-12-24 13:37:42",
        "messages": [],
        "bankprodukte": [],
        "relations": [],
        "sync": false
      }
    }
    
    

    ListOfBankAccesses

    Properties

    Name Type Required Restrictions Description
    UUID BankAccess true none none

    CreateBankAccess

    {
      "d48744c0-132c-4ae4-a909-1ff771f61503": {
        "providerId": "00000000-0000-0000-0000-000000000000",
        "credentials": {
          "userid": "mOd2uKYr+2 ... TWOPCAt5zP",
          "pin": "Hhnc+aW/eM ... 7F+XRSHasW"
        },
        "sync": true
      }
    }
    
    

    CreateBankAccess

    Properties

    Name Type Required Restrictions Description
    {access-id} CreateBankAccessData true none none

    MessageCode

    "BA999"
    
    

    MessageCode

    Properties

    Name Type Required Restrictions Description
    MessageCode string false none Code of the message

    Message Codes:
  • BA999 - Internal error
  • BA1000 - Maintenance work provider
  • BA1001 - Provider no longer active
  • BA1010 - Access blocked
  • BA1011 - Access data incorrect
  • BA1012 - Access data incomplete
  • BA1050 - The bank account does not answer
  • BA1051 - Bank access unavailable
  • BA1052 - Bank access not fully available
  • BA1060 - Product could not be updated
  • BA1061 - Product could not be completely updated
  • BA1062 - Sales could not be updated
  • BA1063 - Depot positions could not be updated
  • BA1064 - Message bank
  • BA1100 - Transfer data invalid
  • BA1101 - Invalid TAN procedure
  • BA1103 - TAN invalid
  • BA1104 - Bank transfer not possible
  • BA1110 - TAN input required
  • BA1111 - The transfer has been completed successfully
  • BA2001 - SEPA server not accessible
  • BA2002 - There are notifications from your bank
  • BA3000 - SCA required
  • BA3010 - Select SCA method
  • BA3020 - Select SCA medium
  • BA3030 - SCA Challenge
  • BA3040 - SCA failed
  • BA3060 - No supported SCA method found
  • Enumerated Values
    Property Value
    MessageCode BA999
    MessageCode BA1000
    MessageCode BA1001
    MessageCode BA1010
    MessageCode BA1011
    MessageCode BA1012
    MessageCode BA1050
    MessageCode BA1051
    MessageCode BA1052
    MessageCode BA1060
    MessageCode BA1061
    MessageCode BA1062
    MessageCode BA1063
    MessageCode BA1064
    MessageCode BA1100
    MessageCode BA1101
    MessageCode BA1103
    MessageCode BA1104
    MessageCode BA1110
    MessageCode BA1111
    MessageCode BA2001
    MessageCode BA2002
    MessageCode BA3000
    MessageCode BA3010
    MessageCode BA3020
    MessageCode BA3030
    MessageCode BA3040
    MessageCode BA3060

    Product

    {
      "kategorie": "GIROKONTO",
      "produktbezeichnung": "Demo-Girokonto",
      "produktId": "DE1235233452324553423442A",
      "inhaber": "Dan Cooper",
      "aktualisierungsdatum": "2016-05-23 13:37:00",
      "saldo": "200000.00",
      "waehrung": "USD",
      "saldoDatum": "2016-05-23 13:37:00",
      "kontonummer": "0123456789",
      "iban": "DE1235233452324553423442",
      "bic": "BICIS133742",
      "blz": "12345678",
      "kreditinstitut": "Demo-Bank",
      "messages": [],
      "relations": []
    }
    
    

    Product

    Properties

    Name Type Required Restrictions Description
    id string true none In access unique identifier for the bank product. Is assigned by the system.
    bezeichnung string true none Name of bank product according to bank / service provider
    productCategories [ProductCategory] false none May be sent with a list of contain product categories. This attribute can be used to reduce the number of necessary SCAs by concentrating on product categories we fetch through the same channel.
    status BankProductStatus false none Retrieval status for product data
    saldo integer(int32) true none Balance / value of bank product with two decimal places
    aktualisierungszeitpunkt string(date) true none Time of the last product update at the bank / service provider
    saldoDatum string(date) true none Date of expiry as reported by the bank / service provider
    waehrung string true none Currency in which the bank product is valued / managed
    kontonummer string true none The account or credit card number. The credit card number may not be issued completely, but with a star eg "3223 ****** 4554"
    iban string true none The IBAN
    blz string true none The bank code
    bic string true none The BIC
    kreditinstitut string true none Name of institute of credit
    inhaber string true none Name of the product owner
    messages [Message] true none Messages transport both errors and analysis events.
    relations [Relation] true none Functions available to the customer
    verfuegungsrahmen integer(int32) true none Contains the available balance (usually overdraft limit + balance)
    verfuegterBetrag integer(int32) true none Contains the available balance (usually overdraft limit + balance)

    ProductCategory

    "GIROKONTO"
    
    

    ProductCategory

    Properties

    Name Type Required Restrictions Description
    ProductCategory string false none Categories:
  • GIROKONTO - Checking account: Account for payment transactions, as well as for the settlement / processing of eg deposit-related bookings, fees, interest, etc.
  • SPARKONTO - Savings account: Interest-bearing account with an unlimited term and fixed period of notice, as a rule an immediate withdrawal is limited to a maximum value
  • FESTGELDKONTO - Fixed deposit account: Interest-bearing account with a contractually agreed term
  • KREDITKONTO - Credit account: Account for managing the loan balance
  • TAGESGELDKONTO - Overnight money account: Interest-based account for an investment with daily availability
  • BAUSPARVERTRAG - Building loan account: Savings and possibly loan account for a home savings contract
  • SONSTIGESKONTO - Account that can not be assigned by the provider or our product heuristic
  • KREDITKARTE - Credit card: Payment card with credit line, billing takes place via an agreed current account / clearing account
  • SONSTIGEKARTE - Other card: Payment card that can not be assigned by the provider or our product heuristic
  • DEPOT - Brokerage account
  • SONSTIGESPRODUKT - Bank product that can not be assigned by the provider or our product heuristic
  • Enumerated Values
    Property Value
    ProductCategory GIROKONTO
    ProductCategory SPARKONTO
    ProductCategory FESTGELDKONTO
    ProductCategory KREDITKONTO
    ProductCategory TAGESGELDKONTO
    ProductCategory BAUSPARVERTRAG
    ProductCategory SONSTIGESKONTO
    ProductCategory KREDITKARTE
    ProductCategory SONSTIGEKARTE
    ProductCategory DEPOT
    ProductCategory SONSTIGESPRODUKT

    ProductCategories

    [
      "GIROKONTO",
      "TAGESGELDKONTO"
    ]
    
    

    ProductCategories

    Properties

    Name Type Required Restrictions Description
    ProductCategories [ProductCategory] false none A list of product categories

    TagType

    "CATEGORY"
    
    

    TagType

    Properties

    Name Type Required Restrictions Description
    TagType string false none Type according to usage purpose
    Enumerated Values
    Property Value
    TagType null

    ScaInteraction

    {
      "tanMedien": [
        {
          "gueltigVon": "2016-06-03 17:17:41",
          "gueltigBis": "2016-06-03 17:17:41",
          "name": "Mobil",
          "medienklasse": "MOBIL"
        }
      ],
      "sicherheitsverfahren": [
        {
          "kodierung": 2,
          "name": "mTAN",
          "hinweis": "mTAN"
        },
        {
          "kodierung": 1,
          "name": "Mock-TAN",
          "hinweis": "Mock-TAN"
        }
      ],
      "messages": [
        {
          "level": "INFO",
          "code": "BA3010",
          "message": "SCA benötigt",
          "details": "Bitte wählen Sie eine SCA-Methode aus"
        }
      ],
      "relations": [
        {
          "rel": "set_method",
          "href": "https://banksapi.io/v2/customer/consent/1345340218050910215PSDDE-BAFIN-152070CO4960JJ"
        }
      ]
    }
    
    

    ScaInteraction

    Properties

    Name Type Required Restrictions Description
    messages [Message] true none Messages transport both errors and analysis events.
    sicherheitsverfahren [SecurityProcedures] false none Listing of security procedures available in the gateway
    relations [Relation] true none The relations available for bank access
    tanMedien [TANMedium] false none List of available TAN media in the access

    BankAccess

    {
      "status": "VOLLSTAENDIG",
      "aktivesSicherheitsverfahren": {
        "kodierung": 1,
        "name": "Mock-TAN",
        "hinweis": "Mock-TAN"
      },
      "aktualisierungszeitpunkt": "2016-06-10 17:17:40",
      "timeout": "2016-12-24 13:37:42",
      "bankprodukte": [],
      "sync": false,
      "tanMedien": [
        {
          "gueltigVon": "2016-06-03 17:17:41",
          "gueltigBis": "2016-06-03 17:17:41",
          "name": "Mobil",
          "medienklasse": "MOBIL"
        }
      ],
      "sicherheitsverfahren": [
        {
          "kodierung": 2,
          "name": "mTAN",
          "hinweis": "mTAN"
        },
        {
          "kodierung": 1,
          "name": "Mock-TAN",
          "hinweis": "Mock-TAN"
        }
      ],
      "messages": [
        {
          "level": "INFO",
          "code": "BA3010",
          "message": "SCA benötigt",
          "details": "Bitte wählen Sie eine SCA-Methode aus"
        }
      ],
      "relations": [
        {
          "rel": "set_method",
          "href": "https://banksapi.io/v2/customer/consent/1345340218050910215PSDDE-BAFIN-152070CO4960JJ"
        }
      ]
    }
    
    

    Properties

    allOf

    Name Type Required Restrictions Description
    anonymous ScaInteraction false none BankAccess and Transfer inherit from this object. It indicates that in some cases, SCA may be needed to interact with the inheriting object.

    and

    Name Type Required Restrictions Description
    anonymous object false none Im Bankzugang-Objekt werden die Daten zu einem Bankzugang (i.d.R. Online-Banking-Zugang des eindeutigen Benutzers) geliefert.
    » status BankAccessStatus false none Retrieval status of the bank account

    Status list :
  • GESTARTET - Started: The data retrieval was started
  • INTERAKTION - Interaction: User intervention required, e.g. SCA required, see messages and relations
  • KOPFDATEN - Collection: All required data is entered, we are still fetching the account through multiple requests, should be finished within seconds, poll back soon.
  • VOLLSTAENDIG - Finished: The data retrieval is completed
  • » aktivesSicherheitsverfahren SecurityProcedure false none The security procedure determines how the end user releases his transaction (s).
    » aktualisierungszeitpunkt DateTime false none Time of the last query at the bank / service provider
    » timeout DateTime false none Lifetime of the data in seconds from the time of the update
    » bankprodukte [Product] false none The banking products available in the access
    » sync boolean false none Whether the bank account is automatically updated in the background.

    BankAccessIssues

    {
      "id": "815251d6-c062-4f61-bec0-182bc14a48fb",
      "providerId": "00000000-0000-0000-0000-000000000000",
      "tanMedien": [
        {
          "gueltigVon": "2016-06-03 17:17:41",
          "gueltigBis": "2016-06-03 17:17:41",
          "name": "Mobil",
          "medienklasse": "MOBIL"
        }
      ],
      "sicherheitsverfahren": [
        {
          "kodierung": 2,
          "name": "mTAN",
          "hinweis": "mTAN"
        },
        {
          "kodierung": 1,
          "name": "Mock-TAN",
          "hinweis": "Mock-TAN"
        }
      ],
      "aktivesSicherheitsverfahren": {
        "kodierung": 1,
        "name": "Mock-TAN",
        "hinweis": "Mock-TAN"
      },
      "challenge": {
        "name": "Mock-TAN-Verfahren",
        "content": {
          "instructions": "Enter a TAN that is divisible by 2"
        }
      },
      "aktualisierungszeitpunkt": "2016-06-10 17:17:40",
      "messages": [
        {
          "level": "INFO",
          "code": "BA3010",
          "message": "SCA benötigt",
          "details": "Bitte wählen Sie eine SCA-Methode aus"
        }
      ],
      "relations": [
        {
          "rel": "set_method",
          "href": "https://banksapi.io/v2/customer/consent/1345340218050910215PSDDE-BAFIN-152070CO4960JJ"
        }
      ]
    }
    
    

    Properties

    allOf

    Name Type Required Restrictions Description
    anonymous ScaInteraction false none BankAccess and Transfer inherit from this object. It indicates that in some cases, SCA may be needed to interact with the inheriting object.

    and

    Name Type Required Restrictions Description
    anonymous object false none The issues endpoint holds the last known issues for a bank access (useful to retrieve the reason for delayed / failed background or manual sync) This method communicates all messages, also errors, that are not displayed in the stable bank access
    » aktivesSicherheitsverfahren SecurityProcedure false none The security procedure determines how the end user releases his transaction (s).
    » aktualisierungszeitpunkt DateTime false none Time of the last query at the bank / service provider
    » id string false none ID of the bank access
    » providerId string false none ID of the provider
    » challenge Challenge false none Contains information about TAN generation

    MessageLevel

    "ERROR"
    
    

    MessageLevel

    Properties

    Name Type Required Restrictions Description
    MessageLevel string false none Level of the message, INFO or ERROR
    Enumerated Values
    Property Value
    MessageLevel INFO
    MessageLevel ERROR

    Interaction

    {
      "messages": [
        {
          "code": "BA1110",
          "level": "INFO",
          "message": "TAN-Eingabe nötig",
          "details": "Bitte geben Sie die TAN ein"
        }
      ],
      "timeout": "2017-08-31 16:08:55",
      "relations": [
        {
          "rel": "submit_text_tan",
          "href": "https://banksapi.io/customer/v2/ueberweisung/00000000-0000-0000-0000-000000000000/DE00123456789012345679/c612b2f3-f797-4f66-bec4-2064812c8736"
        }
      ],
      "challenge": {
        "name": "chipTAN optisch",
        "content": {
          "HHD": "11048714955205123456789F14302C303107",
          "HHDUC": "1234567891234567891234567890,01"
        }
      }
    }
    
    

    Interaction

    Properties

    Name Type Required Restrictions Description
    messages [Message] true none Messages for TAN input or error texts for transfer
    relations [Relation] true none Relations for follow-up actions
    timeout string(date) false none Time to wait for follow-up actions
    challenge Challenge false none Contains information about TAN generation

    ConsentStatus

    "received"
    
    

    ConsentStatus

    Properties

    Name Type Required Restrictions Description
    ConsentStatus string false none This is the overall life cycle status of the consent.

    Valid values are:
  • RECEIVED: The consent data have been received and are technically correct. The data is not authorised yet.
  • REJECTED: The consent data have been rejected e.g. since no successful authorisation has taken place.
  • VALID: The consent is accepted and valid for GET account data calls and others as specified in the consent object.
  • REVOKED_BY_USER: The consent has been revoked by the PSU towards the ASPSP.
  • EXPIRED: The consent expired.
  • Enumerated Values
    Property Value
    ConsentStatus RECEIVED
    ConsentStatus REJECTED
    ConsentStatus VALID
    ConsentStatus EXPIRED
    ConsentStatus REVOKED_BY_USER

    SystemName

    "BANKFINANCE"
    
    

    SystemName

    Properties

    Name Type Required Restrictions Description
    SystemName string false none Machine-readable name of the tag, for a list check e.g. the transaction categories

    Sca

    {
      "scaStatus": "finalised",
      "gueltigBis": "2019-05-02 18:20:48"
    }
    
    

    Sca

    Properties

    Name Type Required Restrictions Description
    scaStatus string true none finalised
    gueltigBis string true none none

    CreateBankAccessData

    {
      "815251d6-c062-4f61-bec0-182bc14a48fb": {
        "providerId": "00000000-0000-0000-0000-000000000000",
        "credentials": {
          "userid": "mOd2uKYr+2 ... TWOPCAt5zP",
          "pin": "Hhnc+aW/eM ... 7F+XRSHasW"
        },
        "sync": true
      }
    }
    
    

    Create Bank Access Data

    Properties

    Name Type Required Restrictions Description
    providerId string(uuid) true none The ID of the access provider (bank or service provider ) according to the provider list
    credentials Credentials true none The Credentials object is a map of encrypted and Base64-encoded access data, corresponding to the provider's authentication fields. The Base64 encoding must not use line wrapping. The encryption method used is described in the chapter Encryption.
    sync boolean false none Whether an automatic regular background update is to be performed

    CreateClientToken

    {
      "grant_type": "client_credentials",
      "scope": "http://banksapi.io/provider/read"
    }
    
    

    CreateClientToken

    Properties

    Name Type Required Restrictions Description
    grant_type string true none Must always be client_credentials
    scope string false none Space-separated list of desired scopes. A scope names a class of access rules. It is a string, usually in the form of a (fictitious) URL. The available scopes depend on the scope of services booked. You therefore receive the scope list together with your cooperation agreement.

    CreateUserToken

    {
      "grant_type": "client_credentials",
      "scope": "http://banksapi.io/provider/read"
    }
    
    

    CreateUserToken

    Properties

    Name Type Required Restrictions Description
    grant_type string true none Must always be password
    username string true none Username of user
    password string true none Password of user
    scope string false none Space-separated list of desired scopes. A scope names a class of access rules. It is a string, usually in the form of a (fictitious) URL. The available scopes depend on the scope of services booked. You therefore receive the scope list together with your cooperation agreement.

    Token

    {
      "scope": "http://banksapi.io/customer/read http://banksapi.io/customer/modify",
      "tenant": "demo",
      "client": "demo-client",
      "user": "1c5b33f6-9c4d-11e6-ba80-480fcfb9550f",
      "access_token": "0defaced-1337-d00d-c0de-face8badcafe",
      "token_type": "Bearer"
    }
    
    

    Token

    Properties

    Name Type Required Restrictions Description
    scope string true none Space-separated list of OAuth2 scopes. A scope names a class of access rules. It is a string, usually in the form of a (fictitious) URL. The available scopes depend on the scope of services booked. You therefore receive the scope list together with your cooperation agreement.
    tenant string true none Technical name of the tenant
    client string true none Technical name of the client
    user string false none User reference, only set if this is a user token
    access_token string true none The token
    token_type string true none Always "Bearer"

    Customer

    {
      "messages": [
        {
          "level": "INFO",
          "code": "BA3010",
          "message": "SCA benötigt",
          "details": "Bitte wählen Sie eine SCA-Methode aus"
        }
      ],
      "bankzugaenge": {
        "4000fda7-18af-463f-b694-bbafe5d23a48": {
          "messages": [
            {
              "level": "INFO",
              "code": "BA3010",
              "message": "SCA benötigt",
              "details": "Bitte wählen Sie eine SCA-Methode aus"
            }
          ],
          "sicherheitsverfahren": [
            {
              "kodierung": 980,
              "name": "mTAN",
              "hinweis": "mTAN"
            },
            {
              "name": "SMS_OTP",
              "kodierung": "942",
              "hinweis": "SMS OTP"
            }
          ],
          "relations": [
            {
              "rel": "start_sca",
              "href": "https://banksapi.io/v2/customer/consent/1345340218050910215PSDDE-BAFIN-152070CO4960JJ"
            }
          ]
        }
      },
      "relations": [
        {
          "rel": "start_sca",
          "href": "https://banksapi.io/customer/v2"
        },
        {
          "rel": "authenticate",
          "href": "https://banksapi.io/customer/v2"
        },
        {
          "rel": "set_method",
          "href": "https://banksapi.io/customer/v2/consent/{consent-id}"
        },
        {
          "rel": "set_medium",
          "href": "https://banksapi.io/customer/v2/consent/{consent-id}"
        },
        {
          "rel": "self",
          "href": "https://banksapi.io/customer/v2"
        },
        {
          "rel": "get_bankzugaenge",
          "href": "https://banksapi.io/customer/v2/bankzugaenge"
        },
        {
          "rel": "add_bankzugaenge",
          "href": "https://banksapi.io/customer/v2/bankzugaenge"
        },
        {
          "rel": "delete_bankzugaenge",
          "href": "https://banksapi.io/customer/v2/bankzugaenge"
        }
      ]
    }
    
    

    Customer

    Properties

    Name Type Required Restrictions Description
    messages [Message] false none [Messages transport both errors and analysis events.]
    bankzugaenge ListOfBankAccesses false none Collection of bank accesses
    relations [Relation] false none [A relation corresponds to an application or business transaction that is supported by the enclosing data object. Each application or business transaction has its own documentation, which describes the call as well as the return or the possible alternative answer scenarios in detail.]

    BankAccessStatus

    "STARTED"
    
    

    BankAccessStatus

    Properties

    Name Type Required Restrictions Description
    BankAccessStatus string false none Retrieval status of the bank account

    Status list :
  • GESTARTET - Started: The data retrieval was started
  • INTERAKTION - Interaction: User intervention required, e.g. SCA required, see messages and relations
  • KOPFDATEN - Collection: All required data is entered, we are still fetching the account through multiple requests, should be finished within seconds, poll back soon.
  • VOLLSTAENDIG - Finished: The data retrieval is completed
  • Enumerated Values
    Property Value
    BankAccessStatus GESTARTET
    BankAccessStatus INTERAKTION
    BankAccessStatus KOPFDATEN
    BankAccessStatus VOLLSTAENDIG

    BankProductStatus

    "STARTED"
    
    

    BankProductStatus

    Properties

    Name Type Required Restrictions Description
    BankProductStatus string false none Retrieval status of the bank product

    Status list :
  • GESTARTET - Started: The data retrieval was started
  • VOLLSTAENDIG - Finished: The data retrieval is completed
  • Enumerated Values
    Property Value
    BankProductStatus GESTARTET
    BankProductStatus VOLLSTAENDIG

    TANMedium

    {
      "gueltigVon": "2016-01-01 00:00:00",
      "gueltigBis": "2016-12-31 23:59:59",
      "name": "+49-1111-11111",
      "medienklasse": "MOBIL"
    }
    
    

    TANMedium

    Properties

    Name Type Required Restrictions Description
    gueltigVon DateTime false none Start of validity.
    gueltigBis DateTime false none End of validity.
    name string false none Name of the TAN medium such as the mobile phone number
    medienklasse MediaClass false none Media Classes:
  • LIST - Paper-TAN list
  • GENERATOR - TAN generator
  • MOBILE - mobile phone
  • SECODER - TAN matrix generator
  • PUSHTAN - Push message
  • MediaClass

    "MOBILE"
    
    

    MediaClass

    Properties

    Name Type Required Restrictions Description
    MediaClass string false none Media Classes:
  • LIST - Paper-TAN list
  • GENERATOR - TAN generator
  • MOBILE - mobile phone
  • SECODER - TAN matrix generator
  • PUSHTAN - Push message
  • Enumerated Values
    Property Value
    MediaClass LIST
    MediaClass GENERATOR
    MediaClass MOBILE
    MediaClass SECODER
    MediaClass PUSHTAN

    SecurityProcedure

    {
      "kodierung": "4711",
      "name": "mTAN",
      "hinweis": "Ihre mTAN"
    }
    
    

    SecurityProcedure

    Properties

    Name Type Required Restrictions Description
    kodierung string false none Key to the security procedure
    name string false none Human readable name for the security procedure
    hinweis string false none Human readable reference to the security procedure

    Classification

    {
      "category": "bills_electricity",
      "parentCategory": "bills",
      "displayName": "Strom",
      "confidenceLevel": 0.8
    }
    
    

    Classification

    Properties

    Name Type Required Restrictions Description
    category string true none Unique system name of sales category
    parentCategory string false none If it is a subcategory, this field includes the system name of the main category
    displayName string true none User friendly name of sales category
    confidenceLevel string false none Probability value (0-1) that account sales belong to this category

    Investment

    {
      "name": "Aberdeen Global - Emer. Markets Equity E2",
      "menge": 210.819609,
      "handelseinheit": "STUECK",
      "isin": "LU0498181733",
      "wkn": "A1C5UV",
      "kurs": 15.4117,
      "kursDatum": "2015-05-11 00:00:00",
      "waehrung": "EUR",
      "waehrungskurs": 1,
      "handelsplatz": "KAG",
      "gesamtwert": 3249.09
    }
    
    

    Investment

    Properties

    Name Type Required Restrictions Description
    name string false none Name of the deposit position, usually the name of the financial instrument
    menge number false none Pieces with decimal places
    handelseinheit string false none Trade item, STUECK or NOMINAL
    isin string false none ISIN of the financial instrument
    wkn string false none WKN of the financial instrument
    kurs number false none Price in trading currency
    kursDatum DateTime false none State of the course
    waehrung string false none Trading currency (Alphabetic Code ISO 4217)
    waehrungskurs number false none Conversion rate from EUR to the trading currency
    handelsplatz string false none Trading place of the price determination
    gesamtwert string false none Total value of the stock in EUR as at the end of the financial statements
    Enumerated Values
    Property Value
    handelseinheit STUECK
    handelseinheit NOMINAL

    Tenant

    {
      "name": "demo",
      "description": "A tenant for demonstration purposes"
    }
    
    

    Tenant

    Properties

    Name Type Required Restrictions Description
    name string true none Tenant technical name becomes URL component
    description string false none Optional human readable description

    User

    {
      "userReference": "1c5b33f6-9c4d-11e6-ba80-480fcfb9550f",
      "username": "demo-user"
    }
    
    

    User

    Properties

    Name Type Required Restrictions Description
    userReference string true none Technical ID for the user, is also used in URLs (user-id)
    username string true none Username for creating an OAuth2 token

    DateTime

    "2019-12-04 13:37:00"
    
    

    DateTime

    Properties

    Name Type Required Restrictions Description
    DateTime string false none This object represents a timestamp. Format: YYYY-MM-DD hh:mm:ss. Data will be interpreted according to the time zone Europe/Berlin.

    IsoDateTime

    "2019-12-04T13:37:00"
    
    

    IsoDateTime

    Properties

    Name Type Required Restrictions Description
    IsoDateTime string false none This object represents an ISO timestamp. Format: ISO 8601 in the form YYYY-MM-DDThh:mm:ss. Data will be interpreted according to the time zone Europe/Berlin.

    title: AI/

    AI/Connect API Reference v2.00

    Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

    General Remarks

    Overview

    BANKSapi AI Endpoints first categorizes individual transactions along the dimensions of spending type,spending frequency and business partner.

    After enriching individual transactions on these dimensions, the transactions of a specific user are aggregated and used as inputs to the next level of machine learning models to categorize the user along different dimensions such as monthly budget structure, spending habits across time and across spending categories, life stages.

    Tagging Concept

    The data enrichment process described above is conceptualized as Tagging and is used across all the endpoints. The following concepts are crucial to the understanding of tagging and make consumption of the endpoints easier. Following is a bottom-up description of tagging. - Entity is an object that is being tagged, e.g. a transaction. - TagInstance is a concrete instance of a Tag, which associates an Entity with a TagTreeItem and instance specific details. TagTreeItem captures the standardized part of the tagging, in other words the information that we can map to a standardized concept in a controlled vocabulary. In a CATEGORY TagInstance this corresponds to RECREATION_ONLINE. details on the other hand captures the instance-specific information. For the same CATEGORY example, it would contain the confidence level, which is specific only to this instance of the tagging exercise. - TagTreeItem is a standardized concept which is a member of a controlled vocabulary with others. - TagTree is a set of standardized concepts, which form a controlled vocabulary.

    Base URLs:

    Email: info@banksapi.de Web: info@banksapi.de

    Authentication

    Categories

    General categorization of transactions

    Returns spending categorization tags

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/bankzugaenge/{access-id}/{product-id}/kontoumsaetze?tag=true \
      -H 'Accept: application/json' \
      -H 'Authentication: API_KEY'
    
    

    GET https://banksapi.io/customer/v2/bankzugaenge/{access-id}/{product-id}/kontoumsaetze?tag=true

    Gives transaction categories based on everyday spending types such as groceries shopping or rental payments.

    To get a full list of such categories, use:

    /tags/tag_trees/1/tag_tree_items/

    Categorization Logic

    We use a hybrid model, that combines a basic model and a NLP-Based AI model.

    Basic model runs first. If it cannot find a category, AI model runs. If the found category has a sufficient confidence, it is returned.

    If the basic model yields multiple tags, the AI model runs as well. Majority voting in combination with a confidence threshold is used to detect the most likely category.

    Basic Model

    This model searches for keywords and regular expression based substrings in note to payee, counterparty name and posting text.

    It includes the main categories of the insurance classifier to precisely detect insurance transactions.

    Artificial Intelligence Model

    The model architecture is a bidirectional recurrent neural network with long short-term memory and an attention mechanism.

    Training data contains semantically-meaningful word embeddings, pre-trained in an unsupervised setting as well as human and automatically labeled data, providing a total of more than a million training samples.

    Parameters

    Name In Type Required Description
    access-id path string true ID of the bank access
    product-id path boolean true ID of the bank product
    persist query boolean false This option persists tags in the database. Default value is false. Use with enforce=true for ephemeral category tags.

    Example responses

    200 Response

    [
      {
        "betrag": -13.09,
        "buchungsdatum": "2020-03-11 18:00:00",
        "gegenkontoBic": "",
        "gegenkontoIban": "",
        "gegenkontoInhaber": "",
        "hash": "8891f1f9-511a-3ed6-8982-ef4078cecc16",
        "id": "956ca508-c0e2-52c5-3202-8de20e7ed12b",
        "primanotaNummer": "12345",
        "tags": [
          {
            "entity": {
              "displayName": "TRANSACTION",
              "entityClass": "TRANSACTION",
              "id": "956ca508-c0e2-52c5-3202-8de20e7ed12b"
            },
            "id": "eb047b64-619f-4104-805e-ee6c832bc306",
            "relations": [
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
                "rel": "tag_trees"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/2/",
                "rel": "tag_tree"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/2/tag-tree-items/",
                "rel": "tag_tree_items"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/2/tag-tree-items/164/",
                "rel": "tag_tree_item"
              }
            ],
            "tagTreeItem": {
              "displayName": "Kapitallebensversicherung",
              "systemId": 164,
              "systemName": "LIFE_ENDOWMENT",
              "systemNameParent": "LIFE",
              "tagTree": {
                "description": "Two level fine grained insurance categorization tag tree.",
                "displayName": "Versicherungsarten",
                "isClientGenerated": false,
                "systemId": 2,
                "systemName": "INSURANCE_TYPES",
                "version": 2.4
              }
            }
          }
        ],
        "verwendungszweck": "CRED DE07ZZZ00000063475 Beitrag Lebensvers 2020 01 SEPA BASISLASTSCHRIFT wiederholend",
        "wertstellungsdatum": "2020-03-11 18:00:00"
      }
    ]
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Success Inline none
    400 Bad Request BadRequest None none
    403 Forbidden Forbidden None none
    500 Internal Server Error InternalServerError None none

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    anonymous [v2_output_connect_schema] false none none
    » account string true none Account which the transaction is associated with
    » betrag number true none Amount in Euros
    » buchungsdatum string true none Date the transaction was initiated in yyyy-mm-dd HH:MM format
    » buchungstext string false none Text entered during posting
    » gegenkontoBic string false none BIC of the counterparty
    » gegenkontoIban string false none IBAN of the counterparty
    » gegenkontoInhaber string false none Name of the counterparty
    » gvCode string false none SEPA GV Code (Geschäftsvorfallcode)
    » hash string false none Hash value for historical ordering
    » id string true none Unique Universal Identifier (UUID)
    » primanotaNummer string false none Id used by the bank
    » product string false none Account which the transaction is associated with
    » provider string false none Id of the bank
    » tags [tag_instance_schema] false none List of tags of the transaction
    »» entity entity_schema true none none
    »»» accountId string false none Tenant generated Account id for TRANSACTIONs, empty for USER
    »»» displayName string true none Display name of the entity
    »»» entityClass string true none Class of the entity, such as TRANSACTION or USER
    »»» id string true none Transaction UUID or USER UUID.
    »»» userId string false none UUID of the USER. Same as id field for USER entities.
    »» id string true none Unique Universal Identifier (UUID)
    »» relations [relation_schema] false none List of relations
    »»» href string true none Link of the relation
    »»» rel string true none Name of the relation
    »» tagTreeItem tag_tree_item_schema true none none
    »»» addressCity string false none Address city of the business partner
    »»» addressCountry string false none Address country of the business partner
    »»» addressStreet string false none Address street incl. number of the business partner
    »»» addressZip string false none Address zip/postal code of the business partner
    »»» categories [string] false none Categories the business partner belongs to.
    »»» creditorId string false none creditor id of the business partner
    »»» description string false none Gives a description of the tagTreeItem
    »»» displayName string true none User-friendly name shown to the end-users
    »»» group string false none Group the business partner belongs to.
    »»» relations [relation_schema] false none List of relations
    »»» systemId integer true none Unique internal id of the tag tree or tag tree item
    »»» systemName string true none Unique name of the tag, tag tree or tag tree item
    »»» systemNameParent string false none Unique name of the parent of the tagTreeItem
    »»» tagTree tag_tree_schema true none tagTree that the tagTreeItem belongs to
    »»»» description string false none Gives a description of the tag tree
    »»»» displayName string true none User-friendly name shown to the end-users
    »»»» isTenantGenerated boolean true none Boolean iflag, set TRUE if the tag was manually set
    »»»» relations [relation_schema] false none List of relations
    »»»» systemId integer true none Unique internal id of the tag tree or tag tree item
    »»»» systemName string true none Unique name of the tag, tag tree or tag tree item
    »»»» version number true none Version of the tag tree
    »»» telephone string false none Telephone of the business partner
    »»» website string false none Website of the business partner
    »» tenant string true none Tenant ID to which the transaction belongs
    »» user string true none Universally Unique Identifier of the user
    »» verwendungszweck string true none Text entered during posting
    »» wertstellungsdatum string false none Financial booking date in in yyyy-mm-dd HH:MM format.

    Contracts

    Contract detection of a user

    Return contract tags

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/ai/contracts/ \
      -H 'Accept: application/json' \
      -H 'x-correlation-id: [object Object]' \
      -H 'Authentication: API_KEY'
    
    

    GET /contracts/

    Detects contracts using all the transactions of a user, independent of accounts and banks. All the transactions are aggregated.

    The transactions are categorized and periodic payments are detected first.

    Contracts are created by grouping payments of similar size in the same category and made to a certain business partners.

    After transactions are grouped, we extract further statistics and make simple predictions on next amount and due date.

    APR Estimation

    Best effort estimate of the Annual Percentage Rate (APR) is given for fixed payment credit contracts. This feature works if:

    * The note to payee includes breakdown of the principal and interest payments and we have the first 2 payments to the credit giver.

    * We see the initial credit payment to the user and next two fixed payments, without having the interest/principal payment ratio.

    Identifying Contracts with a Hash

    Contract Tag Instance IDs are generated by hashing the Counterparty Name and IBAN, period tag, and the date time of the first transaction.

    This gives a best effort uniqueness to the ids.

    Parameters

    Name In Type Required Description
    x-correlation-id header string false Optional UUID used to track end-to-end processing of the request
    insuranceOnly query boolean false If True, returns insurance contracts only.

    Example responses

    200 Response

    [
      {
        "details": {
          "amountFirst": -319,
          "amountLatest": -319,
          "amountMaximum": -319,
          "amountMean": -319,
          "amountMinimum": -319,
          "amountNext": -319,
          "amountTotal": -4466,
          "costDevelopment": {
            "2019-01-20": -319,
            "2019-02-20": -319,
            "2019-03-20": -319,
            "2019-04-20": -319,
            "2019-05-20": -319,
            "2019-06-20": -319,
            "2019-07-20": -319,
            "2019-08-20": -319,
            "2019-09-20": -319,
            "2019-10-20": -319,
            "2019-11-20": -319,
            "2019-12-20": -319,
            "2020-01-20": -319,
            "2020-02-20": -319
          },
          "counterpartyBic": "",
          "counterpartyIban": "DE123456222",
          "counterpartyName": "Allianz Private Krankenversicherungs AG",
          "dateFirst": "2019-01-20",
          "dateLatest": "2020-02-20",
          "dateNext": "2020-03-20",
          "daysAge": 445,
          "growthRate": 0,
          "numberCustomer": ".:",
          "standardDeviation": 0,
          "status": "ACTIVE",
          "transactionIds": [
            "qj64ir73-30ba-yei2-1i1q-vrg8glvkhwno",
            "lbmk8o1n-a832-xcqi-mpcp-brv4pieipge8",
            "qks1f8e9-59yu-rglt-yvq9-y8jnlm5huhro",
            "2j3599se-4b53-q06f-78u6-byv3q9hltndt",
            "hqe7417d-9ixm-6bzk-0ckm-tp3914r4k2ay",
            "dxfav1pk-vqxv-6390-qrb3-4pigp5s614u5",
            "a36lxcgg-3drd-f7w5-e3bb-uin03hxxni48",
            "cs7ew6pu-mn2n-5xko-48sj-u33owtszqqub",
            "uzi9a837-63ld-t8b2-t2s0-sle79yz1mx88",
            "yayvsn9d-oszt-mg4k-8q86-f0du01kineis",
            "9n4va5cc-5hx3-r14q-ehe2-9d7c2jbehstq",
            "kbw1nxhc-uxmq-4pyi-kar7-hlii1viy9bus",
            "g3kqczjp-5cuq-ntl6-k5vw-454vfy0bfa3d",
            "yv8uh99n-csyj-66xn-4wkr-f3nvzzxkhas7"
          ]
        },
        "entity": {
          "displayName": "USER",
          "entityClass": "USER",
          "id": "0b64d605-0483-4bae-8b12-fa26e313060b"
        },
        "id": "824aa59a-c243-744f-fcbb-a6ce1edacd02",
        "relations": [
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
            "rel": "tag_trees"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/",
            "rel": "tag_tree_category"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/",
            "rel": "tag_tree_items_category"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/64/",
            "rel": "tag_tree_item_category"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/2/",
            "rel": "tag_tree_insurance_type"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/2/tag-tree-items/",
            "rel": "tag_tree_items_insurance_type"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/2/tag-tree-items/134/",
            "rel": "tag_tree_item_insurance_type"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/4/",
            "rel": "tag_tree_period"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/4/tag-tree-items/",
            "rel": "tag_tree_items_period"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/4/tag-tree-items/235/",
            "rel": "tag_tree_item_period"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/3/",
            "rel": "tag_tree_business_partner"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/3/tag-tree-items/",
            "rel": "tag_tree_items_business_partner"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/3/tag-tree-items/206/",
            "rel": "tag_tree_item_business_partner"
          }
        ],
        "tagTreeItemBusinessPartner": {
          "addressCity": "München",
          "addressCountry": "Deutschland",
          "addressStreet": "Königinstraße 28",
          "addressZip": "80802",
          "creditorId": "DE40ZZZ00000063851",
          "displayName": "Allianz Private Krankenversicherung",
          "group": "Allianz",
          "systemId": 206,
          "systemName": "Allianz Private Krankenversicherungs AG",
          "tagTree": {
            "description": "Single level tag tree of business partners.",
            "displayName": "Geschäftspartner",
            "isClientGenerated": false,
            "systemId": 3,
            "systemName": "BUSINESS_PARTNERS",
            "version": 1.9
          },
          "telephone": "089-3800-1000",
          "website": "http://www.allianz.de"
        },
        "tagTreeItemCategory": {
          "description": "Payments related to a health insurance contract",
          "displayName": "Krankenversicherung",
          "systemId": 64,
          "systemName": "INSURANCE_HEALTH",
          "systemNameParent": "INSURANCE",
          "tagTree": {
            "description": "Two level categorization tree.",
            "displayName": "Kategorien",
            "isClientGenerated": false,
            "systemId": 1,
            "systemName": "CATEGORIES",
            "version": 3.7
          }
        },
        "tagTreeItemInsuranceType": {
          "displayName": "Private Krankenversicherung",
          "systemId": 134,
          "systemName": "HEALTH_PRIVATE",
          "systemNameParent": "HEALTH",
          "tagTree": {
            "description": "Two level fine grained insurance categorization tag tree.",
            "displayName": "Versicherungsarten",
            "isClientGenerated": false,
            "systemId": 2,
            "systemName": "INSURANCE_TYPES",
            "version": 2.4
          }
        },
        "tagTreeItemPeriod": {
          "description": "Period of a single month",
          "displayName": "Ein Monat",
          "systemId": 235,
          "systemName": "MONTH_ONE",
          "systemNameParent": "MONTH",
          "tagTree": {
            "description": "Two level periods tag tree.",
            "displayName": "Turnus",
            "isClientGenerated": false,
            "systemId": 4,
            "systemName": "PERIODS",
            "version": 0.4
          }
        }
      }
    ]
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Success Inline none
    400 Bad Request BadRequest None none
    403 Forbidden Forbidden None none
    500 Internal Server Error InternalServerError None none

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    anonymous [contract_tag_instance_schema] false none none
    » details contract_tag_instance_details_schema false none none
    »» amountFirst number true none First payment among contract payments
    »» amountLatest number true none Most recent payment among contract payments
    »» amountMaximum number true none Maximum payment among contract payments
    »» amountMean number true none Mean payment among contract payments
    »» amountMinimum number true none Minimum payment among contract payments
    »» amountNext number false none Predicted next payment based on contract payments
    »» amountTotal number true none Total amount paid to the contract
    »» contractNumbers [string] true none List of detected contract numbers
    »» costDevelopment object true none Payment history
    »» counterpartyBic string false none BIC of the counterparty
    »» counterpartyIban string false none IBAN of the counterparty
    »» counterpartyName string false none Name of the counterparty copied from a transaction, without any modification
    »» creditAmount number false none Net amount of the loan being paid back with the contract
    »» creditAmountGross number false none Total amount of the loan being paid back with the contract including additional costs
    »» customName string false none If there is no listed business partner found, a custom name is tried to be extracted from the transaction.
    »» customerNumbers [string] true none List of detected customer numbers
    »» dateEnd string(date) false none Contract end date
    »» dateFirst string(date) true none Date of the first payment
    »» dateLatest string(date) true none Date of the last payment
    »» dateNext string(date) false none Predicted date of the next payment
    »» dateStart string(date) false none Contract start date
    »» daysAge integer true none Age of the contract in days
    »» growthRate number false none Procentual growth rate per period
    »» interestRate number false none Effective annual interest rate estimated for this contract
    »» interestRateNominal number false none Nominal annual interest rate detected for this contract
    »» numberContract string false none Contract number
    »» numberCustomer string false none Customer number
    »» standardDeviation number false none Standard deviation of contract payments
    »» status string true none Status of contract (ACTIVE or NOT_ACTIVE)
    »» transactionIds [string] true none List of transaction ids
    » entity entity_schema true none none
    »» accountId string false none Tenant generated Account id for TRANSACTIONs, empty for USER
    »» displayName string true none Display name of the entity
    »» entityClass string true none Class of the entity, such as TRANSACTION or USER
    »» id string true none Transaction UUID or USER UUID.
    »» userId string false none UUID of the USER. Same as id field for USER entities.
    » id string true none Unique Universal Identifier (UUID)
    » relations [relation_schema] false none List of relations
    »» href string true none Link of the relation
    »» rel string true none Name of the relation
    » tagTreeItemBusinessPartner tag_tree_item_schema true none none
    »» addressCity string false none Address city of the business partner
    »» addressCountry string false none Address country of the business partner
    »» addressStreet string false none Address street incl. number of the business partner
    »» addressZip string false none Address zip/postal code of the business partner
    »» categories [string] false none Categories the business partner belongs to.
    »» creditorId string false none creditor id of the business partner
    »» description string false none Gives a description of the tagTreeItem
    »» displayName string true none User-friendly name shown to the end-users
    »» group string false none Group the business partner belongs to.
    »» relations [relation_schema] false none List of relations
    »» systemId integer true none Unique internal id of the tag tree or tag tree item
    »» systemName string true none Unique name of the tag, tag tree or tag tree item
    »» systemNameParent string false none Unique name of the parent of the tagTreeItem
    »» tagTree tag_tree_schema true none tagTree that the tagTreeItem belongs to
    »»» description string false none Gives a description of the tag tree
    »»» displayName string true none User-friendly name shown to the end-users
    »»» isTenantGenerated boolean true none Boolean iflag, set TRUE if the tag was manually set
    »»» relations [relation_schema] false none List of relations
    »»» systemId integer true none Unique internal id of the tag tree or tag tree item
    »»» systemName string true none Unique name of the tag, tag tree or tag tree item
    »»» version number true none Version of the tag tree
    »» telephone string false none Telephone of the business partner
    »» website string false none Website of the business partner
    » tagTreeItemCategory tag_tree_item_schema true none none
    » tagTreeItemInsuranceType tag_tree_item_schema false none none
    » tagTreeItemPeriod tag_tree_item_schema true none none

    Life

    Determine life events and life stages of a user

    Return the life events of a user

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/ai/life-events/ \
      -H 'Accept: application/json' \
      -H 'x-correlation-id: [object Object]' \
      -H 'Authentication: API_KEY'
    
    

    GET /life-events/

    Detects all life events of a user.

    Life events are key events in a user's life that represent some significant change. They are always the start or end of some activity or state. In general, although life events often correspond to the start or end of a life stage, this is not necessarily always the case.

    This endpoint returns all life events in the past with the corresponding date. Some life events are unique (e.g. first employment, first tenancy), others may recur over time (e.g. new tenancy, birth of child).

    Refer to /api/v2/tags/tag-trees/10/tag-tree-items/ for a full list of life stages.

    Life Event Tag Instance IDs are generated by hashing the User ID, event date and the tagTreeItem ID of the Tag Instance. This gives a best effort uniqueness to the ids.

    Parameters

    Name In Type Required Description
    x-correlation-id header string false Optional UUID used to track end-to-end processing of the request

    Example responses

    200 Response

    [
      {
        "details": {
          "eventDate": "2019-07-01"
        },
        "entity": {
          "displayName": "USER",
          "entityClass": "USER",
          "id": "0b64d605-0483-4bae-8b12-fa26e313060b"
        },
        "id": "924bbc71-2444-aa4a-4821-e92e9976ed17",
        "relations": [
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
            "rel": "tag_trees"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/10/",
            "rel": "tag_tree"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/10/tag-tree-items/",
            "rel": "tag_tree_items"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/10/tag-tree-items/931/",
            "rel": "tag_tree_item"
          }
        ],
        "tagTreeItem": {
          "displayName": "Ende Mietverhältnis",
          "systemId": 931,
          "systemName": "TENANCY_END",
          "tagTree": {
            "description": "Single level life event tag tree, usually with both start and end tags.",
            "displayName": "Lebensereignisse",
            "isClientGenerated": false,
            "systemId": 10,
            "systemName": "LIFE_EVENTS",
            "version": 0.3
          }
        }
      }
    ]
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Success Inline none
    400 Bad Request BadRequest None none
    403 Forbidden Forbidden None none
    500 Internal Server Error InternalServerError None none

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    anonymous [lifeevent_tag_instance_schema] false none none
    » details lifeevent_tag_instance_details_schema true none none
    »» eventDate string(date) true none Date of the event
    » entity entity_schema true none none
    »» accountId string false none Tenant generated Account id for TRANSACTIONs, empty for USER
    »» displayName string true none Display name of the entity
    »» entityClass string true none Class of the entity, such as TRANSACTION or USER
    »» id string true none Transaction UUID or USER UUID.
    »» userId string false none UUID of the USER. Same as id field for USER entities.
    » id string true none Unique Universal Identifier (UUID)
    » relations [relation_schema] false none List of relations
    »» href string true none Link of the relation
    »» rel string true none Name of the relation
    » tagTreeItem life_tag_tree_item_schema true none none
    »» addressCity string false none Address city of the business partner
    »» addressCountry string false none Address country of the business partner
    »» addressStreet string false none Address street incl. number of the business partner
    »» addressZip string false none Address zip/postal code of the business partner
    »» categories [string] false none Categories the business partner belongs to.
    »» creditorId string false none creditor id of the business partner
    »» description string false none Gives a description of the tagTreeItem
    »» displayName string true none User-friendly name shown to the end-users
    »» domain tag_tree_item_schema true none Life domain this tag belongs to
    »»» addressCity string false none Address city of the business partner
    »»» addressCountry string false none Address country of the business partner
    »»» addressStreet string false none Address street incl. number of the business partner
    »»» addressZip string false none Address zip/postal code of the business partner
    »»» categories [string] false none Categories the business partner belongs to.
    »»» creditorId string false none creditor id of the business partner
    »»» description string false none Gives a description of the tagTreeItem
    »»» displayName string true none User-friendly name shown to the end-users
    »»» group string false none Group the business partner belongs to.
    »»» relations [relation_schema] false none List of relations
    »»» systemId integer true none Unique internal id of the tag tree or tag tree item
    »»» systemName string true none Unique name of the tag, tag tree or tag tree item
    »»» systemNameParent string false none Unique name of the parent of the tagTreeItem
    »»» tagTree tag_tree_schema true none tagTree that the tagTreeItem belongs to
    »»»» description string false none Gives a description of the tag tree
    »»»» displayName string true none User-friendly name shown to the end-users
    »»»» isTenantGenerated boolean true none Boolean iflag, set TRUE if the tag was manually set
    »»»» relations [relation_schema] false none List of relations
    »»»» systemId integer true none Unique internal id of the tag tree or tag tree item
    »»»» systemName string true none Unique name of the tag, tag tree or tag tree item
    »»»» version number true none Version of the tag tree
    »»» telephone string false none Telephone of the business partner
    »»» website string false none Website of the business partner
    »» group string false none Group the business partner belongs to.
    »» relations [relation_schema] false none List of relations
    »» systemId integer true none Unique internal id of the tag tree or tag tree item
    »» systemName string true none Unique name of the tag, tag tree or tag tree item
    »» tagTree tag_tree_schema true none tagTree that the tagTreeItem belongs to
    »»» description string false none Gives a description of the tag tree
    »»» displayName string true none User-friendly name shown to the end-users
    »»» isTenantGenerated boolean true none Boolean iflag, set TRUE if the tag was manually set
    »»» relations [relation_schema] false none List of relations
    »»» systemId integer true none Unique internal id of the tag tree or tag tree item
    »»» systemName string true none Unique name of the tag, tag tree or tag tree item
    »»» version number true none Version of the tag tree
    »» telephone string false none Telephone of the business partner
    »» website string false none Website of the business partner

    Return life stages of a user

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/ai/life-stages/ \
      -H 'Accept: application/json' \
      -H 'x-correlation-id: [object Object]' \
      -H 'Authentication: API_KEY'
    
    

    GET /life-stages/

    Detects life stages using all transactions of a user. Life stages are detected with the help of contracts dealing with significant aspects of life (e.g. rentals, employment contracts).

    Life stages are structured in four domains, each representing information about different aspects of life: - Labour Market: Professional and academic career of the user - Parenthood: Indicating whether the user has children - Housing: Information about ownership / rental agreements of the user's accommodation - Savings: Current user activity for preparing retirement

    Refer to /api/v2/tags/tag-trees/8/tag-tree-items/ for a full list of life stages.

    Life Stage Tag Instance Ids are generated by hashing the User ID and the tagTreeItem ID of the Tag Instance. This gives a best effort uniqueness to the ids.

    Parameters

    Name In Type Required Description
    x-correlation-id header string false Optional UUID used to track end-to-end processing of the request

    Example responses

    200 Response

    [
      {
        "entity": {
          "displayName": "USER",
          "entityClass": "USER",
          "id": "0b64d605-0483-4bae-8b12-fa26e313060b"
        },
        "id": "83b507c5-0be5-e3c8-a0b7-f3339744cfa2",
        "relations": [
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
            "rel": "tag_trees"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/8/",
            "rel": "tag_tree"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/8/tag-tree-items/",
            "rel": "tag_tree_items"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/8/tag-tree-items/923/",
            "rel": "tag_tree_item"
          }
        ],
        "tagTreeItem": {
          "displayName": "Mieter",
          "systemId": 923,
          "systemName": "TENANCY",
          "tagTree": {
            "description": "Single level life stage tag tree.",
            "displayName": "Lebensphasen",
            "isClientGenerated": false,
            "systemId": 8,
            "systemName": "LIFE_STAGES",
            "version": 0.4
          }
        }
      },
      {
        "entity": {
          "displayName": "USER",
          "entityClass": "USER",
          "id": "0b64d605-0483-4bae-8b12-fa26e313060b"
        },
        "id": "be26f079-38de-3d1e-504c-404efad17365",
        "relations": [
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
            "rel": "tag_trees"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/8/",
            "rel": "tag_tree"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/8/tag-tree-items/",
            "rel": "tag_tree_items"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/8/tag-tree-items/915/",
            "rel": "tag_tree_item"
          }
        ],
        "tagTreeItem": {
          "displayName": "Elternteil",
          "systemId": 915,
          "systemName": "PARENTHOOD",
          "tagTree": {
            "description": "Single level life stage tag tree.",
            "displayName": "Lebensphasen",
            "isClientGenerated": false,
            "systemId": 8,
            "systemName": "LIFE_STAGES",
            "version": 0.4
          }
        }
      },
      {
        "entity": {
          "displayName": "USER",
          "entityClass": "USER",
          "id": "0b64d605-0483-4bae-8b12-fa26e313060b"
        },
        "id": "af7b1ceb-9eda-2db4-7e91-8097dc902d42",
        "relations": [
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
            "rel": "tag_trees"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/8/",
            "rel": "tag_tree"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/8/tag-tree-items/",
            "rel": "tag_tree_items"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/8/tag-tree-items/912/",
            "rel": "tag_tree_item"
          }
        ],
        "tagTreeItem": {
          "displayName": "Angestellt",
          "systemId": 912,
          "systemName": "EMPLOYMENT",
          "tagTree": {
            "description": "Single level life stage tag tree.",
            "displayName": "Lebensphasen",
            "isClientGenerated": false,
            "systemId": 8,
            "systemName": "LIFE_STAGES",
            "version": 0.4
          }
        }
      }
    ]
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Success Inline none
    400 Bad Request BadRequest None none
    403 Forbidden Forbidden None none
    500 Internal Server Error InternalServerError None none

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    anonymous [life_stage_tag_instance_schema] false none none
    » entity entity_schema true none none
    »» accountId string false none Tenant generated Account id for TRANSACTIONs, empty for USER
    »» displayName string true none Display name of the entity
    »» entityClass string true none Class of the entity, such as TRANSACTION or USER
    »» id string true none Transaction UUID or USER UUID.
    »» userId string false none UUID of the USER. Same as id field for USER entities.
    » id string true none Unique Universal Identifier (UUID)
    » relations [relation_schema] false none List of relations
    »» href string true none Link of the relation
    »» rel string true none Name of the relation
    » tagTreeItem life_tag_tree_item_schema true none none
    »» addressCity string false none Address city of the business partner
    »» addressCountry string false none Address country of the business partner
    »» addressStreet string false none Address street incl. number of the business partner
    »» addressZip string false none Address zip/postal code of the business partner
    »» categories [string] false none Categories the business partner belongs to.
    »» creditorId string false none creditor id of the business partner
    »» description string false none Gives a description of the tagTreeItem
    »» displayName string true none User-friendly name shown to the end-users
    »» domain tag_tree_item_schema true none Life domain this tag belongs to
    »»» addressCity string false none Address city of the business partner
    »»» addressCountry string false none Address country of the business partner
    »»» addressStreet string false none Address street incl. number of the business partner
    »»» addressZip string false none Address zip/postal code of the business partner
    »»» categories [string] false none Categories the business partner belongs to.
    »»» creditorId string false none creditor id of the business partner
    »»» description string false none Gives a description of the tagTreeItem
    »»» displayName string true none User-friendly name shown to the end-users
    »»» group string false none Group the business partner belongs to.
    »»» relations [relation_schema] false none List of relations
    »»» systemId integer true none Unique internal id of the tag tree or tag tree item
    »»» systemName string true none Unique name of the tag, tag tree or tag tree item
    »»» systemNameParent string false none Unique name of the parent of the tagTreeItem
    »»» tagTree tag_tree_schema true none tagTree that the tagTreeItem belongs to
    »»»» description string false none Gives a description of the tag tree
    »»»» displayName string true none User-friendly name shown to the end-users
    »»»» isTenantGenerated boolean true none Boolean iflag, set TRUE if the tag was manually set
    »»»» relations [relation_schema] false none List of relations
    »»»» systemId integer true none Unique internal id of the tag tree or tag tree item
    »»»» systemName string true none Unique name of the tag, tag tree or tag tree item
    »»»» version number true none Version of the tag tree
    »»» telephone string false none Telephone of the business partner
    »»» website string false none Website of the business partner
    »» group string false none Group the business partner belongs to.
    »» relations [relation_schema] false none List of relations
    »» systemId integer true none Unique internal id of the tag tree or tag tree item
    »» systemName string true none Unique name of the tag, tag tree or tag tree item
    »» tagTree tag_tree_schema true none tagTree that the tagTreeItem belongs to
    »»» description string false none Gives a description of the tag tree
    »»» displayName string true none User-friendly name shown to the end-users
    »»» isTenantGenerated boolean true none Boolean iflag, set TRUE if the tag was manually set
    »»» relations [relation_schema] false none List of relations
    »»» systemId integer true none Unique internal id of the tag tree or tag tree item
    »»» systemName string true none Unique name of the tag, tag tree or tag tree item
    »»» version number true none Version of the tag tree
    »» telephone string false none Telephone of the business partner
    »» website string false none Website of the business partner

    Sales Triggers

    Sales trigger detection of a user

    Return sales triggers tags

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/ai/sales-triggers/ \
      -H 'Accept: application/json' \
      -H 'x-correlation-id: [object Object]' \
      -H 'Authentication: API_KEY'
    
    

    GET /sales-triggers/

    This end-point runs Contracts and Life Endpoints and returns sales triggers when conditions on these sales triggers are met for the specific user.

    Refer to /api/v2/tags/tag-trees/5/tag-tree-items/ for a full list of sales_triggers.

    Sales Triggers are extendible on a tenant basis.

    Sales Trigger Instance Ids are generated by hashing the User ID and the tagTreeItem ID of the Sales Trigger Tags. This gives a best effort uniqueness to the ids.

    Parameters

    Name In Type Required Description
    x-correlation-id header string false Optional UUID used to track end-to-end processing of the request
    threshold query integer false Sales trigger savings potential: Threshold amount.

    Example responses

    200 Response

    [
      {
        "entity": {
          "displayName": "USER",
          "entityClass": "USER",
          "id": "0b64d605-0483-4bae-8b12-fa26e313060b"
        },
        "id": "85b962ac-1e50-3d2f-3e83-bc577678ad55",
        "relations": [
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
            "rel": "tag_trees"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/5/",
            "rel": "tag_tree"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/5/tag-tree-items/",
            "rel": "tag_tree_items"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/5/tag-tree-items/247/",
            "rel": "tag_tree_item"
          }
        ],
        "tagTreeItem": {
          "description": "Trigger for a missing private liability insurance",
          "displayName": "Trigger für eine fehlende Privathaftpflichtversicherung",
          "systemId": 247,
          "systemName": "MISSING_INSURANCE_LIABILITY_PRIVATE",
          "systemNameParent": "MISSING",
          "tagTree": {
            "description": "Two level sales trigger tag tree.",
            "displayName": "Sales Trigger",
            "isClientGenerated": false,
            "systemId": 5,
            "systemName": "SALES_TRIGGERS",
            "version": 0.1
          }
        }
      }
    ]
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Success Inline none
    400 Bad Request BadRequest None none
    403 Forbidden Forbidden None none
    500 Internal Server Error InternalServerError None none

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    anonymous [tag_instance_schema] false none none
    » entity entity_schema true none none
    »» accountId string false none Tenant generated Account id for TRANSACTIONs, empty for USER
    »» displayName string true none Display name of the entity
    »» entityClass string true none Class of the entity, such as TRANSACTION or USER
    »» id string true none Transaction UUID or USER UUID.
    »» userId string false none UUID of the USER. Same as id field for USER entities.
    » id string true none Unique Universal Identifier (UUID)
    » relations [relation_schema] false none List of relations
    »» href string true none Link of the relation
    »» rel string true none Name of the relation
    » tagTreeItem tag_tree_item_schema true none none
    »» addressCity string false none Address city of the business partner
    »» addressCountry string false none Address country of the business partner
    »» addressStreet string false none Address street incl. number of the business partner
    »» addressZip string false none Address zip/postal code of the business partner
    »» categories [string] false none Categories the business partner belongs to.
    »» creditorId string false none creditor id of the business partner
    »» description string false none Gives a description of the tagTreeItem
    »» displayName string true none User-friendly name shown to the end-users
    »» group string false none Group the business partner belongs to.
    »» relations [relation_schema] false none List of relations
    »» systemId integer true none Unique internal id of the tag tree or tag tree item
    »» systemName string true none Unique name of the tag, tag tree or tag tree item
    »» systemNameParent string false none Unique name of the parent of the tagTreeItem
    »» tagTree tag_tree_schema true none tagTree that the tagTreeItem belongs to
    »»» description string false none Gives a description of the tag tree
    »»» displayName string true none User-friendly name shown to the end-users
    »»» isTenantGenerated boolean true none Boolean iflag, set TRUE if the tag was manually set
    »»» relations [relation_schema] false none List of relations
    »»» systemId integer true none Unique internal id of the tag tree or tag tree item
    »»» systemName string true none Unique name of the tag, tag tree or tag tree item
    »»» version number true none Version of the tag tree
    »» telephone string false none Telephone of the business partner
    »» website string false none Website of the business partner

    Categories V1

    General categorization of transactions version 1

    (DEPRECATED) Returns spending categorization tags

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/bankzugaenge/{access-id}/{product-id}/kontoumsaetze?categorize=true \
      -H 'Accept: application/json' \
      -H 'Authentication: API_KEY'
    
    

    GET https://banksapi.io/customer/v2/bankzugaenge/{access-id}/{product-id}/kontoumsaetze?categorize=true

    DEPRECATED
    Gives transaction categories based on everyday spending types such as groceries shopping or rental payments.

    To get a full list of such categories, use:

    /tags/tag_trees/1/tag_tree_items/ to get the list of categories.

    Categorization Logic

    We use a hybrid model, that combines a basic model and a NLP-Based AI model.

    Basic model runs first. If it cannot find a category, AI model runs. If the found category has a sufficient confidence, it is returned.

    If the basic model yields multiple tags, the AI model runs as well. Majority voting in combination with a confidence threshold is used to detect the most likely category.

    Basic Model

    This model searches for keywords and regular expression based substrings in note to payee, counterparty name and posting text.

    It includes the main categories of the insurance classifier to precisely detect insurance transactions.

    Artificial Intelligence Model

    The model architecture is a bidirectional recurrent neural network with long short-term memory and an attention mechanism.

    Training data contains semantically-meaningful word embeddings, pre-trained in an unsupervised setting as well as human and automatically labeled data, providing a total of more than a million training samples.

    Parameters

    Name In Type Required Description
    access-id path string true ID of the bank access
    product-id path boolean true ID of the bank product
    persist query boolean false This option persists tags in the database. Default value is false. Use with enforce=true for ephemeral category tags.

    Example responses

    200 Response

    [
      {
        "account": "a0c4d28a-ab2f-439a-a7b0-7660a862af6d",
        "betrag": -3.94,
        "buchungsdatum": "2020-03-01 10:00",
        "buchungstext": "Lastschrift",
        "gegenkontoBic": "PBNKDEFF",
        "gegenkontoIban": "DE75512108001245126199",
        "gegenkontoInhaber": "Erika Musterfrau",
        "gvCode": "082",
        "hash": "956ca508-c0e2-52c5-3202-8de20e7ed12b",
        "id": "956ca508-c0e2-52c5-3202-8de20e7ed12b",
        "primanotaNummer": "999001",
        "product": "30cc4587-7e5f-450f-bb51-dc3829f67db4",
        "provider": "23d67ff8-ff6a-44ff-93da-f2af835394e4",
        "tags": [
          {
            "category": "LIVING_GROCERIES",
            "confidenceLevel": 0.95,
            "displayName": "Lebensmittel",
            "parent": "LIVING",
            "parentCategory": "LIVING",
            "systemName": "LIVING_GROCERIES",
            "tagId": "956ca508-c0e2-52c5-3202-8de20e7ed12b",
            "tagScope": "transaction",
            "tagType": "CATEGORY",
            "tagVersion": "1.5"
          }
        ],
        "tenant": "1bcb487e-f409-4438-a358-d8d128581761",
        "user": "624ca509-b0f2-42f6-b202-8de20e9ed12a",
        "verwendungszweck": "Miete 2020 03 Wohnung 123 Bahnhofsstraße 1",
        "wertstellungsdatum": "2020-03-01 10:00"
      }
    ]
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Success Inline none
    400 Bad Request BadRequest None none
    403 Forbidden Forbidden None none
    500 Internal Server Error InternalServerError None none

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    anonymous [v1_output] false none none
    » account string true none Account which the transaction is associated with
    » betrag number true none Amount in Euros
    » buchungsdatum string true none Date the transaction was initiated in yyyy-mm-dd HH:MM format
    » buchungstext string false none Text entered during posting
    » gegenkontoBic string false none BIC of the counterparty
    » gegenkontoIban string false none IBAN of the counterparty
    » gegenkontoInhaber string false none Name of the counterparty
    » gvCode string false none SEPA GV Code (Geschäftsvorfallcode)
    » hash string false none Hash value for historical ordering
    » id string true none Unique Universal Identifier (UUID)
    » primanotaNummer string false none Id used by the bank
    » product string false none Account which the transaction is associated with
    » provider string false none Id of the bank
    » tags [v1_tag] false none List of tags of the transaction
    »» category string true none Unique name used by the API, similar to systemId.
    »» confidenceLevel number false none Probability that the tag is correct.
    »» displayName string true none User friendly local name.
    »» parent string false none systemName of the tag's parent.
    »» parentCategory string false none systemName of the tag's parent.
    »» systemName string true none Unique name used by the API, similar to systemId.
    »» tagId string false none Unique Universal Identifier (UUID)
    »» tagScope string false none Object of the tag, user or transaction
    »» tagType string false none Type of the tag
    »» tagVersion string true none Version of the tag tree
    » tenant string true none Tenant ID to which the transaction belongs
    » user string true none Universally Unique Identifier of the user
    » verwendungszweck string true none Text entered during posting
    » wertstellungsdatum string false none Financial booking date in in yyyy-mm-dd HH:MM format.

    Tags

    Get information about tag trees and tag tree items

    Get all TagTrees

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/ai/tags/tag-trees/ \
      -H 'Accept: application/json' \
      -H 'x-correlation-id: [object Object]' \
      -H 'Authentication: API_KEY'
    
    

    GET /tags/tag-trees/

    TagTree is a collection of TagTreeItems. Each TagTree represent a versioned set of concepts that are relevant for a Business Domain. We call a curated group of concepts a Controlled Vocabulary as in accordance with the ISO Indexing Standards, hence TagTree represent a specific controlled vocabulary.

    For example, we represent all the different customer spending categories in the TagTree CATEGORY. The set of all supported sales triggers are grouped together in the TagTree SalesTriggers.

    TagTrees can be thought of the root node of a hierarchical concept tree. The leaves of the TagTree are called TagTreeItems.

    One way of interpreting TagTree is seeing it as the root node of the tree. However we have intentionally not taken this path and represented the root node as a separate concept in our concept model.

    This gives us the flexibility of giving versions to TagTrees. When we add a new TagTreeItem or deprecate an old one, we are actually affecting all the TagTreeItems, since the semantic value of each item is in relation to all other items. Such a change is captured by a simple increase in the version number of the TagTree. We do our best to keep such updates rare and backward-compatible, but we do not give hard guarantees.

    Parameters

    Name In Type Required Description
    x-correlation-id header string false Optional UUID used to track end-to-end processing of the request

    Example responses

    200 Response

    [
      {
        "description": "Two level categorization tree.",
        "displayName": "Kategorien",
        "isClientGenerated": false,
        "relations": [
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/",
            "rel": "self"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
            "rel": "tag_trees"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/",
            "rel": "tag_tree_items"
          }
        ],
        "systemId": 1,
        "systemName": "CATEGORIES",
        "version": 3.7
      },
      {
        "description": "Two level fine grained insurance categorization tag tree.",
        "displayName": "Versicherungsarten",
        "isClientGenerated": false,
        "relations": [
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/2/",
            "rel": "self"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
            "rel": "tag_trees"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/2/tag-tree-items/",
            "rel": "tag_tree_items"
          }
        ],
        "systemId": 2,
        "systemName": "INSURANCE_TYPES",
        "version": 2.4
      }
    ]
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Success Inline none

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    anonymous [tag_tree_schema] false none none
    » description string false none Gives a description of the tag tree
    » displayName string true none User-friendly name shown to the end-users
    » isTenantGenerated boolean true none Boolean iflag, set TRUE if the tag was manually set
    » relations [relation_schema] false none List of relations
    »» href string true none Link of the relation
    »» rel string true none Name of the relation
    » systemId integer true none Unique internal id of the tag tree or tag tree item
    » systemName string true none Unique name of the tag, tag tree or tag tree item
    » version number true none Version of the tag tree

    Get a single TagTree

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/ai/tags/tag-trees/{tagTreeId}/ \
      -H 'Accept: application/json' \
      -H 'x-correlation-id: [object Object]' \
      -H 'Authentication: API_KEY'
    
    

    GET /tags/tag-trees/{tagTreeId}/

    Get Information on a single TagTree

    Parameters

    Name In Type Required Description
    x-correlation-id header string false Optional UUID used to track end-to-end processing of the request
    tagTreeId path integer true none

    Example responses

    200 Response

    {
      "description": "Two level categorization tree.",
      "displayName": "Kategorien",
      "isClientGenerated": false,
      "relations": [
        {
          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/",
          "rel": "self"
        },
        {
          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
          "rel": "tag_trees"
        },
        {
          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/",
          "rel": "tag_tree_items"
        }
      ],
      "systemId": 1,
      "systemName": "CATEGORIES",
      "version": 3.7
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Success Inline none

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    » description string false none Gives a description of the tag tree
    » displayName string true none User-friendly name shown to the end-users
    » isTenantGenerated boolean true none Boolean iflag, set TRUE if the tag was manually set
    » relations [relation_schema] false none List of relations
    »» href string true none Link of the relation
    »» rel string true none Name of the relation
    » systemId integer true none Unique internal id of the tag tree or tag tree item
    » systemName string true none Unique name of the tag, tag tree or tag tree item
    » version number true none Version of the tag tree

    Get all TagTreeItems of a specific TagTree

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/ai/tags/tag-trees/{tagTreeId}/tag-tree-items/ \
      -H 'Accept: application/json' \
      -H 'x-correlation-id: [object Object]' \
      -H 'Authentication: API_KEY'
    
    

    GET /tags/tag-trees/{tagTreeId}/tag-tree-items/

    TagTreeItems are the individual words in the Controlled Vocabularies or TagTrees. For example in the TagTree CATEGORY, we represent spending corresponding to online entertainment by the TagTreeItem RECREATION_ONLINE.

    We employ a two level hierarchy in TagTreeItems. The parent-child relation is can be obtained threefold. First, the relation is coded in the systemName attribute, which has the naming convention PARENT_CHILD. Secondly a parent attribute is returned for the children, which has the systemName of the parent TagTreeItem. Finally, a relation having the URI of the parent is also returned. We do not support a parallel children attribute.

    TagTreeItem represent the standardized part of tag instances. They represent the normalized words in the controlled vocabulary represented by Tag Trees.

    Instead of defining a specific tag tree item for each tag tree, we have opted to define a single tag tree item tag, with attributes representing the attributes of all possible tag tree items from all tag trees.

    This is a design choice to keep them searchable under /tag-trees/<int:tagTreeId>/tag-tree-items/. In specific categorizing end-points, where tag tree items are returned, not relevant attributes are deleted on use.

    ## Parameter Details

    ### tagTreeId Use /tags/tag-trees/ to get a list of all tag trees with their systemIds to use them as tagTreeId input in calling this endpoint.

    ### categoryTagTreeItemId This option only works with the BUSINESS_PARTNERS TagTree. This TagTree returns a curated list of contract counterparties. Each business partner in our database is associated to one or multiple TagTreeItems from CATEGORIES TagTree. By setting this parameter to the tagTreeItemId of the wished CATEGORY, e.g. INUSRANCE, BANKFINANCE, you can consume only the business partners in this specific category.

    Parameters

    Name In Type Required Description
    x-correlation-id header string false Optional UUID used to track end-to-end processing of the request
    categoryTagTreeItemId query integer false system id of a tag tree item of the tag tree with the system name 'CATEGORIES'
    tagTreeId path integer true none

    Example responses

    200 Response

    [
      {
        "description": "Transactions in the field of banking and finance",
        "displayName": "Bank und Finanzen",
        "relations": [
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/1/",
            "rel": "self"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
            "rel": "tag_trees"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/",
            "rel": "tag_tree"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/",
            "rel": "tag_tree_items"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/1/",
            "rel": "tag_tree_item"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/None/",
            "rel": "tag_tree_item_parent"
          }
        ],
        "systemId": 1,
        "systemName": "BANKFINANCE",
        "tagTree": {
          "description": "Two level categorization tree.",
          "displayName": "Kategorien",
          "isClientGenerated": false,
          "systemId": 1,
          "systemName": "CATEGORIES",
          "version": 3.7
        }
      },
      {
        "description": "Transactions including invoices & bills",
        "displayName": "Vertragsrechnungen",
        "relations": [
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/2/",
            "rel": "self"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
            "rel": "tag_trees"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/",
            "rel": "tag_tree"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/",
            "rel": "tag_tree_items"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/2/",
            "rel": "tag_tree_item"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/None/",
            "rel": "tag_tree_item_parent"
          }
        ],
        "systemId": 2,
        "systemName": "BILLS",
        "tagTree": {
          "description": "Two level categorization tree.",
          "displayName": "Kategorien",
          "isClientGenerated": false,
          "systemId": 1,
          "systemName": "CATEGORIES",
          "version": 3.7
        }
      }
    ]
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Success Inline none

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    anonymous [tag_tree_item_schema] false none none
    » addressCity string false none Address city of the business partner
    » addressCountry string false none Address country of the business partner
    » addressStreet string false none Address street incl. number of the business partner
    » addressZip string false none Address zip/postal code of the business partner
    » categories [string] false none Categories the business partner belongs to.
    » creditorId string false none creditor id of the business partner
    » description string false none Gives a description of the tagTreeItem
    » displayName string true none User-friendly name shown to the end-users
    » group string false none Group the business partner belongs to.
    » relations [relation_schema] false none List of relations
    »» href string true none Link of the relation
    »» rel string true none Name of the relation
    » systemId integer true none Unique internal id of the tag tree or tag tree item
    » systemName string true none Unique name of the tag, tag tree or tag tree item
    » systemNameParent string false none Unique name of the parent of the tagTreeItem
    » tagTree tag_tree_schema true none tagTree that the tagTreeItem belongs to
    »» description string false none Gives a description of the tag tree
    »» displayName string true none User-friendly name shown to the end-users
    »» isTenantGenerated boolean true none Boolean iflag, set TRUE if the tag was manually set
    »» relations [relation_schema] false none List of relations
    »» systemId integer true none Unique internal id of the tag tree or tag tree item
    »» systemName string true none Unique name of the tag, tag tree or tag tree item
    »» version number true none Version of the tag tree
    » telephone string false none Telephone of the business partner
    » website string false none Website of the business partner

    Get a single TagTreeItem of a specific TagTree

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/ai/tags/tag-trees/{tagTreeId}/tag-tree-items/{tagTreeItemId}/ \
      -H 'Accept: application/json' \
      -H 'x-correlation-id: [object Object]' \
      -H 'Authentication: API_KEY'
    
    

    GET /tags/tag-trees/{tagTreeId}/tag-tree-items/{tagTreeItemId}/

    TagTreeItem represent the standardized part of tag instances. They represent the normalized words in the controlled vocabulary represented by Tag Trees.

    Instead of defining a specific tag tree item for each tag tree, we have opted to define a single tag tree item tag, with attributes representing the attributes of all possible tag tree items from all tag trees.

    This is a design choice to keep them searchable under /tag-trees/<int:tagTreeId>/tag-tree-items/. In specific categorizing end-points, where tag tree items are returned, not relevant attributes are deleted on use.

    Parameters

    Name In Type Required Description
    x-correlation-id header string false Optional UUID used to track end-to-end processing of the request
    tagTreeId path integer true none
    tagTreeItemId path integer true none

    Example responses

    200 Response

    {
      "description": "Transactions in the field of banking and finance",
      "displayName": "Bank und Finanzen",
      "relations": [
        {
          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/1/",
          "rel": "self"
        },
        {
          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
          "rel": "tag_trees"
        },
        {
          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/",
          "rel": "tag_tree"
        },
        {
          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/",
          "rel": "tag_tree_items"
        },
        {
          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/1/",
          "rel": "tag_tree_item"
        },
        {
          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/None/",
          "rel": "tag_tree_item_parent"
        }
      ],
      "systemId": 1,
      "systemName": "BANKFINANCE",
      "tagTree": {
        "description": "Two level categorization tree.",
        "displayName": "Kategorien",
        "isClientGenerated": false,
        "systemId": 1,
        "systemName": "CATEGORIES",
        "version": 3.7
      }
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Success Inline none

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    » addressCity string false none Address city of the business partner
    » addressCountry string false none Address country of the business partner
    » addressStreet string false none Address street incl. number of the business partner
    » addressZip string false none Address zip/postal code of the business partner
    » categories [string] false none Categories the business partner belongs to.
    » creditorId string false none creditor id of the business partner
    » description string false none Gives a description of the tagTreeItem
    » displayName string true none User-friendly name shown to the end-users
    » group string false none Group the business partner belongs to.
    » relations [relation_schema] false none List of relations
    »» href string true none Link of the relation
    »» rel string true none Name of the relation
    » systemId integer true none Unique internal id of the tag tree or tag tree item
    » systemName string true none Unique name of the tag, tag tree or tag tree item
    » systemNameParent string false none Unique name of the parent of the tagTreeItem
    » tagTree tag_tree_schema true none tagTree that the tagTreeItem belongs to
    »» description string false none Gives a description of the tag tree
    »» displayName string true none User-friendly name shown to the end-users
    »» isTenantGenerated boolean true none Boolean iflag, set TRUE if the tag was manually set
    »» relations [relation_schema] false none List of relations
    »» systemId integer true none Unique internal id of the tag tree or tag tree item
    »» systemName string true none Unique name of the tag, tag tree or tag tree item
    »» version number true none Version of the tag tree
    » telephone string false none Telephone of the business partner
    » website string false none Website of the business partner

    Insurances

    Insurance focused categorization of transactions

    Return insurance categorization tags

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/ai/insurances/ \
      -H 'Accept: application/json' \
      -H 'x-correlation-id: [object Object]' \
      -H 'Authentication: API_KEY'
    
    

    GET /insurances/

    Gives detailed insurance categories in accordance with the category tree of GDV (Die deutschen Versicherer).

    Categorization is based on keywords and regular expressions. This classification is an extension of Category endpoint and can be thought as a third level in the classification hierarchy.

    To get a full list of insurance tags, use:

    /tags/tag_trees/2/tag_tree_items/

    Parameters

    Name In Type Required Description
    x-correlation-id header string false Optional UUID used to track end-to-end processing of the request
    enforce query boolean false This option enforces categorization. Previously saved tags are ignored. Default value is true.
    persist query boolean false This option persists tags in the database. Default value is false. Use with enforce=true for ephemeral category tags.

    Example responses

    200 Response

    [
      {
        "betrag": -13.09,
        "buchungsdatum": "2020-03-11 18:00:00",
        "gegenkontoBic": "",
        "gegenkontoIban": "",
        "gegenkontoInhaber": "",
        "hash": "8891f1f9-511a-3ed6-8982-ef4078cecc16",
        "id": "956ca508-c0e2-52c5-3202-8de20e7ed12b",
        "primanotaNummer": "12345",
        "tags": [
          {
            "entity": {
              "displayName": "TRANSACTION",
              "entityClass": "TRANSACTION",
              "id": "956ca508-c0e2-52c5-3202-8de20e7ed12b"
            },
            "id": "eb047b64-619f-4104-805e-ee6c832bc306",
            "relations": [
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
                "rel": "tag_trees"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/2/",
                "rel": "tag_tree"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/2/tag-tree-items/",
                "rel": "tag_tree_items"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/2/tag-tree-items/164/",
                "rel": "tag_tree_item"
              }
            ],
            "tagTreeItem": {
              "displayName": "Kapitallebensversicherung",
              "systemId": 164,
              "systemName": "LIFE_ENDOWMENT",
              "systemNameParent": "LIFE",
              "tagTree": {
                "description": "Two level fine grained insurance categorization tag tree.",
                "displayName": "Versicherungsarten",
                "isClientGenerated": false,
                "systemId": 2,
                "systemName": "INSURANCE_TYPES",
                "version": 2.4
              }
            }
          }
        ],
        "verwendungszweck": "CRED DE07ZZZ00000063475 Beitrag Lebensvers 2020 01 SEPA BASISLASTSCHRIFT wiederholend",
        "wertstellungsdatum": "2020-03-11 18:00:00"
      }
    ]
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Success Inline none
    400 Bad Request BadRequest None none
    403 Forbidden Forbidden None none
    500 Internal Server Error InternalServerError None none

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    anonymous [v2_output_connect_schema] false none none
    » account string true none Account which the transaction is associated with
    » betrag number true none Amount in Euros
    » buchungsdatum string true none Date the transaction was initiated in yyyy-mm-dd HH:MM format
    » buchungstext string false none Text entered during posting
    » gegenkontoBic string false none BIC of the counterparty
    » gegenkontoIban string false none IBAN of the counterparty
    » gegenkontoInhaber string false none Name of the counterparty
    » gvCode string false none SEPA GV Code (Geschäftsvorfallcode)
    » hash string false none Hash value for historical ordering
    » id string true none Unique Universal Identifier (UUID)
    » primanotaNummer string false none Id used by the bank
    » product string false none Account which the transaction is associated with
    » provider string false none Id of the bank
    » tags [tag_instance_schema] false none List of tags of the transaction
    »» entity entity_schema true none none
    »»» accountId string false none Tenant generated Account id for TRANSACTIONs, empty for USER
    »»» displayName string true none Display name of the entity
    »»» entityClass string true none Class of the entity, such as TRANSACTION or USER
    »»» id string true none Transaction UUID or USER UUID.
    »»» userId string false none UUID of the USER. Same as id field for USER entities.
    »» id string true none Unique Universal Identifier (UUID)
    »» relations [relation_schema] false none List of relations
    »»» href string true none Link of the relation
    »»» rel string true none Name of the relation
    »» tagTreeItem tag_tree_item_schema true none none
    »»» addressCity string false none Address city of the business partner
    »»» addressCountry string false none Address country of the business partner
    »»» addressStreet string false none Address street incl. number of the business partner
    »»» addressZip string false none Address zip/postal code of the business partner
    »»» categories [string] false none Categories the business partner belongs to.
    »»» creditorId string false none creditor id of the business partner
    »»» description string false none Gives a description of the tagTreeItem
    »»» displayName string true none User-friendly name shown to the end-users
    »»» group string false none Group the business partner belongs to.
    »»» relations [relation_schema] false none List of relations
    »»» systemId integer true none Unique internal id of the tag tree or tag tree item
    »»» systemName string true none Unique name of the tag, tag tree or tag tree item
    »»» systemNameParent string false none Unique name of the parent of the tagTreeItem
    »»» tagTree tag_tree_schema true none tagTree that the tagTreeItem belongs to
    »»»» description string false none Gives a description of the tag tree
    »»»» displayName string true none User-friendly name shown to the end-users
    »»»» isTenantGenerated boolean true none Boolean iflag, set TRUE if the tag was manually set
    »»»» relations [relation_schema] false none List of relations
    »»»» systemId integer true none Unique internal id of the tag tree or tag tree item
    »»»» systemName string true none Unique name of the tag, tag tree or tag tree item
    »»»» version number true none Version of the tag tree
    »»» telephone string false none Telephone of the business partner
    »»» website string false none Website of the business partner
    »» tenant string true none Tenant ID to which the transaction belongs
    »» user string true none Universally Unique Identifier of the user
    »» verwendungszweck string true none Text entered during posting
    »» wertstellungsdatum string false none Financial booking date in in yyyy-mm-dd HH:MM format.

    Cashflow

    Cashflow statistics and predictions of a user

    Return cashflow tags with statistics and predictions

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/ai/cashflow/ \
      -H 'Accept: application/json' \
      -H 'x-correlation-id: [object Object]' \
      -H 'Authentication: API_KEY'
    
    

    GET /cashflow/

    This is a utility function for Personal Finance Management applications.

    The endpoint simply aggregates transactions on the dimension set by the request parameter focus:

    If focus set to time, the transactions are partitioned by time and aggregated by the choice of tag. If tag is set to CATEGORIES, we deliver the distribution of net cash-flow across all categories, indexed over time periods. The results can be used as monthly pie-charts depicting spending habits. By setting tag to BUSINESS_PARTNERS, distribution is calculated across business partners.

    If focus is set to tag, we limit the result to the net cash-flow in a given tag, and get the time domain changes for this specific tag. If the request parameter tag is set to **CATEGORIES**, we answer the question: "How did my spending change within a category over time?". By settingtag` to BUSINESS_PARTNERS, we answer "How much did I spend to a certain business partner over time?"

    Parameters

    Name In Type Required Description
    x-correlation-id header string false Optional UUID used to track end-to-end processing of the request
    focus query string false Cashflow is generated with the focus on either time or tag (CATEGORIES or BUSINESS_PARTNER)
    tag query string false Tag to use when summarizing the cashflow.
    catLevel query string false Use the usual tags ("sub") or their parents ("main"). Only relevant if tag=CATEGORIES
    Enumerated Values
    Parameter Value
    focus tag
    focus time
    tag CATEGORIES
    tag BUSINESS_PARTNERS
    catLevel sub
    catLevel main

    Example responses

    200 Response

    [
      {
        "details": {
          "predictions": [],
          "statistics": [
            {
              "cashflow": -1879.46,
              "tagTreeItem": {
                "displayName": "Gesamt",
                "systemId": 906,
                "systemName": "TOTAL_TOTAL",
                "systemNameParent": "TOTAL",
                "tagTree": {
                  "description": "Two level tree with years as parents and its periods as children.",
                  "displayName": "Cashflow",
                  "isClientGenerated": false,
                  "systemId": 6,
                  "systemName": "CASHFLOW",
                  "version": 1
                }
              }
            },
            {
              "cashflow": -342.91,
              "tagTreeItem": {
                "displayName": "Jahr 2020",
                "systemId": 692,
                "systemName": "2020_Y",
                "systemNameParent": "2020",
                "tagTree": {
                  "description": "Two level tree with years as parents and its periods as children.",
                  "displayName": "Cashflow",
                  "isClientGenerated": false,
                  "systemId": 6,
                  "systemName": "CASHFLOW",
                  "version": 1
                }
              }
            },
            {
              "cashflow": -342.91,
              "tagTreeItem": {
                "displayName": "1. Quartal 2020",
                "systemId": 634,
                "systemName": "2020_Q1",
                "systemNameParent": "2020",
                "tagTree": {
                  "description": "Two level tree with years as parents and its periods as children.",
                  "displayName": "Cashflow",
                  "isClientGenerated": false,
                  "systemId": 6,
                  "systemName": "CASHFLOW",
                  "version": 1
                }
              }
            },
            {
              "cashflow": -154.3,
              "tagTreeItem": {
                "displayName": "Januar 2020",
                "systemId": 622,
                "systemName": "2020_M01",
                "systemNameParent": "2020",
                "tagTree": {
                  "description": "Two level tree with years as parents and its periods as children.",
                  "displayName": "Cashflow",
                  "isClientGenerated": false,
                  "systemId": 6,
                  "systemName": "CASHFLOW",
                  "version": 1
                }
              }
            },
            {
              "cashflow": -29.99,
              "tagTreeItem": {
                "displayName": "1. Kalenderwoche 2020",
                "systemId": 639,
                "systemName": "2020_W01",
                "systemNameParent": "2020",
                "tagTree": {
                  "description": "Two level tree with years as parents and its periods as children.",
                  "displayName": "Cashflow",
                  "isClientGenerated": false,
                  "systemId": 6,
                  "systemName": "CASHFLOW",
                  "version": 1
                }
              }
            }
          ]
        },
        "entity": {
          "displayName": "USER",
          "entityClass": "USER",
          "id": "0b64d605-0483-4bae-8b12-fa26e313060b"
        },
        "id": "4ff21ddb-baae-47f0-8181-77b7c5a7ade0",
        "relations": [
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
            "rel": "tag_trees"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/",
            "rel": "tag_tree"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/",
            "rel": "tag_tree_items"
          },
          {
            "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/2/",
            "rel": "tag_tree_item"
          }
        ],
        "tagTreeItem": {
          "description": "Transactions including invoices & bills",
          "displayName": "Vertragsrechnungen",
          "systemId": 2,
          "systemName": "BILLS",
          "tagTree": {
            "description": "Two level categorization tree.",
            "displayName": "Kategorien",
            "isClientGenerated": false,
            "systemId": 1,
            "systemName": "CATEGORIES",
            "version": 3.7
          }
        }
      }
    ]
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Success Inline none
    400 Bad Request BadRequest None none
    403 Forbidden Forbidden None none
    500 Internal Server Error InternalServerError None none

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    anonymous [cashflow_tag_instance_schema] false none none
    » details cashflow_tag_instance_details_schema false none none
    »» predictions [cashflow_tag_instance_details_stats_preds_schema] false none cashflow predictions
    »»» cashflow number true none cashflow amount in Euros
    »»» tagTreeItem tag_tree_item_schema false none none
    »»»» addressCity string false none Address city of the business partner
    »»»» addressCountry string false none Address country of the business partner
    »»»» addressStreet string false none Address street incl. number of the business partner
    »»»» addressZip string false none Address zip/postal code of the business partner
    »»»» categories [string] false none Categories the business partner belongs to.
    »»»» creditorId string false none creditor id of the business partner
    »»»» description string false none Gives a description of the tagTreeItem
    »»»» displayName string true none User-friendly name shown to the end-users
    »»»» group string false none Group the business partner belongs to.
    »»»» relations [relation_schema] false none List of relations
    »»»»» href string true none Link of the relation
    »»»»» rel string true none Name of the relation
    »»»» systemId integer true none Unique internal id of the tag tree or tag tree item
    »»»» systemName string true none Unique name of the tag, tag tree or tag tree item
    »»»» systemNameParent string false none Unique name of the parent of the tagTreeItem
    »»»» tagTree tag_tree_schema true none tagTree that the tagTreeItem belongs to
    »»»»» description string false none Gives a description of the tag tree
    »»»»» displayName string true none User-friendly name shown to the end-users
    »»»»» isTenantGenerated boolean true none Boolean iflag, set TRUE if the tag was manually set
    »»»»» relations [relation_schema] false none List of relations
    »»»»» systemId integer true none Unique internal id of the tag tree or tag tree item
    »»»»» systemName string true none Unique name of the tag, tag tree or tag tree item
    »»»»» version number true none Version of the tag tree
    »»»» telephone string false none Telephone of the business partner
    »»»» website string false none Website of the business partner
    »»» total string false none total amount
    »» statistics [cashflow_tag_instance_details_stats_preds_schema] false none cashflow statistics
    » entity entity_schema true none none
    »» accountId string false none Tenant generated Account id for TRANSACTIONs, empty for USER
    »» displayName string true none Display name of the entity
    »» entityClass string true none Class of the entity, such as TRANSACTION or USER
    »» id string true none Transaction UUID or USER UUID.
    »» userId string false none UUID of the USER. Same as id field for USER entities.
    » id string true none Unique Universal Identifier (UUID)
    » relations [relation_schema] false none List of relations
    » tagTreeItem tag_tree_item_schema true none none

    Disposable Money

    Disposable money of a user

    Return a disposable money tag

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/ai/disposable-money/ \
      -H 'Accept: application/json' \
      -H 'x-correlation-id: [object Object]' \
      -H 'Authentication: API_KEY'
    
    

    GET /disposable-money/

    Defines the disposable money of a user when the next salary payment is expected.

    The transactions are categorized, contracts created, cashflow analyzed and predicted.

    By detailed analysis of statistics and predictions of a user's transactions, the following values are extracted.

    dateSalaryLatest

    Date of the lastest salary payment

    dateSalaryNext

    date of the next salary payment

    amountSalaryLatest

    Amount of the latest salaray payment

    amountSalaryNext

    Amount of the next salaray payment

    daysUntilSalary

    Days until the next salaray payment is expected

    amountCashflow

    Sum of income and expenses (cashflow) since the latest salary payment

    amountCurrentlyLeft

    Amount currently left until the next salary payment considering the cashflow since the latest salary payment

    amountExpectedFixedCashflow

    Sum of expected income and expenses (cashflow) from contracts due until the next salary payment

    amountExpectedLeft

    Amount expectedly left until the next salary payment considering the cashflow since the latest salary payment and the expected cashflow until the next salary payment

    amountExpectedLeftDaily

    Daily amount expectedly left until the next salary payment considering the cashflow since the latest salary payment and the expected cashflow until the next salary payment

    amountExpectedFlexCashflow

    Sum of flexible income and expenses (cashflow) expected until the next salary payment derived from previous spending habits excluding contracts (expected fixed cashflow)

    amountDisposableMoney

    Amount estimated to be left at the next salary payment considering the cashflow since the latest salary payment the expected fixed cashflow until the next salary payment and the expected flexible cashflow until the next salary payment

    Parameters

    Name In Type Required Description
    x-correlation-id header string false Optional UUID used to track end-to-end processing of the request

    Example responses

    200 Response

    {
      "details": {
        "amountCashflow": -739.2900000000002,
        "amountCurrrentlyLeft": 3117.55,
        "amountDisposableMoney": 3117.55,
        "amountExpectedFixedCashflow": 0,
        "amountExpectedFlexCashflow": 0,
        "amountExpectedLeft": 3117.55,
        "amountExpectedLeftDaily": -283.41,
        "amountSalaryLatest": 3856.84,
        "amountSalaryNext": 3856.84,
        "dateSalaryLatest": "2020-02-29",
        "dateSalaryNext": "2020-03-29",
        "daysUntilSalary": -11
      },
      "entity": {
        "displayName": "USER",
        "entityClass": "USER",
        "id": "0b64d605-0483-4bae-8b12-fa26e313060b"
      },
      "id": "e846b38e-ec53-48de-b3e5-a81f5397c38a",
      "relations": [
        {
          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
          "rel": "tag_trees"
        },
        {
          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/7/",
          "rel": "tag_tree"
        },
        {
          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/7/tag-tree-items/",
          "rel": "tag_tree_items"
        },
        {
          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/7/tag-tree-items/908/",
          "rel": "tag_tree_item"
        }
      ],
      "tagTreeItem": {
        "description": "Information about the disposable money",
        "displayName": "Informationen über frei verfügbares Geld",
        "systemId": 908,
        "systemName": "DISPOSABLEMONEY_INFORMATION",
        "systemNameParent": "DISPOSABLEMONEY",
        "tagTree": {
          "description": "Disposable money tag tree with single parent and child tag.",
          "displayName": "Einkommensüberschuss",
          "isClientGenerated": false,
          "systemId": 7,
          "systemName": "DISPOSABLE_MONEY",
          "version": 0.1
        }
      }
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Success Inline none
    400 Bad Request BadRequest None none
    403 Forbidden Forbidden None none
    500 Internal Server Error InternalServerError None none

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    » details disposable_money_tag_instance_details_schema false none none
    »» amountCashflow number true none Sum of income and expenses (cashflow) since the latest salary payment
    »» amountCurrentlyLeft number true none Amount currently left until the next salary payment considering the cashflow since the latest salary payment
    »» amountDisposableMoney number true none Amount estimated to be left at the next salary payment considering the cashflow since the latest salary payment the expected fixed cashflow until the next salary payment and the expected flexible cashflow until the next salary payment
    »» amountExpectedFixedCashflow number true none Sum of expected income and expenses (cashflow) from contractsdue until the next salary payment
    »» amountExpectedFlexCashflow number true none Sum of flexible income and expenses (cashflow) expected until the next salary payment derived from previous spending habits excluding contracts (expected fixed cashflow)
    »» amountExpectedLeft number true none Amount expectedly left until the next salary payment considering the cashflow since the latest salary payment and the expected cashflow until the next salary payment
    »» amountExpectedLeftDaily number true none Daily amount expectedly left until the next salary payment considering the cashflow since the latest salary payment and the expected cashflow until the next salary payment
    »» amountSalaryLatest number true none Amount of the latest salaray payment
    »» amountSalaryNext number true none Amount of the next salaray payment
    »» dateSalaryLatest string(date) true none Date of the lastest salary payment
    »» dateSalaryNext string(date) true none Predicted date of the next salary payment
    »» daysUntilSalary integer true none Days until the next salaray payment is expected
    » entity entity_schema true none none
    »» accountId string false none Tenant generated Account id for TRANSACTIONs, empty for USER
    »» displayName string true none Display name of the entity
    »» entityClass string true none Class of the entity, such as TRANSACTION or USER
    »» id string true none Transaction UUID or USER UUID.
    »» userId string false none UUID of the USER. Same as id field for USER entities.
    » id string true none Unique Universal Identifier (UUID)
    » relations [relation_schema] false none List of relations
    »» href string true none Link of the relation
    »» rel string true none Name of the relation
    » tagTreeItem tag_tree_item_schema true none none
    »» addressCity string false none Address city of the business partner
    »» addressCountry string false none Address country of the business partner
    »» addressStreet string false none Address street incl. number of the business partner
    »» addressZip string false none Address zip/postal code of the business partner
    »» categories [string] false none Categories the business partner belongs to.
    »» creditorId string false none creditor id of the business partner
    »» description string false none Gives a description of the tagTreeItem
    »» displayName string true none User-friendly name shown to the end-users
    »» group string false none Group the business partner belongs to.
    »» relations [relation_schema] false none List of relations
    »» systemId integer true none Unique internal id of the tag tree or tag tree item
    »» systemName string true none Unique name of the tag, tag tree or tag tree item
    »» systemNameParent string false none Unique name of the parent of the tagTreeItem
    »» tagTree tag_tree_schema true none tagTree that the tagTreeItem belongs to
    »»» description string false none Gives a description of the tag tree
    »»» displayName string true none User-friendly name shown to the end-users
    »»» isTenantGenerated boolean true none Boolean iflag, set TRUE if the tag was manually set
    »»» relations [relation_schema] false none List of relations
    »»» systemId integer true none Unique internal id of the tag tree or tag tree item
    »»» systemName string true none Unique name of the tag, tag tree or tag tree item
    »»» version number true none Version of the tag tree
    »» telephone string false none Telephone of the business partner
    »» website string false none Website of the business partner

    Credit Check

    Check credit worthiness

    Calculatesi credit risk flags

    Code samples

    ## You can also use wget
    curl -X GET https://banksapi.io/customer/v2/ai/credit-check/ \
      -H 'Accept: application/json' \
      -H 'x-correlation-id: [object Object]' \
      -H 'Authentication: API_KEY'
    
    

    GET /credit-check/

    : Returns extendible credit risk flags of user for credit risk assessment. Individual Transactions, contracts, life-stages and events are used to calculate flags. The standard flags are:

    * Ratio of months with negative cashflow * Existence of a fixed employment * Existence of previous active credit contracts * Length of current employment * Average montly salary * Existence of risky activities such as gambling * Returned payments

    These flags are mutually exclusive and extendible for individual tenants.

    Parameters

    Name In Type Required Description
    x-correlation-id header string false Optional UUID used to track end-to-end processing of the request

    Example responses

    200 Response

    {
      "average_monthly_salary": 1234.56,
      "existing_loans": true,
      "fixed_income": true,
      "length_of_employment": 65,
      "mortgage_payments": true,
      "ratio_deficit_months": 0.5,
      "reminder_charges": true,
      "return_debits": true,
      "risky_activities": true
    }
    

    Responses

    Status Meaning Description Schema Possible relations
    200 OK Success Inline none
    400 Bad Request BadRequest None none
    403 Forbidden Forbidden None none
    500 Internal Server Error InternalServerError None none

    Response Schema

    Status Code 200

    Name Type Required Restrictions Description
    » average_monthly_salary number false none The user's monthly salary, averaged over the whole transaction history
    » existing_loans boolean true none Indicator whether the user has any open loans
    » fixed_income boolean true none Indicator whether the user has a fixed income
    » length_of_employment integer false none The time in days the user has been employed with the current contract
    » mortgage_payments boolean true none Indicator whether the user has made at least one payment related to a mortgage
    » ratio_deficit_months number false none Ratio of months the user had deficits
    » reminder_charges boolean true none Indicator whether the user has paid charges for reminders at least once
    » return_debits boolean true none Indicator whether the user has received at least one payment referring to a return debit
    » risky_activities boolean true none Indicator whether the user has been involved in risky activities at least once

    Schemas

    cashflow_tag_instance_details_schema

    {
      "properties": {
        "predictions": {
          "description": "cashflow predictions",
          "items": {
            "properties": {
              "cashflow": {
                "description": "cashflow amount in Euros",
                "example": -3420.58,
                "type": "number"
              },
              "tagTreeItem": {
                "example": {
                  "description": "Transactions in the field of banking and finance",
                  "displayName": "Bank und Finanzen",
                  "relations": [
                    {
                      "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/1/",
                      "rel": "self"
                    },
                    {
                      "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
                      "rel": "tag_trees"
                    },
                    {
                      "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/",
                      "rel": "tag_tree"
                    },
                    {
                      "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/",
                      "rel": "tag_tree_items"
                    },
                    {
                      "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/1/",
                      "rel": "tag_tree_item"
                    },
                    {
                      "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/None/",
                      "rel": "tag_tree_item_parent"
                    }
                  ],
                  "systemId": 1,
                  "systemName": "BANKFINANCE",
                  "tagTree": {
                    "description": "Two level categorization tree.",
                    "displayName": "Kategorien",
                    "isClientGenerated": false,
                    "systemId": 1,
                    "systemName": "CATEGORIES",
                    "version": 3.7
                  }
                },
                "properties": {
                  "addressCity": {
                    "description": "Address city of the business partner",
                    "example": "München",
                    "type": "string"
                  },
                  "addressCountry": {
                    "description": "Address country of the business partner",
                    "example": "Deutschland",
                    "type": "string"
                  },
                  "addressStreet": {
                    "description": "Address street incl. number of the business partner",
                    "example": "Lyonel-Feininger-Straße 28",
                    "type": "string"
                  },
                  "addressZip": {
                    "description": "Address zip/postal code of the business partner",
                    "example": " 80807",
                    "type": "string"
                  },
                  "categories": {
                    "description": "Categories the business partner belongs to.",
                    "example": [
                      "BANKFINANCE",
                      "SERVICES",
                      "SERVICES_PROFESSIONAL"
                    ],
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "creditorId": {
                    "description": "creditor id of the business partner",
                    "example": "DEZZZ00000012345",
                    "type": "string"
                  },
                  "description": {
                    "description": "Gives a description of the tagTreeItem",
                    "example": "Expenses from daily grocery purchases",
                    "type": "string"
                  },
                  "displayName": {
                    "description": "User-friendly name shown to the end-users",
                    "example": "Groceries",
                    "type": "string"
                  },
                  "group": {
                    "description": "Group the business partner belongs to.",
                    "example": "Finconomy AG",
                    "type": "string"
                  },
                  "relations": {
                    "description": "List of relations",
                    "items": {
                      "properties": {
                        "href": {
                          "description": "Link of the relation",
                          "example": "https://banksapi.io/.../tags/tag-trees/1/",
                          "type": "string"
                        },
                        "rel": {
                          "description": "Name of the relation",
                          "example": "tag_trees",
                          "type": "string"
                        }
                      },
                      "required": [
                        "href",
                        "rel"
                      ],
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "systemId": {
                    "description": "Unique internal id of the tag tree or tag tree item",
                    "example": 17,
                    "type": "integer"
                  },
                  "systemName": {
                    "description": "Unique name of the tag, tag tree or tag tree item",
                    "example": "LIVING_GROCERIES",
                    "type": "string"
                  },
                  "systemNameParent": {
                    "description": "Unique name of the parent of the tagTreeItem",
                    "example": "LIVING",
                    "type": "string"
                  },
                  "tagTree": {
                    "allOf": [
                      {
                        "example": {
                          "description": "Two level categorization tree.",
                          "displayName": "Kategorien",
                          "isClientGenerated": false,
                          "relations": [
                            {
                              "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/",
                              "rel": "self"
                            },
                            {
                              "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
                              "rel": "tag_trees"
                            },
                            {
                              "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/",
                              "rel": "tag_tree_items"
                            }
                          ],
                          "systemId": 1,
                          "systemName": "CATEGORIES",
                          "version": 3.7
                        },
                        "properties": {
                          "description": {
                            "description": "Gives a description of the tag tree",
                            "example": "Detailed inusrance categories.",
                            "type": "string"
                          },
                          "displayName": {
                            "description": "User-friendly name shown to the end-users",
                            "example": "Groceries",
                            "type": "string"
                          },
                          "isTenantGenerated": {
                            "description": "Boolean iflag, set TRUE if the tag was manually set",
                            "example": true,
                            "type": "boolean"
                          },
                          "relations": {
                            "description": "List of relations",
                            "items": {
                              "properties": {
                                "href": {
                                  "description": "Link of the relation",
                                  "example": "https://banksapi.io/.../tags/tag-trees/1/",
                                  "type": "string"
                                },
                                "rel": {
                                  "description": "Name of the relation",
                                  "example": "tag_trees",
                                  "type": "string"
                                }
                              },
                              "required": [
                                "href",
                                "rel"
                              ],
                              "type": "object"
                            },
                            "type": "array"
                          },
                          "systemId": {
                            "description": "Unique internal id of the tag tree or tag tree item",
                            "example": 17,
                            "type": "integer"
                          },
                          "systemName": {
                            "description": "Unique name of the tag, tag tree or tag tree item",
                            "example": "LIVING_GROCERIES",
                            "type": "string"
                          },
                          "version": {
                            "description": "Version of the tag tree",
                            "example": 1.5,
                            "minimum": 0,
                            "type": "number"
                          }
                        },
                        "required": [
                          "displayName",
                          "isTenantGenerated",
                          "systemId",
                          "systemName",
                          "version"
                        ],
                        "type": "object"
                      }
                    ],
                    "description": "tagTree that the tagTreeItem belongs to"
                  },
                  "telephone": {
                    "description": "Telephone of the business partner",
                    "example": "+49 (0)89 121 408 82",
                    "type": "string"
                  },
                  "website": {
                    "description": "Website of the business partner",
                    "example": "www.banksapi.de",
                    "type": "string"
                  }
                },
                "required": [
                  "displayName",
                  "systemId",
                  "systemName",
                  "tagTree"
                ],
                "type": "object"
              },
              "total": {
                "description": "total amount",
                "example": "EXPENSES",
                "type": "string"
              }
            },
            "required": [
              "cashflow"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "statistics": {
          "description": "cashflow statistics",
          "items": {
            "properties": {
              "cashflow": {
                "description": "cashflow amount in Euros",
                "example": -3420.58,
                "type": "number"
              },
              "tagTreeItem": {
                "example": {
                  "description": "Transactions in the field of banking and finance",
                  "displayName": "Bank und Finanzen",
                  "relations": [
                    {
                      "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/1/",
                      "rel": "self"
                    },
                    {
                      "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
                      "rel": "tag_trees"
                    },
                    {
                      "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/",
                      "rel": "tag_tree"
                    },
                    {
                      "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/",
                      "rel": "tag_tree_items"
                    },
                    {
                      "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/1/",
                      "rel": "tag_tree_item"
                    },
                    {
                      "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/None/",
                      "rel": "tag_tree_item_parent"
                    }
                  ],
                  "systemId": 1,
                  "systemName": "BANKFINANCE",
                  "tagTree": {
                    "description": "Two level categorization tree.",
                    "displayName": "Kategorien",
                    "isClientGenerated": false,
                    "systemId": 1,
                    "systemName": "CATEGORIES",
                    "version": 3.7
                  }
                },
                "properties": {
                  "addressCity": {
                    "description": "Address city of the business partner",
                    "example": "München",
                    "type": "string"
                  },
                  "addressCountry": {
                    "description": "Address country of the business partner",
                    "example": "Deutschland",
                    "type": "string"
                  },
                  "addressStreet": {
                    "description": "Address street incl. number of the business partner",
                    "example": "Lyonel-Feininger-Straße 28",
                    "type": "string"
                  },
                  "addressZip": {
                    "description": "Address zip/postal code of the business partner",
                    "example": " 80807",
                    "type": "string"
                  },
                  "categories": {
                    "description": "Categories the business partner belongs to.",
                    "example": [
                      "BANKFINANCE",
                      "SERVICES",
                      "SERVICES_PROFESSIONAL"
                    ],
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "creditorId": {
                    "description": "creditor id of the business partner",
                    "example": "DEZZZ00000012345",
                    "type": "string"
                  },
                  "description": {
                    "description": "Gives a description of the tagTreeItem",
                    "example": "Expenses from daily grocery purchases",
                    "type": "string"
                  },
                  "displayName": {
                    "description": "User-friendly name shown to the end-users",
                    "example": "Groceries",
                    "type": "string"
                  },
                  "group": {
                    "description": "Group the business partner belongs to.",
                    "example": "Finconomy AG",
                    "type": "string"
                  },
                  "relations": {
                    "description": "List of relations",
                    "items": {
                      "properties": {
                        "href": {
                          "description": "Link of the relation",
                          "example": "https://banksapi.io/.../tags/tag-trees/1/",
                          "type": "string"
                        },
                        "rel": {
                          "description": "Name of the relation",
                          "example": "tag_trees",
                          "type": "string"
                        }
                      },
                      "required": [
                        "href",
                        "rel"
                      ],
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "systemId": {
                    "description": "Unique internal id of the tag tree or tag tree item",
                    "example": 17,
                    "type": "integer"
                  },
                  "systemName": {
                    "description": "Unique name of the tag, tag tree or tag tree item",
                    "example": "LIVING_GROCERIES",
                    "type": "string"
                  },
                  "systemNameParent": {
                    "description": "Unique name of the parent of the tagTreeItem",
                    "example": "LIVING",
                    "type": "string"
                  },
                  "tagTree": {
                    "allOf": [
                      {
                        "example": {
                          "description": "Two level categorization tree.",
                          "displayName": "Kategorien",
                          "isClientGenerated": false,
                          "relations": [
                            {
                              "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/",
                              "rel": "self"
                            },
                            {
                              "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
                              "rel": "tag_trees"
                            },
                            {
                              "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/",
                              "rel": "tag_tree_items"
                            }
                          ],
                          "systemId": 1,
                          "systemName": "CATEGORIES",
                          "version": 3.7
                        },
                        "properties": {
                          "description": {
                            "description": "Gives a description of the tag tree",
                            "example": "Detailed inusrance categories.",
                            "type": "string"
                          },
                          "displayName": {
                            "description": "User-friendly name shown to the end-users",
                            "example": "Groceries",
                            "type": "string"
                          },
                          "isTenantGenerated": {
                            "description": "Boolean iflag, set TRUE if the tag was manually set",
                            "example": true,
                            "type": "boolean"
                          },
                          "relations": {
                            "description": "List of relations",
                            "items": {
                              "properties": {
                                "href": {
                                  "description": "Link of the relation",
                                  "example": "https://banksapi.io/.../tags/tag-trees/1/",
                                  "type": "string"
                                },
                                "rel": {
                                  "description": "Name of the relation",
                                  "example": "tag_trees",
                                  "type": "string"
                                }
                              },
                              "required": [
                                "href",
                                "rel"
                              ],
                              "type": "object"
                            },
                            "type": "array"
                          },
                          "systemId": {
                            "description": "Unique internal id of the tag tree or tag tree item",
                            "example": 17,
                            "type": "integer"
                          },
                          "systemName": {
                            "description": "Unique name of the tag, tag tree or tag tree item",
                            "example": "LIVING_GROCERIES",
                            "type": "string"
                          },
                          "version": {
                            "description": "Version of the tag tree",
                            "example": 1.5,
                            "minimum": 0,
                            "type": "number"
                          }
                        },
                        "required": [
                          "displayName",
                          "isTenantGenerated",
                          "systemId",
                          "systemName",
                          "version"
                        ],
                        "type": "object"
                      }
                    ],
                    "description": "tagTree that the tagTreeItem belongs to"
                  },
                  "telephone": {
                    "description": "Telephone of the business partner",
                    "example": "+49 (0)89 121 408 82",
                    "type": "string"
                  },
                  "website": {
                    "description": "Website of the business partner",
                    "example": "www.banksapi.de",
                    "type": "string"
                  }
                },
                "required": [
                  "displayName",
                  "systemId",
                  "systemName",
                  "tagTree"
                ],
                "type": "object"
              },
              "total": {
                "description": "total amount",
                "example": "EXPENSES",
                "type": "string"
              }
            },
            "required": [
              "cashflow"
            ],
            "type": "object"
          },
          "type": "array"
        }
      },
      "type": "object"
    }
    
    

    Properties

    Name Type Required Restrictions Description
    predictions [cashflow_tag_instance_details_stats_preds_schema] false none cashflow predictions
    statistics [cashflow_tag_instance_details_stats_preds_schema] false none cashflow statistics

    cashflow_tag_instance_details_stats_preds_schema

    {
      "properties": {
        "cashflow": {
          "description": "cashflow amount in Euros",
          "example": -3420.58,
          "type": "number"
        },
        "tagTreeItem": {
          "example": {
            "description": "Transactions in the field of banking and finance",
            "displayName": "Bank und Finanzen",
            "relations": [
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/1/",
                "rel": "self"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
                "rel": "tag_trees"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/",
                "rel": "tag_tree"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/",
                "rel": "tag_tree_items"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/1/",
                "rel": "tag_tree_item"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/None/",
                "rel": "tag_tree_item_parent"
              }
            ],
            "systemId": 1,
            "systemName": "BANKFINANCE",
            "tagTree": {
              "description": "Two level categorization tree.",
              "displayName": "Kategorien",
              "isClientGenerated": false,
              "systemId": 1,
              "systemName": "CATEGORIES",
              "version": 3.7
            }
          },
          "properties": {
            "addressCity": {
              "description": "Address city of the business partner",
              "example": "München",
              "type": "string"
            },
            "addressCountry": {
              "description": "Address country of the business partner",
              "example": "Deutschland",
              "type": "string"
            },
            "addressStreet": {
              "description": "Address street incl. number of the business partner",
              "example": "Lyonel-Feininger-Straße 28",
              "type": "string"
            },
            "addressZip": {
              "description": "Address zip/postal code of the business partner",
              "example": " 80807",
              "type": "string"
            },
            "categories": {
              "description": "Categories the business partner belongs to.",
              "example": [
                "BANKFINANCE",
                "SERVICES",
                "SERVICES_PROFESSIONAL"
              ],
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "creditorId": {
              "description": "creditor id of the business partner",
              "example": "DEZZZ00000012345",
              "type": "string"
            },
            "description": {
              "description": "Gives a description of the tagTreeItem",
              "example": "Expenses from daily grocery purchases",
              "type": "string"
            },
            "displayName": {
              "description": "User-friendly name shown to the end-users",
              "example": "Groceries",
              "type": "string"
            },
            "group": {
              "description": "Group the business partner belongs to.",
              "example": "Finconomy AG",
              "type": "string"
            },
            "relations": {
              "description": "List of relations",
              "items": {
                "properties": {
                  "href": {
                    "description": "Link of the relation",
                    "example": "https://banksapi.io/.../tags/tag-trees/1/",
                    "type": "string"
                  },
                  "rel": {
                    "description": "Name of the relation",
                    "example": "tag_trees",
                    "type": "string"
                  }
                },
                "required": [
                  "href",
                  "rel"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "systemId": {
              "description": "Unique internal id of the tag tree or tag tree item",
              "example": 17,
              "type": "integer"
            },
            "systemName": {
              "description": "Unique name of the tag, tag tree or tag tree item",
              "example": "LIVING_GROCERIES",
              "type": "string"
            },
            "systemNameParent": {
              "description": "Unique name of the parent of the tagTreeItem",
              "example": "LIVING",
              "type": "string"
            },
            "tagTree": {
              "allOf": [
                {
                  "example": {
                    "description": "Two level categorization tree.",
                    "displayName": "Kategorien",
                    "isClientGenerated": false,
                    "relations": [
                      {
                        "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/",
                        "rel": "self"
                      },
                      {
                        "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
                        "rel": "tag_trees"
                      },
                      {
                        "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/",
                        "rel": "tag_tree_items"
                      }
                    ],
                    "systemId": 1,
                    "systemName": "CATEGORIES",
                    "version": 3.7
                  },
                  "properties": {
                    "description": {
                      "description": "Gives a description of the tag tree",
                      "example": "Detailed inusrance categories.",
                      "type": "string"
                    },
                    "displayName": {
                      "description": "User-friendly name shown to the end-users",
                      "example": "Groceries",
                      "type": "string"
                    },
                    "isTenantGenerated": {
                      "description": "Boolean iflag, set TRUE if the tag was manually set",
                      "example": true,
                      "type": "boolean"
                    },
                    "relations": {
                      "description": "List of relations",
                      "items": {
                        "properties": {
                          "href": {
                            "description": "Link of the relation",
                            "example": "https://banksapi.io/.../tags/tag-trees/1/",
                            "type": "string"
                          },
                          "rel": {
                            "description": "Name of the relation",
                            "example": "tag_trees",
                            "type": "string"
                          }
                        },
                        "required": [
                          "href",
                          "rel"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "systemId": {
                      "description": "Unique internal id of the tag tree or tag tree item",
                      "example": 17,
                      "type": "integer"
                    },
                    "systemName": {
                      "description": "Unique name of the tag, tag tree or tag tree item",
                      "example": "LIVING_GROCERIES",
                      "type": "string"
                    },
                    "version": {
                      "description": "Version of the tag tree",
                      "example": 1.5,
                      "minimum": 0,
                      "type": "number"
                    }
                  },
                  "required": [
                    "displayName",
                    "isTenantGenerated",
                    "systemId",
                    "systemName",
                    "version"
                  ],
                  "type": "object"
                }
              ],
              "description": "tagTree that the tagTreeItem belongs to"
            },
            "telephone": {
              "description": "Telephone of the business partner",
              "example": "+49 (0)89 121 408 82",
              "type": "string"
            },
            "website": {
              "description": "Website of the business partner",
              "example": "www.banksapi.de",
              "type": "string"
            }
          },
          "required": [
            "displayName",
            "systemId",
            "systemName",
            "tagTree"
          ],
          "type": "object"
        },
        "total": {
          "description": "total amount",
          "example": "EXPENSES",
          "type": "string"
        }
      },
      "required": [
        "cashflow"
      ],
      "type": "object"
    }
    
    

    Properties

    Name Type Required Restrictions Description
    cashflow number true none cashflow amount in Euros
    tagTreeItem tag_tree_item_schema false none none
    total string false none total amount

    cashflow_tag_instance_schema

    {
      "properties": {
        "details": {
          "properties": {
            "predictions": {
              "description": "cashflow predictions",
              "items": {
                "properties": {
                  "cashflow": {
                    "description": "cashflow amount in Euros",
                    "example": -3420.58,
                    "type": "number"
                  },
                  "tagTreeItem": {
                    "example": {
                      "description": "Transactions in the field of banking and finance",
                      "displayName": "Bank und Finanzen",
                      "relations": [
                        {
                          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/1/",
                          "rel": "self"
                        },
                        {
                          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
                          "rel": "tag_trees"
                        },
                        {
                          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/",
                          "rel": "tag_tree"
                        },
                        {
                          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/",
                          "rel": "tag_tree_items"
                        },
                        {
                          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/1/",
                          "rel": "tag_tree_item"
                        },
                        {
                          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/None/",
                          "rel": "tag_tree_item_parent"
                        }
                      ],
                      "systemId": 1,
                      "systemName": "BANKFINANCE",
                      "tagTree": {
                        "description": "Two level categorization tree.",
                        "displayName": "Kategorien",
                        "isClientGenerated": false,
                        "systemId": 1,
                        "systemName": "CATEGORIES",
                        "version": 3.7
                      }
                    },
                    "properties": {
                      "addressCity": {
                        "description": "Address city of the business partner",
                        "example": "München",
                        "type": "string"
                      },
                      "addressCountry": {
                        "description": "Address country of the business partner",
                        "example": "Deutschland",
                        "type": "string"
                      },
                      "addressStreet": {
                        "description": "Address street incl. number of the business partner",
                        "example": "Lyonel-Feininger-Straße 28",
                        "type": "string"
                      },
                      "addressZip": {
                        "description": "Address zip/postal code of the business partner",
                        "example": " 80807",
                        "type": "string"
                      },
                      "categories": {
                        "description": "Categories the business partner belongs to.",
                        "example": [
                          "BANKFINANCE",
                          "SERVICES",
                          "SERVICES_PROFESSIONAL"
                        ],
                        "items": {
                          "type": "string"
                        },
                        "type": "array"
                      },
                      "creditorId": {
                        "description": "creditor id of the business partner",
                        "example": "DEZZZ00000012345",
                        "type": "string"
                      },
                      "description": {
                        "description": "Gives a description of the tagTreeItem",
                        "example": "Expenses from daily grocery purchases",
                        "type": "string"
                      },
                      "displayName": {
                        "description": "User-friendly name shown to the end-users",
                        "example": "Groceries",
                        "type": "string"
                      },
                      "group": {
                        "description": "Group the business partner belongs to.",
                        "example": "Finconomy AG",
                        "type": "string"
                      },
                      "relations": {
                        "description": "List of relations",
                        "items": {
                          "properties": {
                            "href": {
                              "description": "Link of the relation",
                              "example": "https://banksapi.io/.../tags/tag-trees/1/",
                              "type": "string"
                            },
                            "rel": {
                              "description": "Name of the relation",
                              "example": "tag_trees",
                              "type": "string"
                            }
                          },
                          "required": [
                            "href",
                            "rel"
                          ],
                          "type": "object"
                        },
                        "type": "array"
                      },
                      "systemId": {
                        "description": "Unique internal id of the tag tree or tag tree item",
                        "example": 17,
                        "type": "integer"
                      },
                      "systemName": {
                        "description": "Unique name of the tag, tag tree or tag tree item",
                        "example": "LIVING_GROCERIES",
                        "type": "string"
                      },
                      "systemNameParent": {
                        "description": "Unique name of the parent of the tagTreeItem",
                        "example": "LIVING",
                        "type": "string"
                      },
                      "tagTree": {
                        "allOf": [
                          {
                            "example": {
                              "description": "Two level categorization tree.",
                              "displayName": "Kategorien",
                              "isClientGenerated": false,
                              "relations": [
                                {
                                  "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/",
                                  "rel": "self"
                                },
                                {
                                  "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
                                  "rel": "tag_trees"
                                },
                                {
                                  "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/",
                                  "rel": "tag_tree_items"
                                }
                              ],
                              "systemId": 1,
                              "systemName": "CATEGORIES",
                              "version": 3.7
                            },
                            "properties": {
                              "description": {
                                "description": "Gives a description of the tag tree",
                                "example": "Detailed inusrance categories.",
                                "type": "string"
                              },
                              "displayName": {
                                "description": "User-friendly name shown to the end-users",
                                "example": "Groceries",
                                "type": "string"
                              },
                              "isTenantGenerated": {
                                "description": "Boolean iflag, set TRUE if the tag was manually set",
                                "example": true,
                                "type": "boolean"
                              },
                              "relations": {
                                "description": "List of relations",
                                "items": {
                                  "properties": {
                                    "href": {
                                      "description": "Link of the relation",
                                      "example": "https://banksapi.io/.../tags/tag-trees/1/",
                                      "type": "string"
                                    },
                                    "rel": {
                                      "description": "Name of the relation",
                                      "example": "tag_trees",
                                      "type": "string"
                                    }
                                  },
                                  "required": [
                                    "href",
                                    "rel"
                                  ],
                                  "type": "object"
                                },
                                "type": "array"
                              },
                              "systemId": {
                                "description": "Unique internal id of the tag tree or tag tree item",
                                "example": 17,
                                "type": "integer"
                              },
                              "systemName": {
                                "description": "Unique name of the tag, tag tree or tag tree item",
                                "example": "LIVING_GROCERIES",
                                "type": "string"
                              },
                              "version": {
                                "description": "Version of the tag tree",
                                "example": 1.5,
                                "minimum": 0,
                                "type": "number"
                              }
                            },
                            "required": [
                              "displayName",
                              "isTenantGenerated",
                              "systemId",
                              "systemName",
                              "version"
                            ],
                            "type": "object"
                          }
                        ],
                        "description": "tagTree that the tagTreeItem belongs to"
                      },
                      "telephone": {
                        "description": "Telephone of the business partner",
                        "example": "+49 (0)89 121 408 82",
                        "type": "string"
                      },
                      "website": {
                        "description": "Website of the business partner",
                        "example": "www.banksapi.de",
                        "type": "string"
                      }
                    },
                    "required": [
                      "displayName",
                      "systemId",
                      "systemName",
                      "tagTree"
                    ],
                    "type": "object"
                  },
                  "total": {
                    "description": "total amount",
                    "example": "EXPENSES",
                    "type": "string"
                  }
                },
                "required": [
                  "cashflow"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "statistics": {
              "description": "cashflow statistics",
              "items": {
                "properties": {
                  "cashflow": {
                    "description": "cashflow amount in Euros",
                    "example": -3420.58,
                    "type": "number"
                  },
                  "tagTreeItem": {
                    "example": {
                      "description": "Transactions in the field of banking and finance",
                      "displayName": "Bank und Finanzen",
                      "relations": [
                        {
                          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/1/",
                          "rel": "self"
                        },
                        {
                          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
                          "rel": "tag_trees"
                        },
                        {
                          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/",
                          "rel": "tag_tree"
                        },
                        {
                          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/",
                          "rel": "tag_tree_items"
                        },
                        {
                          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/1/",
                          "rel": "tag_tree_item"
                        },
                        {
                          "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/None/",
                          "rel": "tag_tree_item_parent"
                        }
                      ],
                      "systemId": 1,
                      "systemName": "BANKFINANCE",
                      "tagTree": {
                        "description": "Two level categorization tree.",
                        "displayName": "Kategorien",
                        "isClientGenerated": false,
                        "systemId": 1,
                        "systemName": "CATEGORIES",
                        "version": 3.7
                      }
                    },
                    "properties": {
                      "addressCity": {
                        "description": "Address city of the business partner",
                        "example": "München",
                        "type": "string"
                      },
                      "addressCountry": {
                        "description": "Address country of the business partner",
                        "example": "Deutschland",
                        "type": "string"
                      },
                      "addressStreet": {
                        "description": "Address street incl. number of the business partner",
                        "example": "Lyonel-Feininger-Straße 28",
                        "type": "string"
                      },
                      "addressZip": {
                        "description": "Address zip/postal code of the business partner",
                        "example": " 80807",
                        "type": "string"
                      },
                      "categories": {
                        "description": "Categories the business partner belongs to.",
                        "example": [
                          "BANKFINANCE",
                          "SERVICES",
                          "SERVICES_PROFESSIONAL"
                        ],
                        "items": {
                          "type": "string"
                        },
                        "type": "array"
                      },
                      "creditorId": {
                        "description": "creditor id of the business partner",
                        "example": "DEZZZ00000012345",
                        "type": "string"
                      },
                      "description": {
                        "description": "Gives a description of the tagTreeItem",
                        "example": "Expenses from daily grocery purchases",
                        "type": "string"
                      },
                      "displayName": {
                        "description": "User-friendly name shown to the end-users",
                        "example": "Groceries",
                        "type": "string"
                      },
                      "group": {
                        "description": "Group the business partner belongs to.",
                        "example": "Finconomy AG",
                        "type": "string"
                      },
                      "relations": {
                        "description": "List of relations",
                        "items": {
                          "properties": {
                            "href": {
                              "description": "Link of the relation",
                              "example": "https://banksapi.io/.../tags/tag-trees/1/",
                              "type": "string"
                            },
                            "rel": {
                              "description": "Name of the relation",
                              "example": "tag_trees",
                              "type": "string"
                            }
                          },
                          "required": [
                            "href",
                            "rel"
                          ],
                          "type": "object"
                        },
                        "type": "array"
                      },
                      "systemId": {
                        "description": "Unique internal id of the tag tree or tag tree item",
                        "example": 17,
                        "type": "integer"
                      },
                      "systemName": {
                        "description": "Unique name of the tag, tag tree or tag tree item",
                        "example": "LIVING_GROCERIES",
                        "type": "string"
                      },
                      "systemNameParent": {
                        "description": "Unique name of the parent of the tagTreeItem",
                        "example": "LIVING",
                        "type": "string"
                      },
                      "tagTree": {
                        "allOf": [
                          {
                            "example": {
                              "description": "Two level categorization tree.",
                              "displayName": "Kategorien",
                              "isClientGenerated": false,
                              "relations": [
                                {
                                  "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/",
                                  "rel": "self"
                                },
                                {
                                  "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
                                  "rel": "tag_trees"
                                },
                                {
                                  "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/",
                                  "rel": "tag_tree_items"
                                }
                              ],
                              "systemId": 1,
                              "systemName": "CATEGORIES",
                              "version": 3.7
                            },
                            "properties": {
                              "description": {
                                "description": "Gives a description of the tag tree",
                                "example": "Detailed inusrance categories.",
                                "type": "string"
                              },
                              "displayName": {
                                "description": "User-friendly name shown to the end-users",
                                "example": "Groceries",
                                "type": "string"
                              },
                              "isTenantGenerated": {
                                "description": "Boolean iflag, set TRUE if the tag was manually set",
                                "example": true,
                                "type": "boolean"
                              },
                              "relations": {
                                "description": "List of relations",
                                "items": {
                                  "properties": {
                                    "href": {
                                      "description": "Link of the relation",
                                      "example": "https://banksapi.io/.../tags/tag-trees/1/",
                                      "type": "string"
                                    },
                                    "rel": {
                                      "description": "Name of the relation",
                                      "example": "tag_trees",
                                      "type": "string"
                                    }
                                  },
                                  "required": [
                                    "href",
                                    "rel"
                                  ],
                                  "type": "object"
                                },
                                "type": "array"
                              },
                              "systemId": {
                                "description": "Unique internal id of the tag tree or tag tree item",
                                "example": 17,
                                "type": "integer"
                              },
                              "systemName": {
                                "description": "Unique name of the tag, tag tree or tag tree item",
                                "example": "LIVING_GROCERIES",
                                "type": "string"
                              },
                              "version": {
                                "description": "Version of the tag tree",
                                "example": 1.5,
                                "minimum": 0,
                                "type": "number"
                              }
                            },
                            "required": [
                              "displayName",
                              "isTenantGenerated",
                              "systemId",
                              "systemName",
                              "version"
                            ],
                            "type": "object"
                          }
                        ],
                        "description": "tagTree that the tagTreeItem belongs to"
                      },
                      "telephone": {
                        "description": "Telephone of the business partner",
                        "example": "+49 (0)89 121 408 82",
                        "type": "string"
                      },
                      "website": {
                        "description": "Website of the business partner",
                        "example": "www.banksapi.de",
                        "type": "string"
                      }
                    },
                    "required": [
                      "displayName",
                      "systemId",
                      "systemName",
                      "tagTree"
                    ],
                    "type": "object"
                  },
                  "total": {
                    "description": "total amount",
                    "example": "EXPENSES",
                    "type": "string"
                  }
                },
                "required": [
                  "cashflow"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "type": "object"
        },
        "entity": {
          "properties": {
            "accountId": {
              "description": "Tenant generated Account id for TRANSACTIONs, empty for USER",
              "example": "b56ca508-c0e2-52c5-3202-8de20e7ed12b",
              "type": "string"
            },
            "displayName": {
              "description": "Display name of the entity",
              "example": "TRANSACTION",
              "type": "string"
            },
            "entityClass": {
              "description": "Class of the entity, such as TRANSACTION or USER",
              "example": "TRANSACTION",
              "type": "string"
            },
            "id": {
              "description": "Transaction UUID or USER UUID.",
              "example": "156ca508-c0e2-52c5-3202-8de20e7ed12b",
              "type": "string"
            },
            "userId": {
              "description": "UUID of the USER. Same as id field for USER entities.",
              "example": "156ca508-c0e2-52c5-3202-8de20e7ed12b",
              "type": "string"
            }
          },
          "required": [
            "displayName",
            "entityClass",
            "id"
          ],
          "type": "object"
        },
        "id": {
          "description": "Unique Universal Identifier (UUID)",
          "example": "956ca508-c0e2-52c5-3202-8de20e7ed12b",
          "type": "string"
        },
        "relations": {
          "description": "List of relations",
          "items": {
            "properties": {
              "href": {
                "description": "Link of the relation",
                "example": "https://banksapi.io/.../tags/tag-trees/1/",
                "type": "string"
              },
              "rel": {
                "description": "Name of the relation",
                "example": "tag_trees",
                "type": "string"
              }
            },
            "required": [
              "href",
              "rel"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "tagTreeItem": {
          "example": {
            "description": "Transactions in the field of banking and finance",
            "displayName": "Bank und Finanzen",
            "relations": [
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/1/",
                "rel": "self"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
                "rel": "tag_trees"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/",
                "rel": "tag_tree"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/",
                "rel": "tag_tree_items"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/1/",
                "rel": "tag_tree_item"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/None/",
                "rel": "tag_tree_item_parent"
              }
            ],
            "systemId": 1,
            "systemName": "BANKFINANCE",
            "tagTree": {
              "description": "Two level categorization tree.",
              "displayName": "Kategorien",
              "isClientGenerated": false,
              "systemId": 1,
              "systemName": "CATEGORIES",
              "version": 3.7
            }
          },
          "properties": {
            "addressCity": {
              "description": "Address city of the business partner",
              "example": "München",
              "type": "string"
            },
            "addressCountry": {
              "description": "Address country of the business partner",
              "example": "Deutschland",
              "type": "string"
            },
            "addressStreet": {
              "description": "Address street incl. number of the business partner",
              "example": "Lyonel-Feininger-Straße 28",
              "type": "string"
            },
            "addressZip": {
              "description": "Address zip/postal code of the business partner",
              "example": " 80807",
              "type": "string"
            },
            "categories": {
              "description": "Categories the business partner belongs to.",
              "example": [
                "BANKFINANCE",
                "SERVICES",
                "SERVICES_PROFESSIONAL"
              ],
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "creditorId": {
              "description": "creditor id of the business partner",
              "example": "DEZZZ00000012345",
              "type": "string"
            },
            "description": {
              "description": "Gives a description of the tagTreeItem",
              "example": "Expenses from daily grocery purchases",
              "type": "string"
            },
            "displayName": {
              "description": "User-friendly name shown to the end-users",
              "example": "Groceries",
              "type": "string"
            },
            "group": {
              "description": "Group the business partner belongs to.",
              "example": "Finconomy AG",
              "type": "string"
            },
            "relations": {
              "description": "List of relations",
              "items": {
                "properties": {
                  "href": {
                    "description": "Link of the relation",
                    "example": "https://banksapi.io/.../tags/tag-trees/1/",
                    "type": "string"
                  },
                  "rel": {
                    "description": "Name of the relation",
                    "example": "tag_trees",
                    "type": "string"
                  }
                },
                "required": [
                  "href",
                  "rel"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "systemId": {
              "description": "Unique internal id of the tag tree or tag tree item",
              "example": 17,
              "type": "integer"
            },
            "systemName": {
              "description": "Unique name of the tag, tag tree or tag tree item",
              "example": "LIVING_GROCERIES",
              "type": "string"
            },
            "systemNameParent": {
              "description": "Unique name of the parent of the tagTreeItem",
              "example": "LIVING",
              "type": "string"
            },
            "tagTree": {
              "allOf": [
                {
                  "example": {
                    "description": "Two level categorization tree.",
                    "displayName": "Kategorien",
                    "isClientGenerated": false,
                    "relations": [
                      {
                        "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/",
                        "rel": "self"
                      },
                      {
                        "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
                        "rel": "tag_trees"
                      },
                      {
                        "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/",
                        "rel": "tag_tree_items"
                      }
                    ],
                    "systemId": 1,
                    "systemName": "CATEGORIES",
                    "version": 3.7
                  },
                  "properties": {
                    "description": {
                      "description": "Gives a description of the tag tree",
                      "example": "Detailed inusrance categories.",
                      "type": "string"
                    },
                    "displayName": {
                      "description": "User-friendly name shown to the end-users",
                      "example": "Groceries",
                      "type": "string"
                    },
                    "isTenantGenerated": {
                      "description": "Boolean iflag, set TRUE if the tag was manually set",
                      "example": true,
                      "type": "boolean"
                    },
                    "relations": {
                      "description": "List of relations",
                      "items": {
                        "properties": {
                          "href": {
                            "description": "Link of the relation",
                            "example": "https://banksapi.io/.../tags/tag-trees/1/",
                            "type": "string"
                          },
                          "rel": {
                            "description": "Name of the relation",
                            "example": "tag_trees",
                            "type": "string"
                          }
                        },
                        "required": [
                          "href",
                          "rel"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "systemId": {
                      "description": "Unique internal id of the tag tree or tag tree item",
                      "example": 17,
                      "type": "integer"
                    },
                    "systemName": {
                      "description": "Unique name of the tag, tag tree or tag tree item",
                      "example": "LIVING_GROCERIES",
                      "type": "string"
                    },
                    "version": {
                      "description": "Version of the tag tree",
                      "example": 1.5,
                      "minimum": 0,
                      "type": "number"
                    }
                  },
                  "required": [
                    "displayName",
                    "isTenantGenerated",
                    "systemId",
                    "systemName",
                    "version"
                  ],
                  "type": "object"
                }
              ],
              "description": "tagTree that the tagTreeItem belongs to"
            },
            "telephone": {
              "description": "Telephone of the business partner",
              "example": "+49 (0)89 121 408 82",
              "type": "string"
            },
            "website": {
              "description": "Website of the business partner",
              "example": "www.banksapi.de",
              "type": "string"
            }
          },
          "required": [
            "displayName",
            "systemId",
            "systemName",
            "tagTree"
          ],
          "type": "object"
        }
      },
      "required": [
        "entity",
        "id",
        "tagTreeItem"
      ],
      "type": "object"
    }
    
    

    Properties

    Name Type Required Restrictions Description
    details cashflow_tag_instance_details_schema false none none
    entity entity_schema true none none
    id string true none Unique Universal Identifier (UUID)
    relations [relation_schema] false none List of relations
    tagTreeItem tag_tree_item_schema true none none

    categorization_tag_instance_details_schema

    {
      "properties": {
        "confidenceLevel": {
          "description": "Confidence level between 0 and 1",
          "example": 0.94,
          "maximum": 1,
          "minimum": 0,
          "type": "number"
        }
      },
      "type": "object"
    }
    
    

    Properties

    Name Type Required Restrictions Description
    confidenceLevel number false none Confidence level between 0 and 1

    categorization_tag_instance_schema

    {
      "properties": {
        "details": {
          "properties": {
            "confidenceLevel": {
              "description": "Confidence level between 0 and 1",
              "example": 0.94,
              "maximum": 1,
              "minimum": 0,
              "type": "number"
            }
          },
          "type": "object"
        },
        "entity": {
          "properties": {
            "accountId": {
              "description": "Tenant generated Account id for TRANSACTIONs, empty for USER",
              "example": "b56ca508-c0e2-52c5-3202-8de20e7ed12b",
              "type": "string"
            },
            "displayName": {
              "description": "Display name of the entity",
              "example": "TRANSACTION",
              "type": "string"
            },
            "entityClass": {
              "description": "Class of the entity, such as TRANSACTION or USER",
              "example": "TRANSACTION",
              "type": "string"
            },
            "id": {
              "description": "Transaction UUID or USER UUID.",
              "example": "156ca508-c0e2-52c5-3202-8de20e7ed12b",
              "type": "string"
            },
            "userId": {
              "description": "UUID of the USER. Same as id field for USER entities.",
              "example": "156ca508-c0e2-52c5-3202-8de20e7ed12b",
              "type": "string"
            }
          },
          "required": [
            "displayName",
            "entityClass",
            "id"
          ],
          "type": "object"
        },
        "id": {
          "description": "Unique Universal Identifier (UUID)",
          "example": "956ca508-c0e2-52c5-3202-8de20e7ed12b",
          "type": "string"
        },
        "relations": {
          "description": "List of relations",
          "items": {
            "properties": {
              "href": {
                "description": "Link of the relation",
                "example": "https://banksapi.io/.../tags/tag-trees/1/",
                "type": "string"
              },
              "rel": {
                "description": "Name of the relation",
                "example": "tag_trees",
                "type": "string"
              }
            },
            "required": [
              "href",
              "rel"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "tagTreeItem": {
          "example": {
            "description": "Transactions in the field of banking and finance",
            "displayName": "Bank und Finanzen",
            "relations": [
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/1/",
                "rel": "self"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
                "rel": "tag_trees"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/",
                "rel": "tag_tree"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/",
                "rel": "tag_tree_items"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/1/",
                "rel": "tag_tree_item"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/None/",
                "rel": "tag_tree_item_parent"
              }
            ],
            "systemId": 1,
            "systemName": "BANKFINANCE",
            "tagTree": {
              "description": "Two level categorization tree.",
              "displayName": "Kategorien",
              "isClientGenerated": false,
              "systemId": 1,
              "systemName": "CATEGORIES",
              "version": 3.7
            }
          },
          "properties": {
            "addressCity": {
              "description": "Address city of the business partner",
              "example": "München",
              "type": "string"
            },
            "addressCountry": {
              "description": "Address country of the business partner",
              "example": "Deutschland",
              "type": "string"
            },
            "addressStreet": {
              "description": "Address street incl. number of the business partner",
              "example": "Lyonel-Feininger-Straße 28",
              "type": "string"
            },
            "addressZip": {
              "description": "Address zip/postal code of the business partner",
              "example": " 80807",
              "type": "string"
            },
            "categories": {
              "description": "Categories the business partner belongs to.",
              "example": [
                "BANKFINANCE",
                "SERVICES",
                "SERVICES_PROFESSIONAL"
              ],
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "creditorId": {
              "description": "creditor id of the business partner",
              "example": "DEZZZ00000012345",
              "type": "string"
            },
            "description": {
              "description": "Gives a description of the tagTreeItem",
              "example": "Expenses from daily grocery purchases",
              "type": "string"
            },
            "displayName": {
              "description": "User-friendly name shown to the end-users",
              "example": "Groceries",
              "type": "string"
            },
            "group": {
              "description": "Group the business partner belongs to.",
              "example": "Finconomy AG",
              "type": "string"
            },
            "relations": {
              "description": "List of relations",
              "items": {
                "properties": {
                  "href": {
                    "description": "Link of the relation",
                    "example": "https://banksapi.io/.../tags/tag-trees/1/",
                    "type": "string"
                  },
                  "rel": {
                    "description": "Name of the relation",
                    "example": "tag_trees",
                    "type": "string"
                  }
                },
                "required": [
                  "href",
                  "rel"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "systemId": {
              "description": "Unique internal id of the tag tree or tag tree item",
              "example": 17,
              "type": "integer"
            },
            "systemName": {
              "description": "Unique name of the tag, tag tree or tag tree item",
              "example": "LIVING_GROCERIES",
              "type": "string"
            },
            "systemNameParent": {
              "description": "Unique name of the parent of the tagTreeItem",
              "example": "LIVING",
              "type": "string"
            },
            "tagTree": {
              "allOf": [
                {
                  "example": {
                    "description": "Two level categorization tree.",
                    "displayName": "Kategorien",
                    "isClientGenerated": false,
                    "relations": [
                      {
                        "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/",
                        "rel": "self"
                      },
                      {
                        "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
                        "rel": "tag_trees"
                      },
                      {
                        "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/",
                        "rel": "tag_tree_items"
                      }
                    ],
                    "systemId": 1,
                    "systemName": "CATEGORIES",
                    "version": 3.7
                  },
                  "properties": {
                    "description": {
                      "description": "Gives a description of the tag tree",
                      "example": "Detailed inusrance categories.",
                      "type": "string"
                    },
                    "displayName": {
                      "description": "User-friendly name shown to the end-users",
                      "example": "Groceries",
                      "type": "string"
                    },
                    "isTenantGenerated": {
                      "description": "Boolean iflag, set TRUE if the tag was manually set",
                      "example": true,
                      "type": "boolean"
                    },
                    "relations": {
                      "description": "List of relations",
                      "items": {
                        "properties": {
                          "href": {
                            "description": "Link of the relation",
                            "example": "https://banksapi.io/.../tags/tag-trees/1/",
                            "type": "string"
                          },
                          "rel": {
                            "description": "Name of the relation",
                            "example": "tag_trees",
                            "type": "string"
                          }
                        },
                        "required": [
                          "href",
                          "rel"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "systemId": {
                      "description": "Unique internal id of the tag tree or tag tree item",
                      "example": 17,
                      "type": "integer"
                    },
                    "systemName": {
                      "description": "Unique name of the tag, tag tree or tag tree item",
                      "example": "LIVING_GROCERIES",
                      "type": "string"
                    },
                    "version": {
                      "description": "Version of the tag tree",
                      "example": 1.5,
                      "minimum": 0,
                      "type": "number"
                    }
                  },
                  "required": [
                    "displayName",
                    "isTenantGenerated",
                    "systemId",
                    "systemName",
                    "version"
                  ],
                  "type": "object"
                }
              ],
              "description": "tagTree that the tagTreeItem belongs to"
            },
            "telephone": {
              "description": "Telephone of the business partner",
              "example": "+49 (0)89 121 408 82",
              "type": "string"
            },
            "website": {
              "description": "Website of the business partner",
              "example": "www.banksapi.de",
              "type": "string"
            }
          },
          "required": [
            "displayName",
            "systemId",
            "systemName",
            "tagTree"
          ],
          "type": "object"
        }
      },
      "required": [
        "entity",
        "id",
        "tagTreeItem"
      ],
      "type": "object"
    }
    
    

    Properties

    Name Type Required Restrictions Description
    details categorization_tag_instance_details_schema false none none
    entity entity_schema true none none
    id string true none Unique Universal Identifier (UUID)
    relations [relation_schema] false none List of relations
    tagTreeItem tag_tree_item_schema true none none

    contract_tag_instance_details_schema

    {
      "properties": {
        "amountFirst": {
          "description": "First payment among contract payments",
          "example": "12.34",
          "type": "number"
        },
        "amountLatest": {
          "description": "Most recent payment among contract payments",
          "example": "21.01",
          "type": "number"
        },
        "amountMaximum": {
          "description": "Maximum payment among contract payments",
          "example": "23.23",
          "type": "number"
        },
        "amountMean": {
          "description": "Mean payment among contract payments",
          "example": "21.35",
          "type": "number"
        },
        "amountMinimum": {
          "description": "Minimum payment among contract payments",
          "example": "19.34",
          "type": "number"
        },
        "amountNext": {
          "description": "Predicted next payment based on contract payments",
          "example": "22.01",
          "type": "number"
        },
        "amountTotal": {
          "description": "Total amount paid to the contract",
          "example": "2345.23",
          "type": "number"
        },
        "contractNumbers": {
          "description": "List of detected contract numbers",
          "example": [
            "334112312",
            "334112313"
          ],
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "costDevelopment": {
          "description": "Payment history",
          "example": {
            "2017-04-03": 103.93,
            "2017-04-30": 103.46
          },
          "type": "object"
        },
        "counterpartyBic": {
          "description": "BIC of the counterparty",
          "example": "PBNKDEFF",
          "type": "string"
        },
        "counterpartyIban": {
          "description": "IBAN of the counterparty",
          "example": "DE75512108001245126199",
          "type": "string"
        },
        "counterpartyName": {
          "description": "Name of the counterparty copied from a transaction, without any modification",
          "example": "Allianz Versicherungen",
          "type": "string"
        },
        "creditAmount": {
          "description": "Net amount of the loan being paid back with the contract",
          "example": "2345.23",
          "type": "number"
        },
        "creditAmountGross": {
          "description": "Total amount of the loan being paid back with the contract including additional costs",
          "example": "2345.23",
          "type": "number"
        },
        "customName": {
          "description": "If there is no listed business partner found, a custom name is tried to be extracted from the transaction.",
          "example": "Allianz",
          "type": "string"
        },
        "customerNumbers": {
          "description": "List of detected customer numbers",
          "example": [
            "K1000452"
          ],
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "dateEnd": {
          "description": "Contract end date",
          "example": "2019-04-03",
          "format": "date",
          "type": "string"
        },
        "dateFirst": {
          "description": "Date of the first payment",
          "example": "2017-04-03",
          "format": "date",
          "type": "string"
        },
        "dateLatest": {
          "description": "Date of the last payment",
          "example": "2019-04-03",
          "format": "date",
          "type": "string"
        },
        "dateNext": {
          "description": "Predicted date of the next payment",
          "example": "2019-05-03",
          "format": "date",
          "type": "string"
        },
        "dateStart": {
          "description": "Contract start date",
          "example": "2017-04-03",
          "format": "date",
          "type": "string"
        },
        "daysAge": {
          "description": "Age of the contract in days",
          "example": "12",
          "type": "integer"
        },
        "growthRate": {
          "description": "Procentual growth rate per period",
          "example": "4.34",
          "type": "number"
        },
        "interestRate": {
          "description": "Effective annual interest rate estimated for this contract",
          "example": "0.04",
          "type": "number"
        },
        "interestRateNominal": {
          "description": "Nominal annual interest rate detected for this contract",
          "example": "0.04",
          "type": "number"
        },
        "numberContract": {
          "description": "Contract number",
          "example": "0003412312",
          "type": "string"
        },
        "numberCustomer": {
          "description": "Customer number",
          "example": "123412312",
          "type": "string"
        },
        "standardDeviation": {
          "description": "Standard deviation of contract payments",
          "example": "0.23",
          "type": "number"
        },
        "status": {
          "description": "Status of contract (ACTIVE or NOT_ACTIVE)",
          "example": "NOT_ACTIVE",
          "type": "string"
        },
        "transactionIds": {
          "description": "List of transaction ids",
          "example": [
            "956ca508-c0e2-52c5-3202-8de20e7ed12b",
            "123ab456-a1b2-98o1-4321-5mn3b2v103bl"
          ],
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "amountFirst",
        "amountLatest",
        "amountMaximum",
        "amountMean",
        "amountMinimum",
        "amountTotal",
        "contractNumbers",
        "costDevelopment",
        "customerNumbers",
        "dateFirst",
        "dateLatest",
        "daysAge",
        "status",
        "transactionIds"
      ],
      "type": "object"
    }
    
    

    Properties

    Name Type Required Restrictions Description
    amountFirst number true none First payment among contract payments
    amountLatest number true none Most recent payment among contract payments
    amountMaximum number true none Maximum payment among contract payments
    amountMean number true none Mean payment among contract payments
    amountMinimum number true none Minimum payment among contract payments
    amountNext number false none Predicted next payment based on contract payments
    amountTotal number true none Total amount paid to the contract
    contractNumbers [string] true none List of detected contract numbers
    costDevelopment object true none Payment history
    counterpartyBic string false none BIC of the counterparty
    counterpartyIban string false none IBAN of the counterparty
    counterpartyName string false none Name of the counterparty copied from a transaction, without any modification
    creditAmount number false none Net amount of the loan being paid back with the contract
    creditAmountGross number false none Total amount of the loan being paid back with the contract including additional costs
    customName string false none If there is no listed business partner found, a custom name is tried to be extracted from the transaction.
    customerNumbers [string] true none List of detected customer numbers
    dateEnd string(date) false none Contract end date
    dateFirst string(date) true none Date of the first payment
    dateLatest string(date) true none Date of the last payment
    dateNext string(date) false none Predicted date of the next payment
    dateStart string(date) false none Contract start date
    daysAge integer true none Age of the contract in days
    growthRate number false none Procentual growth rate per period
    interestRate number false none Effective annual interest rate estimated for this contract
    interestRateNominal number false none Nominal annual interest rate detected for this contract
    numberContract string false none Contract number
    numberCustomer string false none Customer number
    standardDeviation number false none Standard deviation of contract payments
    status string true none Status of contract (ACTIVE or NOT_ACTIVE)
    transactionIds [string] true none List of transaction ids

    contract_tag_instance_schema

    {
      "properties": {
        "details": {
          "properties": {
            "amountFirst": {
              "description": "First payment among contract payments",
              "example": "12.34",
              "type": "number"
            },
            "amountLatest": {
              "description": "Most recent payment among contract payments",
              "example": "21.01",
              "type": "number"
            },
            "amountMaximum": {
              "description": "Maximum payment among contract payments",
              "example": "23.23",
              "type": "number"
            },
            "amountMean": {
              "description": "Mean payment among contract payments",
              "example": "21.35",
              "type": "number"
            },
            "amountMinimum": {
              "description": "Minimum payment among contract payments",
              "example": "19.34",
              "type": "number"
            },
            "amountNext": {
              "description": "Predicted next payment based on contract payments",
              "example": "22.01",
              "type": "number"
            },
            "amountTotal": {
              "description": "Total amount paid to the contract",
              "example": "2345.23",
              "type": "number"
            },
            "contractNumbers": {
              "description": "List of detected contract numbers",
              "example": [
                "334112312",
                "334112313"
              ],
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "costDevelopment": {
              "description": "Payment history",
              "example": {
                "2017-04-03": 103.93,
                "2017-04-30": 103.46
              },
              "type": "object"
            },
            "counterpartyBic": {
              "description": "BIC of the counterparty",
              "example": "PBNKDEFF",
              "type": "string"
            },
            "counterpartyIban": {
              "description": "IBAN of the counterparty",
              "example": "DE75512108001245126199",
              "type": "string"
            },
            "counterpartyName": {
              "description": "Name of the counterparty copied from a transaction, without any modification",
              "example": "Allianz Versicherungen",
              "type": "string"
            },
            "creditAmount": {
              "description": "Net amount of the loan being paid back with the contract",
              "example": "2345.23",
              "type": "number"
            },
            "creditAmountGross": {
              "description": "Total amount of the loan being paid back with the contract including additional costs",
              "example": "2345.23",
              "type": "number"
            },
            "customName": {
              "description": "If there is no listed business partner found, a custom name is tried to be extracted from the transaction.",
              "example": "Allianz",
              "type": "string"
            },
            "customerNumbers": {
              "description": "List of detected customer numbers",
              "example": [
                "K1000452"
              ],
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "dateEnd": {
              "description": "Contract end date",
              "example": "2019-04-03",
              "format": "date",
              "type": "string"
            },
            "dateFirst": {
              "description": "Date of the first payment",
              "example": "2017-04-03",
              "format": "date",
              "type": "string"
            },
            "dateLatest": {
              "description": "Date of the last payment",
              "example": "2019-04-03",
              "format": "date",
              "type": "string"
            },
            "dateNext": {
              "description": "Predicted date of the next payment",
              "example": "2019-05-03",
              "format": "date",
              "type": "string"
            },
            "dateStart": {
              "description": "Contract start date",
              "example": "2017-04-03",
              "format": "date",
              "type": "string"
            },
            "daysAge": {
              "description": "Age of the contract in days",
              "example": "12",
              "type": "integer"
            },
            "growthRate": {
              "description": "Procentual growth rate per period",
              "example": "4.34",
              "type": "number"
            },
            "interestRate": {
              "description": "Effective annual interest rate estimated for this contract",
              "example": "0.04",
              "type": "number"
            },
            "interestRateNominal": {
              "description": "Nominal annual interest rate detected for this contract",
              "example": "0.04",
              "type": "number"
            },
            "numberContract": {
              "description": "Contract number",
              "example": "0003412312",
              "type": "string"
            },
            "numberCustomer": {
              "description": "Customer number",
              "example": "123412312",
              "type": "string"
            },
            "standardDeviation": {
              "description": "Standard deviation of contract payments",
              "example": "0.23",
              "type": "number"
            },
            "status": {
              "description": "Status of contract (ACTIVE or NOT_ACTIVE)",
              "example": "NOT_ACTIVE",
              "type": "string"
            },
            "transactionIds": {
              "description": "List of transaction ids",
              "example": [
                "956ca508-c0e2-52c5-3202-8de20e7ed12b",
                "123ab456-a1b2-98o1-4321-5mn3b2v103bl"
              ],
              "items": {
                "type": "string"
              },
              "type": "array"
            }
          },
          "required": [
            "amountFirst",
            "amountLatest",
            "amountMaximum",
            "amountMean",
            "amountMinimum",
            "amountTotal",
            "contractNumbers",
            "costDevelopment",
            "customerNumbers",
            "dateFirst",
            "dateLatest",
            "daysAge",
            "status",
            "transactionIds"
          ],
          "type": "object"
        },
        "entity": {
          "properties": {
            "accountId": {
              "description": "Tenant generated Account id for TRANSACTIONs, empty for USER",
              "example": "b56ca508-c0e2-52c5-3202-8de20e7ed12b",
              "type": "string"
            },
            "displayName": {
              "description": "Display name of the entity",
              "example": "TRANSACTION",
              "type": "string"
            },
            "entityClass": {
              "description": "Class of the entity, such as TRANSACTION or USER",
              "example": "TRANSACTION",
              "type": "string"
            },
            "id": {
              "description": "Transaction UUID or USER UUID.",
              "example": "156ca508-c0e2-52c5-3202-8de20e7ed12b",
              "type": "string"
            },
            "userId": {
              "description": "UUID of the USER. Same as id field for USER entities.",
              "example": "156ca508-c0e2-52c5-3202-8de20e7ed12b",
              "type": "string"
            }
          },
          "required": [
            "displayName",
            "entityClass",
            "id"
          ],
          "type": "object"
        },
        "id": {
          "description": "Unique Universal Identifier (UUID)",
          "example": "956ca508-c0e2-52c5-3202-8de20e7ed12b",
          "type": "string"
        },
        "relations": {
          "description": "List of relations",
          "items": {
            "properties": {
              "href": {
                "description": "Link of the relation",
                "example": "https://banksapi.io/.../tags/tag-trees/1/",
                "type": "string"
              },
              "rel": {
                "description": "Name of the relation",
                "example": "tag_trees",
                "type": "string"
              }
            },
            "required": [
              "href",
              "rel"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "tagTreeItemBusinessPartner": {
          "example": {
            "description": "Transactions in the field of banking and finance",
            "displayName": "Bank und Finanzen",
            "relations": [
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/1/",
                "rel": "self"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
                "rel": "tag_trees"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/",
                "rel": "tag_tree"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/",
                "rel": "tag_tree_items"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/1/",
                "rel": "tag_tree_item"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/None/",
                "rel": "tag_tree_item_parent"
              }
            ],
            "systemId": 1,
            "systemName": "BANKFINANCE",
            "tagTree": {
              "description": "Two level categorization tree.",
              "displayName": "Kategorien",
              "isClientGenerated": false,
              "systemId": 1,
              "systemName": "CATEGORIES",
              "version": 3.7
            }
          },
          "properties": {
            "addressCity": {
              "description": "Address city of the business partner",
              "example": "München",
              "type": "string"
            },
            "addressCountry": {
              "description": "Address country of the business partner",
              "example": "Deutschland",
              "type": "string"
            },
            "addressStreet": {
              "description": "Address street incl. number of the business partner",
              "example": "Lyonel-Feininger-Straße 28",
              "type": "string"
            },
            "addressZip": {
              "description": "Address zip/postal code of the business partner",
              "example": " 80807",
              "type": "string"
            },
            "categories": {
              "description": "Categories the business partner belongs to.",
              "example": [
                "BANKFINANCE",
                "SERVICES",
                "SERVICES_PROFESSIONAL"
              ],
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "creditorId": {
              "description": "creditor id of the business partner",
              "example": "DEZZZ00000012345",
              "type": "string"
            },
            "description": {
              "description": "Gives a description of the tagTreeItem",
              "example": "Expenses from daily grocery purchases",
              "type": "string"
            },
            "displayName": {
              "description": "User-friendly name shown to the end-users",
              "example": "Groceries",
              "type": "string"
            },
            "group": {
              "description": "Group the business partner belongs to.",
              "example": "Finconomy AG",
              "type": "string"
            },
            "relations": {
              "description": "List of relations",
              "items": {
                "properties": {
                  "href": {
                    "description": "Link of the relation",
                    "example": "https://banksapi.io/.../tags/tag-trees/1/",
                    "type": "string"
                  },
                  "rel": {
                    "description": "Name of the relation",
                    "example": "tag_trees",
                    "type": "string"
                  }
                },
                "required": [
                  "href",
                  "rel"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "systemId": {
              "description": "Unique internal id of the tag tree or tag tree item",
              "example": 17,
              "type": "integer"
            },
            "systemName": {
              "description": "Unique name of the tag, tag tree or tag tree item",
              "example": "LIVING_GROCERIES",
              "type": "string"
            },
            "systemNameParent": {
              "description": "Unique name of the parent of the tagTreeItem",
              "example": "LIVING",
              "type": "string"
            },
            "tagTree": {
              "allOf": [
                {
                  "example": {
                    "description": "Two level categorization tree.",
                    "displayName": "Kategorien",
                    "isClientGenerated": false,
                    "relations": [
                      {
                        "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/",
                        "rel": "self"
                      },
                      {
                        "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
                        "rel": "tag_trees"
                      },
                      {
                        "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/",
                        "rel": "tag_tree_items"
                      }
                    ],
                    "systemId": 1,
                    "systemName": "CATEGORIES",
                    "version": 3.7
                  },
                  "properties": {
                    "description": {
                      "description": "Gives a description of the tag tree",
                      "example": "Detailed inusrance categories.",
                      "type": "string"
                    },
                    "displayName": {
                      "description": "User-friendly name shown to the end-users",
                      "example": "Groceries",
                      "type": "string"
                    },
                    "isTenantGenerated": {
                      "description": "Boolean iflag, set TRUE if the tag was manually set",
                      "example": true,
                      "type": "boolean"
                    },
                    "relations": {
                      "description": "List of relations",
                      "items": {
                        "properties": {
                          "href": {
                            "description": "Link of the relation",
                            "example": "https://banksapi.io/.../tags/tag-trees/1/",
                            "type": "string"
                          },
                          "rel": {
                            "description": "Name of the relation",
                            "example": "tag_trees",
                            "type": "string"
                          }
                        },
                        "required": [
                          "href",
                          "rel"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "systemId": {
                      "description": "Unique internal id of the tag tree or tag tree item",
                      "example": 17,
                      "type": "integer"
                    },
                    "systemName": {
                      "description": "Unique name of the tag, tag tree or tag tree item",
                      "example": "LIVING_GROCERIES",
                      "type": "string"
                    },
                    "version": {
                      "description": "Version of the tag tree",
                      "example": 1.5,
                      "minimum": 0,
                      "type": "number"
                    }
                  },
                  "required": [
                    "displayName",
                    "isTenantGenerated",
                    "systemId",
                    "systemName",
                    "version"
                  ],
                  "type": "object"
                }
              ],
              "description": "tagTree that the tagTreeItem belongs to"
            },
            "telephone": {
              "description": "Telephone of the business partner",
              "example": "+49 (0)89 121 408 82",
              "type": "string"
            },
            "website": {
              "description": "Website of the business partner",
              "example": "www.banksapi.de",
              "type": "string"
            }
          },
          "required": [
            "displayName",
            "systemId",
            "systemName",
            "tagTree"
          ],
          "type": "object"
        },
        "tagTreeItemCategory": {
          "example": {
            "description": "Transactions in the field of banking and finance",
            "displayName": "Bank und Finanzen",
            "relations": [
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/1/",
                "rel": "self"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/",
                "rel": "tag_trees"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/",
                "rel": "tag_tree"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/",
                "rel": "tag_tree_items"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/1/",
                "rel": "tag_tree_item"
              },
              {
                "href": "https://banksapi.io/customer/v2/ai/tags/tag-trees/1/tag-tree-items/None/",
                "rel": "tag_tree_item_parent"
              }
            ],
            "systemId": 1,
            "systemName": "BANKFINANCE",
            "tagTree": {
              "description": "Two level categorization tree.",
              "displayName": "Kategorien",
              "isClientGenerated": false,
              "systemId": 1,
              "systemName": "CATEGORIES",
              "version": 3.7
            }
          },
          "properties": {
            "addressCity": {
              "description": "Address city of the business partner",
              "example": "München",
              "type": "string"
            },
            "addressCountry": {
              "description": "Address country of the business partner",
              "example": "Deutschland",
              "type": "string"
            },
            "addressStreet": {
              "description": "Address street incl. number of the business partner",
              "example": "Lyonel-Feininger-Straße 28",
              "type": "string"
            },
            "addressZip": {
              "description": "Address zip/postal code of the business partner",
              "example": " 80807",
              "type": "string"
            },
            "categories": {
              "description": "Categories the business partner belongs to.",
              "example": [
                "BANKFINANCE",
                "SERVICES",
                "SERVICES_PROFESSIONAL"
              ],
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "creditorId": {
              "description": "creditor id of the business partner",
              "example": "DEZZZ00000012345",
              "type": "string"
            },
            "description": {
              "description": "Gives a description of the tagTreeItem",
              "example": "Expenses from daily grocery purchases",
              "type": "string"
            },
            "displayName": {
              "description": "User-friendly name shown to the end-users",
              "example": "Groceries",
              "type": "string"
            },
            "group": {
              "description": "Group the business partner belongs to.",
              "example": "Finconomy AG",
              "type": "string"
            },
            "relations": {
              "description": "List of relations",