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.