The finoOS API provides a safe and secure way to access financial services powered by fino. Once you have obtained a name and secret, you can start using the finoOS API as described in the following sections. All endpoints are located at https://os.fino.cloud/api/v1 for production access and https://os.test.fino.cloud/api/v1 for testing access.

To get started with the finoOS API, check out our Quickstart guide.

Follow these steps to get up and running with the finoOS API by connecting a bank login with our Banking service and retrieve the bank data of your user.

Before you can start to integrate with our API, make sure you have received your credentials name and secret for our testing environment.

Step 1: Authentication

To access the finoOS API, you need to authenticate yourself with the API and obtain an accessToken. This accessToken needs to be provided in every subsequent request, otherwise you will not be able to access the API.

To authenticate with the API you need your name and secret and request a token via our Authenticate endpoint.

curl -s -X POST https://os.test.fino.cloud/api/v1/auth \ 
-H "Content-Type: application/json" \ 
-d '{"name": "<YOUR_NAME>", "secret": "<YOUR_SECRET>"}'

The finoOS API will return the following object.

{
  "accessToken": "<ACCESS_TOKEN>",
  "refreshToken": "<REFRESH_TOKEN>",
  "expiresIn": 300,
  "refreshExpiresIn": 1800
}

The response contains the required accessToken which you will need to provide in the next steps. It also contains a refreshToken which you will need to refresh your authentication when the accessToken has expired.

Step 2: Create a user

To connect a bank login, you first need to create a user for whom you want to connect the bank login. finoOS distinguishes users in two different types:

• person (a real human being)
• company (businesses, SMEs, etc.)

Choosing the type of the user will influence how finoOS analyzes the user's data. To learn more about this, check out the Users section. For now, we will assume the user is a person.

To access the Create User endpoint, you need to provide the accessToken from the first step via the Authorization header and send the following request.

curl -s -X POST https://os.test.fino.cloud/api/v1/users \
-H "Content-Type: application/json" \ 
-H "Authorization: <ACCESS_TOKEN>" \ 
-d '{"type": "person"}'

The finoOS API will return the following object.

{
  "id": "<USER_ID>"
}

The provided id is a unique identifier belonging to this user, which you need to provide in the next steps.

Step 3: Connect a bank login

The finoOS API provides two different ways to connect a bank login. Depending on how you want to process your user's data, you can connect the bank login of a user via

• our Banking UI, allowing the user to connect their real bank accounts from various banks and other financial institutions
• our API, if you already possess the data and do not need a direct connection to the bank

If you want to use our Banking UI, proceed with Step 4a. If you already possess the user's bank data and want to send it directly to our API, proceed with Step 4b.

Step 4a: Connect a bank login via the Banking UI

To access our Banking UI, you need to create a session to connect the user to the Banking service and redirect your user to our UI.

You need to provide three URLs where we can redirect the user to after the bank login. This way, you can provide different URLs in case of

• a successful login: the redirectURL
• an error happens during the bank login process: the errorURL
• a user exits the banking UI during the bank login process: the exitURL

To access the Create Connect User Session endpoint, you will also need the id of the user from the second step and your accessToken. Send the following request.

curl -s -X POST https://os.test.fino.cloud/api/v1/users/<USER_ID>/banking/connect \
-H "Content-Type: application/json" \
-H "Authorization: <ACCESS_TOKEN>" \
-d '{
  "errorURL": "https://yourapp.com/your-error-redirect-resource",
  "exitURL": "https://yourapp.com/your-exit-redirect-resource",
  "recurring": true,
  "redirectURL": "https://yourapp.com/your-success-redirect-resource"
}'

The finoOS API will return the following object.

{
  "redirectURL": "https://uba.test.fino.run/auth..."
}

Redirect your user to the redirectURL of the response object. The user will now be presented our secure Banking UI to connect the bank login.

Enter the bank credentials

First, the user needs to choose a bank and provide their credentials. To try it out, you can search for the fino Bank (bank code is 10020000) and enter the following credentials:

• username: dummy
• password: 654321

Strong Customer Authentication

Second, the user needs to enter a generated TAN for the Strong Customer Authentication(SCA). For the provided test bank login, the TAN will be presented on the Banking UI screen as shown below.

The user is now connected to our Banking service and will be redirected to the redirectURL you provided on the initial request.

Step 4b: Connect a bank login via the API

To connect the bank login directly via our API, you need to possess the bank login data and set the logins of the user via the Set Logins endpoint.

To try it out, you can use the provided bank login data in the request below. You need to provide the id of the user from Step 3 and your accessToken.

curl -s -X POST https://os.test.fino.cloud/api/v1/users/<USER_ID>/banking/logins \ 
-H "Authorization: <ACCESS_TOKEN>" \
-d '{
  "logins": [
    {
      "accounts": [
        {
          "balance": 2004.41,
          "creditLine": 0,
          "currency": "EUR",
          "iban": "DE64100200007791587578",
          "id": "A38253.f837c3ab353",
          "monthlySpendingLimit": 6000,
          "name": "Girokonto",
          "number": "83767594",
          "owner": "Torben Mais",
          "securities": [
            {
              "accountID": "A5ecd4d9bb9e14800012d99e9.1356664d2044208d10cf439e5009e810382ba932",
              "amount": 200,
              "currency": "EUR",
              "exchangeRate": 1.23,
              "id": "5ecd4d9bb9e14800012d99e9",
              "isin": "US0378331005",
              "market": "NASDAQ",
              "name": "finoOS Security",
              "priceAmount": 100,
              "priceCurrency": "EUR",
              "purchasePriceAmount": 150,
              "purchasePriceCurrency": "EUR",
              "quantity": 40
            }
          ],
          "standingOrders": [
            {
              "accountID": "A5ecd4d9bb9e14800012d99e9.1356664d2044208d10cf439e5009e810382ba932",
              "amount": 200,
              "creationDate": "2020-05-26T17:11:22Z",
              "currency": "EUR",
              "executionDay": 2,
              "firstExecutionDate": "2020-05-26T17:11:22Z",
              "id": "5ecd4d9bb9e14800012d99e9",
              "interval": "MONTHLY",
              "lastExecutionDate": "2020-05-26T17:11:22Z",
              "purpose": "Taschengeld"
            }
          ],
          "transactions": [
            {
              "accountID": "A5ecd4d9bb9e14800012d99e9.1356664d2044208d10cf439e5009e810382ba932",
              "amount": 24.99,
              "booked": true,
              "bookingDate": "2020-05-26T17:11:22Z",
              "codes": [
                {
                  "type": "transactionCode",
                  "value": "999"
                }
              ],
              "counterPart": {
                "bic": "GENODEF1S04",
                "creditorId": "DE97ZZZ12345678901",
                "iban": "DE83701999010000002000",
                "name": "Schettchens Schnittchen"
              },
              "currency": "EUR",
              "id": "5ecd4d9bb9e14800012d99e9",
              "mref": "MREF123ZZ678JJ",
              "purpose": "Welcome to finoOS",
              "tags": [
                {
                  "name": "salary",
                  "source": "string"
                }
              ],
              "valueDate": "2020-05-26T17:11:22Z"
            }
          ],
          "type": "GIRO"
        }
      ],
      "bank": {
        "bankCode": "70199901",
        "bic": "SUBSDE71",
        "logo": {
          "type": "string",
          "url": "string"
        },
        "name": "fino Bank"
      },
      "id": "5d7267d1b747aa683d88668f"
    }
  ]
}'

The user is now connected to our Banking service.

Step 5: Retrieve the bank login data

Finally, access the user's bank logins with the Get Logins endpoint. Send the following request.

curl -s -X GET https://os.test.fino.cloud/api/v1/users/5f22c402b6968c000128edb6/banking/logins \
-H "Authorization: <ACCESS_TOKEN>"

The finoOS API will return the following object.

{
  "logins": [
    {
      "id": "5d7267d1b747aa683d88668f",
      "bank": {
        "name": "fino Bank",
        "bic": "SUBSDE71",
        "bankCode": "70199901",
        "logo": {
          "url": "",
          "type": ""
        }
      },
      "accounts": [
        {
          "iban": "DE64100200007791587578",
          "id": "A38253.f837c3ab353",
          "number": "83767594",
          "name": "Girokonto",
          "owner": "Torben Mais",
          "type": "GIRO",
          "balance": 2004.41,
          "creditLine": 0,
          "monthlySpendingLimit": 6000,
          "currency": "EUR",
          "transactions": [
            {
              "id": "5ecd4d9bb9e14800012d99e9",
              "accountID": "A38253.f837c3ab353",
              "bookingDate": "2020-05-26T17:11:22Z",
              "valueDate": "2020-05-26T17:11:22Z",
              "currency": "EUR",
              "mref": "MREF123ZZ678JJ",
              "purpose": "Welcome to finoOS",
              "booked": true,
              "amount": 24.99,
              "counterPart": {
                "bic": "GENODEF1S04",
                "iban": "DE83701999010000002000",
                "creditorId": "DE97ZZZ12345678901",
                "name": "Schettchens Schnittchen"
              },
              "tags": [
                {
                  "name": "salary"
                }
              ],
              "codes": [
                {
                  "value": "999",
                  "type": "transactionCode"
                }
              ]
            }
          ],
          "standingOrders": [
            {
              "id": "",
              "accountID": "A5ecd4d9bb9e14800012d99e9.1356664d2044208d10cf439e5009e810382ba932",
              "creationDate": "2020-05-26T17:11:22Z",
              "firstExecutionDate": "2020-05-26T17:11:22Z",
              "lastExecutionDate": "2020-05-26T17:11:22Z",
              "executionDay": 2,
              "interval": "MONTHLY",
              "amount": 200,
              "currency": "EUR",
              "purpose": "Taschengeld"
            }
          ],
          "securities": [
            {
              "id": "5ecd4d9bb9e14800012d99e9",
              "accountID": "A38253.f837c3ab353",
              "amount": 200,
              "priceAmount": 100,
              "purchasePriceAmount": 150,
              "currency": "EUR",
              "priceCurrency": "EUR",
              "purchasePriceCurrency": "EUR",
              "exchangeRate": 1.23,
              "quantity": 40,
              "isin": "US0378331005",
              "name": "finoOS Security",
              "market": "NASDAQ"
            }
          ]
        }
      ]
    }
  ]
}

To integrate with the finoOS API, we assume you to be familiar with the following technical principles:

• Web APIs
• HTTP(S)
• Representational State Transfer (REST)
• JSON-encoding format

For more information on these topics, follow the respective links. If you are unsure how to integrate with the finoOS API after reading the documentation, feel free to contact us.

To guarantee backwards compatibility, each breaking change causes an upgrade of the API version. This way, users are still able to use the API as usual and can upgrade to a newer version when they are ready.

The API version is part of your account but can be overwritten using a request header. Future new versions will be configurable within our developer portal (not released yet) without any need to update anything on your side. As a precaution, it's recommended to test a new API version before committing to an upgrade.

Every API response contains an API-Version header with the current version of your account. The version is a string date of the format YYYY-MM-DD. The date itself refers to the day of the version's release. The latest version of the API is 2020-06-16.

New features, bug fixes and patches will always be backwards compatible. They can be found in the Changelog. We only release a new version of the API when we introduce breaking changes. We consider breaking changes as one of the following:

• Changing a HTTP method or a resource name
• Adding new required parameters to a resource
• Changing the response structure, not extending it by adding new values to a response
• Changing a HTTP response code
• Changing error codes

Error responses of the API will return one of the HTTP error codes listed below in the Status Codes and Errors table. Error responses will contain a JSON-encoded body of the following format:

{
    "type": "forbidden",
    "message": "Forbidden. No access to this resource"
}

Status Codes and Errors

Code	Name	Description
200	OK	Success
204	OK	Success, but no response content
400	Bad Request	The provided request was invalid. Most of the times, the given format is incorrect.
401	Unauthorized	Invalid authorization. Check your access tokens or tenant id and secret
403	Forbidden	Access for the given resource or operation was denied
404	Not Found	The requested resource doesn't exist
409	Conflict	The request conflicts with a previous request
429	Too Many Requests	Too many requests hit the API too quickly. Rate limit exceeded
5xx	Server Errors	Unknown finoOS server errors

The finoOS API returns a X-Request-ID header with every API response. This way, you can trace a specific request. If you want to make tracing requests easier for yourself, you can overwrite the X-Request-ID header on your requests. When reporting a failure during a request to our API, providing the respective request ID will greatly improve our ability to provide support.

September 25, 2020

• Implementation of the PaymentPartnerAnalysis service

July 29, 2020 Add Scope To User payload changed - renamed scope to name

July 02, 2020

• Implementation of the DocumentShipment service. You can now send a fax or a letter via our API

June 25, 2020

• Routes now hold a scope. If your account holds a certain scope, you are permitted to use the respective routes
• New Get Settings route to request your account specific settings via the API. For now, this returns your API version and scopes
• Users now are assigned scopes to handle permissions on a per User basis

June 22, 2020

• Some Banking routes now require the User-IP header to adhere to the latest PSD2 regulations

June 15, 2020

• Update the Authentication token to accept the OAuth 2.0 standard Bearer Authorization header

May 25, 2020

• Implementation of the Banking service. You can now connect and manage a user's bank login(s) via our API

May 19, 2020

• Implementation of the Search Companies feature of the Companies service. You can now search for multiple companies via a bulk request of queries

May 4, 2020

• Implementation of the Search Logos feature of the Companies service. You can now search for multiple logos of companies via a bulk request of queries

To authenticate yourself with the finoOS API, you exchange your credentials name and secret for a temporary valid pair of JSON web tokens(JWT) via the Authenticate endpoint. The returned accessToken has to be provided in every following request via the Authorization header. Once the returned accessToken expires, exchange the refreshToken for a new pair of JWT. If this is not possible, because the refreshToken has expired too, restart the authentication process from the beginning.

The diagram below shows a sample flow of the authentication process before calling the Search Companies resource of our Companies service.

Users in the finoOS API represent the end-user of your application. All services that require some kind of data persistence are only usable in connection with a user. The resource paths of these services are prefixed with /users/:userID. At the end of the Types section, you will find a list of all services which require a user.

Types

Every user has a type. A user can either be of type person or company. The type of your user will determine which services can be used. It also impacts how we analyze the user's data. You need to specify the type of your user when you create a user.

The below table shows which services are available for which user type and provides details on how each service differs for the different types.

Service	Type "person"	Type "company"	Details
Banking	X	X	Connecting a user to our banking service with the type person will result in categorized transaction data for personal accounts and personal finance use cases. In contrast, setting the type to company will result in categorized transactions for business accounts.
Payment Partner Analysis	-	X	This service is only available for users of the type company.

Scopes

The same way, as your account is assgined scopes, scopes need to be assigned to users to access certain endpoints and services. Set the user's scopes once when you create a user or later when you add a scope to a user

Be aware that when you assign a scope to a user, you will be billed for this scope for the user.

You can manage the settings of your account directly with the finoOS API. The following sections describe what is configurable and how you can do it.

Scopes

Your account is assigned a set of scopes on creation. Scopes define which service or endpoints can be used with your account. In the future, you will be able to update your scopes by booking or cancelling them via our Developer Portal. For now, this can only be done manually by one of our engineers. If you want to book or cancel a certain scope or service, please contact us.

To determine which scopes you need, just check out the endpoints and services you want to implement. The required scope is documented on every endpoint.

The finoOS Banking service provides a secure and reliable way to access and manage financial data of bank accounts. It is based on the Revised Payment Services Directive (PSD2) and adheres to its regulations. PSD2 prohibits non-regulated third-parties to transfer sensitive consumer data such as bank login credentials via an API.

Connecting bank logins with our Banking UI

Therefore, the finoOS Banking service comes with a Banking UI which can be used to connect a bank login by the consumer directly. The Banking UI also handles the mandatory Strong Customer Authentication (SCA) for the bank login. Once a bank login is connected to a user, the finoOS API will synchronize the account data automatically as long as no new SCA of the user is required. You can check if a new SCA is required via the Get Logins Synchronization Status endpoint.

Manually adding bank logins and transaction data

If you already possess the bank login and transaction data of your customers, you can use the finoOS Banking Service by adding this data via the Set Logins and Update Logins routes. You will not be able touse our Banking UI and the particular routes. Make sure to enable the bankingExternal scope for the respective user.

The finoOS Companies service provides access to a database with several hundred thousand verified companies. It holds information about these companies' addresses, contact information, logos, creditor identifiers, related bank accounts and more.

The finoOS Document Shipment service provides an easy way to send documents via fax or a letter. You can simply encode a PDF file as a base64-encoded string and send it to any recipient.

The finoOS Payment Partner Analysis service is an intelligent bank account analysis service. It analyses your payment partners and returns information on how relevant an individual payment partner is for your liquidity. This information includes details on how long the relationship to this customer or supplier exists, how much of your income/outcome is dedicated to this partner and much more.