API docs by Redocly

FinoOS2 Documentation (1.20.7)

Download OpenAPI specification:Download

Support: os.support@fino.run License: "

Introduction

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

Legacy API finoOS1 Documentation: legacy.

Principles

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

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.

Errors

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
201 Created Success
202 Accepted Success
204 No Content 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

Authentication

To authenticate yourself with the finoOS API, you exchange your client identifier and client 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.

Authentication

Authenticate with your credentials client_id and client_secret and grant_type=client_credentials to retrieve a JWT. The expiresIn property indicate the lifetime of the accessToken in seconds.

Generate new token with:

  • client_id=5d7267d1b747aa683d88668f
  • client_secret=5d7267d1b747aa683d88668f
  • grant_type=client_credentials
Request Body schema: application/x-www-form-urlencoded
required
client_id
required
string

5d7267d1b747aa683d88668f

client_secret
required
string

5d7267d1b747aa683d88668f

grant_type
required
string

client_credentials

Responses

Response samples

Content type
application/json
{
  • "access_token": "jA1nN-pl4uEwyJ0_-v3rIr3byH2PwyQ_deE20sWDEdolpJB-NBASpQyxXnjL1M9Yorq3QZAUCuaam9DH_KoLb3NlOPVDar83lI3_Ns3R_LrMcs_P4hs_m57Z-h-BBBdKklvqibLAZTp_0l90-Quy1vcrER7lN3oIfwSEpxhebA8CWKlTYROUfTax6g_25JSAKtUT-wjGl29_rRlFIs9tQcmDrwCkz7iRv5y9tE_S5hbiJ5n7vBPKna7zaeYqcq-09K_SP8iopGkiUC1LVUIiwYt2UdDGi2FnebhtWiuPQTE0zVqqe_ivY0GTKvbQndXfAYkMnWS3L6BXcIAFNPxBpcRynkAsOM5GUKtGa8laHkcAJ5uzPsurlWhPnlmFQv41fQvyzMH-jWWqzeU0RHyIufgy2Zj6-sO4ImbH1lhK2M_Y4dplIAtAfWIcWzatz3SAuksdCp1r8FuSBP2uMS0Y2v0nQU6QC78WymqNPebv7XO-q55Tl4CO3z-uf4qeV0RnQLMvNa0LIz-IduJicV01_QKw8dCfn4zLNCV5l8Tc15G1CumDIpFFe_kbuYWyQ9v6111EyPVOu3Qeom8zDWE5qmaiQ8eB-LE45zi7Da_6HKVH0LSSMEzneNDYonJqQR1Ea1mkHglzjbQRiylclCzMRNKbAKhXM7erolX0HwLj27iliGoQ1itIgeAsNYtty2JVmIE2pI2p2YimvUkLNiqhhZtFhagDVmxo2GeFD7PBS4-RxdmM0kuyb-VB8sDFMEeZ5hW1wec2rfy1eNfS5sVLtSvCBpMbUvG0eHZWHvYAFX-4yJ5F1tQoYlK_Yc7RJuR_D0lcpBTiobYwRCXIsuGMf-hhrSyzSKDMG0rIowf-XC1XInAjdzpq4LLNykUIntJrFsDobbngoKJAMJUcRA3SUElRXvYkms6E62lSQPEGeuPTLcMrM3mumUND6uf0wcw96VM3Rd6NgSJ-U6Xd8ofy76X-GSYxj3O7j4r5EjEqHFaogLpthA85PYJmYdinH7eXRQ47AHLJmAwXfS-Tiu776Iep8_lUY2n78_i4QaA8gPPyLXa6JN-IL6uFdnowjGfpDWnIjUmUqVODMIrtIr7LjNtQhz0PXj-PvUIjXTcA__wkGZDi3TXSJ9X8C7XH7xUJbXo1jQsya-A_5erTd6RGSZs4Pgtn6Q714sC2PVhB0Ks3qOVe6t42iFQ_1Y4VYBa9e-5PW4TRMn4VjF0wrXHWZqlF1uEf5c3zbFF9JDT4NehvdcAnBc9HcyY18V9V7tZGnrmIVeKSZIXO1nKBplQR_roSS-ikIBYwR0V6sVjy8czM6eE2-9WL64d0V7PNGth5XTUF3BLwVpKXFq6nyRdLJvN_5ASDUtOXV6Gwxv2a_hFMA9Sx1KzewxQZVNiOEwO7WGgja46JsmLg0EUDLAKXMFsUGAqdE9E6b8CY_EbSPfEEFayt6KOpihVKDwDsvhe-rIJiQlszfLDvPHQTC3DRL6KbmncdHjlV93RjcBK2HsF1DQM8MOjAtBQMDvZv46PA56kYnSPKqNH_vaLo7bX173j829KikrfJcCj8ca2fYOKh7kY6nZfFInceJFVmKFO0Ea1EqI4o9koCRNMVA4IRBJTVA4EC0WBPQ_KqY7K2tA85zDwFCVx8uxT8bdu7XUd3jU24KVkAucQoP_OcTCgPjaDCqoO0rta-EJ45547sxzhfaCoG4QFP5XMXFwwo756O5_QXBk8PUIwMDKKMCqvFn0ySswcOE5vLxhtXvRq7OXytEPtfVvmF_Tt0Kkb6KBvBrFjrWiJkNfWEvwZonPC5xN4FgJcIW-Xm4mOAuIJVIEH3I-JvmTYAMfgMz85L0C7O2ls9n9_vMsHAKpeDUn4iJ9UuIOp3x8QkEgBTBSoIC3e22wVGjdExzeuqIT_e_6poFl6l7Vx-UBi_dPrNGETxvW4K5-svXtiV-Igsw3YonweKIpZ516C3PajGK1_BjwyzsdyqKoKfadtdMXgv9llh98OfqAjXOju-BsWf9Z7DBpxC8G7ZgArHOKauh8bGORtC3iBph-Pe_YYuJhayTsD2iaf_JpMiZS2fS2ooeuLHC86A5ZFhQJ8dbrFCGDfWds_WCpKyy8igEZVjBdTZS5vRLJ5BJKvZw_vNa37FLjAH0EyuSCXaPHF9TpdsqtfJbauv-yvPBlwxVh3j8zm8WipFeRBdPitDlDWAvwIYrgYRIgGaq_FrSYVrXoSwTxSoahjRAGE7YdpEJWGssDttSol4fIdZA5IyDnhGV6zk-IYYZuPjWs8p49b0yyuvPiDCen-hgYIdaVrB3UyzdX9MxPfqopLAtp8KIr_9RbPkNg26eEfQOxqTCS6qPNIpnSHKEOxEQACdMEJ6VUFZcKzS41cywiGoqNHvu0PrwTQxcAYqS9A2d-xpf7M4ZJ73",
  • "expires_in": 300,
  • "not-before-policy": 1618235966,
  • "scope": "credits webhooks companiesLogo bankingExternal banking contracts",
  • "session_state": "1e2212ad-e13f-4d3d-af05-7d1716ee920a",
  • "token_type": "Bearer"
}

Scopes

Your client is assigned a set of scopes on creation. Scopes define which service or endpoints can be used with your client. For now, this can only be done manually by one of our engineers. If you want to book or cancel a certain scopes or services, 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.

scope description
banking access to all banking features
banking-fetch fetching of raw accounts and transactions
banking-connect connecting to xs2a interface to retrieve accounts and transactions and enable automatic daily syncs of the data
banking-upload uploading of raw accounts and transactions
categorization transaction tags detected by our analysis
categorization-categories categories tree and their dependencies on each other and a description of the categories with localization in German and English
account-detection list of accounts uploaded or retrieved with xs2a and additional accounts detected by our analysis
account-history daily balances for all accounts
contracts contracts based on tags and other characteristics
cockpits comprehensive display of our analysis results
renter-information compact salary and rental information
webhooks enables to create webhooks to receive notifications or data for every scope or analysis result

Users

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.

Get Users

Gets all users paginated.

query Parameters
page
string

The page of users to retrieve

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
  • "context": {
    },
  • "users": [
    ]
}

Add User

Adds a user.

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

automaticAnalysis
string
Default: "active"
Enum: "suspended" "active"

Optional field to deactivate the automatic analysis for the user. If set to suspended, the user will not be analyzed automatically and trigger-analysis can be used instead. If set to active, the user will be analyzed automatically.

customUserID
string

Optional CustomUserID of the created user.

name
string

Optional Name of the created user.

type
string
Enum: "person" "company"

Type of the user.

userScopes
Array of strings

Optional Scopes array to create this specific user with reduced calculation scopes. Can be a array containing values of [banking,banking-fetch,banking-upload,account-detection,categorization,contracts,cockpits]. Only the given scopes will be accessible and calculated for the created user.

Responses

Request samples

Content type
application/json
{
  • "automaticAnalysis": "suspended",
  • "customUserID": "0815",
  • "name": "John Doe",
  • "type": "person",
  • "userScopes": [
    ]
}

Response samples

Content type
application/json
{
  • "context": {
    },
  • "user": {
    }
}

Update User

Updates a user.

header Parameters
Authorization
required
string

The authorization token

tenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

automaticAnalysis
string
Enum: "suspended" "active"

Optional field to deactivate the automatic analysis for the user. If set to suspended, the user will not be analyzed automatically and trigger-analysis can be used instead. If set to active, the user will be analyzed automatically.

customUserID
string

Optional CustomUserID of the created user.

name
string

Optional Name of the created user.

Responses

Request samples

Content type
application/json
{
  • "automaticAnalysis": "active",
  • "customUserID": "0815",
  • "name": "John Doe"
}

Response samples

Content type
application/json
{
  • "context": {
    },
  • "user": {
    }
}

Get User using customUserID

Get User by using optional value customUserID which can be assigned to a user on creation. Note this currently can only find the customUserID if a cockpit was successfully created.

path Parameters
custom-user-id
required
string

The customUserID id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
  • "advisorID": "string",
  • "advisorIDs": [
    ],
  • "createdAt": "2024-08-14T11:37:20.515Z",
  • "customUserID": "0815",
  • "duplicates": [
    ],
  • "id": "e57a73a9-bcda-4cda-9e8a-99a915a7d675",
  • "tenant": "testTenant",
  • "type": "person"
}

Delete Users

Delete multiple user.

header Parameters
Authorization
required
string

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

userIDs
Array of strings

Responses

Request samples

Content type
application/json
{
  • "userIDs": [
    ]
}

Response samples

Content type
application/json
{
  • "users": {
    }
}

Import User with External Accounts

Scope: banking or banking-upload and cockpits

Send User Creation information alongside the bank accounts and transactions When you set the accounts and transactions, make sure to provide a unique id or number on each

  • account.accountId
  • account.accountNumber
  • transaction.transactionId

Otherwise our services will not be able to handle your data correctly and return unexpected results.

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

Request Body schema: application/json
required

The payload of the request

required
Array of objects (banking.AccountRequest) non-empty
Array of objects (banking.Advisor)

Only required for status=start. Optional Advisors of the created user. Minimum is a id to connect the cockpit to the advisor.

customUserID
required
string

Required CustomUserID of the user and later used for allocation of created user.

name
string

Only required for status=start. Optional Name of the created user.

status
required
string
Enum: "start" "upload" "finish"

Combination of enums is allowed. start for user creation, upload for appending data and finish for starting the analysis process.

type
string
Enum: "person" "company"

Only required for status=start. Required Type of the created user. Can be person or company.

Responses

Request samples

Content type
application/json
{
  • "accounts": [
    ],
  • "advisors": [
    ],
  • "customUserID": "1337",
  • "name": "string",
  • "status": "start,finish",
  • "type": "person"
}

Response samples

Content type
application/json
{
  • "correlationID": "string",
  • "correlationTimestamp": "string",
  • "customUserID": "1337",
  • "userID": "1234567890"
}

Get User

Get a user.

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
  • "context": {
    },
  • "user": {
    }
}

Delete User

Delete a user.

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "type": "invalidInput"
}

Add scopes to user

Adds scopes to user and trigger a new calculation with expanded scopes.

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

userScopes
Array of strings

Scopes input for a user to calculate more scopes. Scopes can only be added and cannot be removed. Can be a array containing values of [banking,banking-fetch,banking-upload,account-detection,categorization,contracts,cockpits]. Only the given scopes will be accessible and calculated for the user.

Responses

Request samples

Content type
application/json
{
  • "userScopes": [
    ]
}

Response samples

Content type
application/json
{
  • "correlationID": "18bf1171-9e82-4a74-bf52-923b9a80144e",
  • "userScopes": [
    ]
}

Trigger a new analysis for user.

Manually trigger a new analysis for this user. The user needs to have raw banking data instead if not this no new analysis can be triggered.

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
  • "correlationID": "18bf1171-9e82-4a74-bf52-923b9a80144e",
  • "userScopes": [
    ]
}

Banking

The finoOS Banking service provides a secure and reliable way to access and manage financial data of bank accounts.

For multi banking access or connecting of multiple bank accounts use the following procedure:

  • For a new user use Create Connect User Session to connect the first bank account
  • Further accounts can be added with Create Management Session which by default has an overview UI of the connected accounts
    • the query param addBankLogin=true skips the overview UI and starts a connect flow for an additional account so that you can seamlessly connect multiple accounts

Get Accounts

Scope: banking

path Parameters
user-id
required
string

The user id of the finoOS user

query Parameters
includeTransactions
boolean

Set to false if accounts response should not include transactions. Defaults to true

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
  • "accounts": [
    ]
}

Create External Accounts

Scope: banking,banking-upload

Note: You can only set accounts if you do not use our Banking UI and already possess the bank data of your user.

Set the bank accounts of the user. When you set the accounts and transactions, make sure to provide a unique id or number on each

  • account.accountId
  • account.accountNumber
  • transaction.transactionId

Otherwise our services will not be able to handle your data correctly and return unexpected results.

If an account with an existing accountId and accountNumber is provided, it will override the existing account in our database.

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

required
Array of objects (banking.AccountRequest) non-empty

Responses

Request samples

Content type
application/json
{
  • "accounts": [
    ]
}

Response samples

Content type
application/json
{
  • "userId": "d73df22f-cff9-4a31-8cd2-7f46e8603414"
}

Patch External Accounts

Scope: banking,banking-upload

_Note: You can only set accounts which were previously added by a manual upload with banking-create-external-accounts

Updates the bank accounts of the user. Can update account fields and transaction fields excluding the ids and accountnumber.

When fields are omitted from the request or null they will be ignored by the update. For example if bankName is set to "example" and the update request does not contain bankName, the bankName will not be updated and still be set to "example".

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

Array of objects

Responses

Request samples

Content type
application/json
{
  • "accounts": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "type": "invalidInput"
}

Delete transactions from External Accounts

Scope: banking,banking-upload

Delete transactions from existing accounts. The account with the provided id must exist or this request will fail accordingly.

path Parameters
user-id
required
string

The user id of the finoOS user

account-id
required
string

The account id of the account

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

ids
Array of strings

The transactionIds to delete for the account

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "type": "invalidInput"
}

Patch transactions for External Account

Scope: banking,banking-upload

Update transactions for existing accounts. The account with the provided id must exist or this request will fail. Also each transactionId must already exist to update a transaction.

When fields are omitted from the request or null they will be ignored by the update. For example if bookingText is set to "example" and the update request does not contain bookingText, the bookingText will not be updated and still be set to "example".

path Parameters
user-id
required
string

The user id of the finoOS user

account-id
required
string

The account id of the account

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

Array of objects

Responses

Request samples

Content type
application/json
{
  • "transactions": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "type": "invalidInput"
}

Get Account Summary as PDF

Scope: banking

Returns the account summary as a PDF that contains up to a maximum of 10000 transactions.

If since and until are provided, the summary will only contain transactions within the specified date range.

If no date range is specified, the summary will attempt to gather all transactions of the account up to a limit of 10000 transactions.

If a date range is provided, and it contains more than 10000 transactions, the pdf will only contain all transactions up to the last date that does not exceed this limit. In this case, the response will have a 206 status code.

If a pdf file returns with a 206 status code, the response will contain a header stoppedAt which will point to the next available date after the last page that was successfully processed.

Note: It is also possible to only provide the since parameter. In this case, the summary will be generated from the provided date until the current date. Also, if the gathered data exceeds 10000 transactions, the response will be cropped as described above.

path Parameters
user-id
required
string

The user id of the finoOS user

account-id
required
string

The id of account to get the summary for

query Parameters
since
string

RFC3339 formatted timestamp for inclusive filtering

until
string

RFC3339 formatted timestamp for inclusive filtering

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Add transactions to External Accounts

Scope: banking,banking-upload

Add transactions to existing accounts. The account with the provided id must exist or this request will fail accordingly.

You have to provide unique transaction ids. Otherwise our services will override existing transactions.

path Parameters
user-id
required
string

The user id of the finoOS user

account-id
required
string

The account id of the account

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

required
Array of objects (banking.TransactionRequest)

Responses

Request samples

Content type
application/json
{
  • "transactions": [
    ]
}

Response samples

Content type
application/json
{
  • "transactionsAdded": 0
}

Create Connect User Session

Scope: banking

Connect the user with the banking service. This creates a session for our Banking UI and returns a URL to the bank login section of the Banking UI. Redirect your user to this URL. After connecting the bank login or in case of an error or exit of the user, we will redirect the user to your application. Specify your own redirect URLs for the following cases:

  • redirectURL: The bank login was successful
  • errorURL: An error happened
  • exitURL: The user exits the Banking UI The redirect URLs will contain an userID query parameter to match the redirect to the respective finoOS user.
path Parameters
user-id
required
string

The user id of the finoOS user

query Parameters
demo
string

Set to true to activate demo mode for UBA. Simulates the login flow with fino bank and the selected demo account. False by default.

bankCode
string

The bank code of the bank to connect to. If not provided, the user will be prompted to select a bank in the Banking UI.

multiple
string

Set to true to redirect back to the management screen to connect additional accounts, false otherwise (also by default). Will be included in the response's redirectURL as query parameter.

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

accountTypes
Array of strings
Items Enum: "BAUSPAREN" "DEPOT" "FESTGELD" "FONDSDEPOT" "GIRO" "KREDIT_KARTE" "KREDIT_KONTO" "KREDITDARLEHEN" "SPARBUCH" "TAGESGELD" "UNKNOWN" "OTHER"

List of account types to be shown during login

errorURL
required
string

The URL your user will be redirect to in case of an error during bank login

exitURL
required
string

The URL your user will be redirect to in case she or he exits the process

persistNonRecurring
boolean

Flag that indicates whether to persist non-recurring users. If omitted or set to false, non-recurring users and associated account data will be automatically deleted after 24 hours. This flag has no effect on recurring users

recurring
boolean
Default: false

Whether this shall be a recurring user or not

redirectURL
required
string

The URL your user will be redirect to in case of a successful bank login

storeSecrets
boolean

Whether the bank login credentials should be stored or not

Responses

Request samples

Content type
application/json
{}

Get Correlation

Scope: banking

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
  • "correlationID": "cc451d48-dbc2-4ea4-894a-fb4b299f9e56",
  • "correlationTimestamp": "2024-01-22T14:08:47+01:00"
}

Disconnect User

Scope: banking Disconnects a user from the banking service. This will also delete all stored banking data connected to the user such as his bank logins and banking. It will not delete the user itself.

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

User-IP
required
string

The IP address of the user. This is mandatory due to PSD2 regulations.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "type": "invalidInput"
}

Get Logins Synchronization Status

Scope: banking

Get the synchronization status of the connected bank logins. Determine whether the connected bank login is still synchronized automatically in background or if you need to Trigger a Synchronization manually

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete Login

Scope: banking

Delete a connected bank login of the user.

path Parameters
user-id
required
string

The user id of the finoOS user

banklogin-id
required
string

The bankLoginId of the accounts to be deleted

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

User-IP
required
string

The IP address of the user. This is mandatory due to PSD2 regulations.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "type": "invalidInput"
}

Money Transfer

Scope: banking

Sends a list of money transfers. Either returns 200 (no TAN was required, transfer was successful) or 451 (user input required)

path Parameters
user-id
required
string

The user id of the finoOS user

banklogin-id
required
string

The id of BankLogin to execute the money transfer on

header Parameters
Authorization
required
string

The authorization token

User-IP
required
string

The IP address of the user. This is mandatory due to PSD2 regulations.

Request Body schema: application/json
required

The payload of the request

accountId
string

Internal AccountID

executionDate
string

Execution date for the money transfer(s) in the format 'YYYY-MM-DD'. Cannot be in the past. If omitted, current date will be used.

exitUrl
string

URL the user gets redirected to after exiting the money transfer operation. Only secured URLs permitted (https)

fallbackUrl
string

URL the user gets redirected to after an error occurs during money transfer. Only secured URLs permitted (https)

Array of objects (banking.MoneyTransferInfo)

Holds all user input for a single money transfer

redirectUrl
string

URL the user gets redirected to after money transfer operation succeeds. Only secured URLs permitted (https)

singleBooking
boolean

Only relevant for multiple money transfers. Processes the money transfers as a single booking (value: true) or as single bookings (value: false). Default value is true

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "paymentId": "4c3f499042d08950a7f6126b",
  • "sessionId": "5c3f499042d08950a7f6126b",
  • "status": "success"
}

Get Money Transfer

Scope: banking

Returns a detailed response for an existing MoneyTransfer with the executed payments and the current status

path Parameters
user-id
required
string

The user id of the finoOS user

banklogin-id
required
string

The id of BankLogin the money transfer was executed on

money-transfer-id
required
string

The id of the money transfer

header Parameters
Authorization
required
string

The authorization token

User-IP
required
string

The IP address of the user. This is mandatory due to PSD2 regulations.

Responses

Response samples

Content type
application/json
{
  • "moneyTransfers": [
    ],
  • "status": "OPEN"
}

Create Management Session

Scope: banking

This creates a session for our Banking UI and returns a URL to the overview section of the Banking UI. Redirect your user to this URL. After connecting the bank login or in case of an error or exit of the user, we will redirect the user to your application. Specify your own redirect URLs for the following cases:

  • redirectURL: The bank login was successful
  • errorURL: An error happened
  • exitURL: The user exits the Banking UI The redirect URLs will contain an userID query parameter to match the redirect to the respective finoOS user.
path Parameters
user-id
required
string

The user id of the finoOS user

query Parameters
addBankLogin
string

Jump directly to the add bank login screen in the Banking UI

bankCode
string

In combination with addBankLogin the bank code of the bank to connect to. If not provided, the user will be prompted to select a bank in the Banking UI.

demo
string

Set to true to activate demo mode for UBA. Simulates the login flow with fino bank and the selected demo account. False by default.

multiple
string

Set to true to redirect back to the management screen to connect additional accounts, false otherwise (also by default). Will be included in the response's redirectURL as query parameter.

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

accountTypes
Array of strings
Items Enum: "BAUSPAREN" "DEPOT" "FESTGELD" "FONDSDEPOT" "GIRO" "KREDIT_KARTE" "KREDIT_KONTO" "KREDITDARLEHEN" "SPARBUCH" "TAGESGELD" "UNKNOWN" "OTHER"

List of account types to be shown during login

bankLoginId
string

The ID of the bank login to be synchronized

errorURL
string

The URL your user will be redirect to in case of an error during bank login

exitURL
string

The URL your user will be redirect to in case she or he exits the process

redirectURL
string

The URL your user will be redirect to in case of a successful bank login

Responses

Request samples

Content type
application/json
{}

Connect User Mock

Scope: banking

Connect and add a mocked bank account from our fino bank without going through any SCA process. This is just for testing and demo purposes.

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

userName
string

Username of the test bank account to connect. Your contact person at fino can provide you with some test accounts. If not provided, the default value will be finocontext1. This account contains some transactions and represents a "real" person

Responses

Request samples

Content type
application/json
{
  • "userName": "finocontext1"
}

Response samples

Content type
application/json
{
  • "alreadyConnected": true,
  • "bankLoginId": "4c3f499042d08950a7f6126b",
  • "data": [
    ],
  • "status": "success"
}

Create Synchronization Session

Scope: banking

Trigger the synchronization of a connected bank login to fetch new account and transaction data from the bank. This can result in the following responses:

  • 204: The synchronization was successful and you can query the latest bank accounts data via Get Accounts
  • 409: The interface used to set up the bank connection is deprecated. The user must update the connection, please redirect him to the management session.
  • 422: The user's credentials are required for syncing.
  • 423: The access to the account is blocked. This possibly is a problem on the user's chosen banking provider. Please refer to the payload of the response for more context
  • 429: The daily limit of manual synchronizations has been reached
  • 451: This creates a session in our Banking UI, because the user has to redo the SCA process to fetch new data. Redirect your user to the response URL. After connecting the bank login or in case of an error or exit of the user, we will redirect the user to your application. Specify your own redirect URLs for the following cases:
  • redirectURL: The bank login was successful
  • errorURL: An error happened
  • exitURL: The user exits the Banking UI The redirect URLs will contain a userID query parameter to match the redirect to the respective finoOS user.
path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

User-IP
required
string

The IP address of the user. This is mandatory due to PSD2 regulations.

Request Body schema: application/json
required

The payload of the request

bankLoginId
string

The ID of the bank login to be synchronized

errorURL
string

The URL your user will be redirect to in case of an error during bank login

exitURL
string

The URL your user will be redirect to in case she or he exits the process

redirectURL
string

The URL your user will be redirect to in case of a successful bank login

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "message": "string",
  • "type": "invalidInput"
}

Get Transactions

Scope: banking

Returns all transactions for this user

path Parameters
user-id
required
string

The user id of the finoOS user

query Parameters
since
string

RFC3339 formatted timestamp for inclusive filtering

until
string

RFC3339 formatted timestamp for inclusive filtering

transactionIds
string

TransactionId`s seperated bei comma. If this is sent since and until are ignored

lastMonths
string

filters the transactions of the last n months from the current time. Must be a positive value

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Categorization

This categorization-categories scope allows access to the categories and to determine their dependencies on each other. Additionally, a description of the categories is available with localization in German and English.

The hash version of the tree and the description is an aid to recognizing the changes, it is not a version per se. We reserve the right to adapt the hierarchies if we think that it fits better from a technical point of view.

Get Categorization

Returns a paginated list or current tags for transactions.

Its possible to query for changes in the categorization by providing a correlationID in the query. This will return the diff of newly added tags for transactions since the provided correlation.

path Parameters
user-id
required
string

The user id of the finoOS user

query Parameters
page
integer

The page number. Default is 1.

pageSize
integer

The number of transactions to return. Default is 10.

correlationID
string

optional: If provided, the response will only contain changes to tagging for the correlationID or newer. This includes tags for newly added transactions or changes in tagging for previously tagged transactions

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
  • "categorization": [
    ],
  • "metaData": {
    }
}

Get Correlation

Scope: categorization

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
  • "correlationID": "cc451d48-dbc2-4ea4-894a-fb4b299f9e56",
  • "correlationTimestamp": "2024-01-22T14:08:47+01:00"
}

Get Patterns

Returns a list of patterns that the user has added

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
  • "ids": {
    },
  • "patterns": [
    ]
}

Add or update patterns

The endpoint makes a complete update of the patterns and then categorizes the transactions. Therefore, all patterns must be specified in the body, even if the pattern does not change. Currently it is only possible to create patterns based on the PaymentPartner (Name and CreditorID). Further possibilities will follow. If since and until are omitted, all existing transactions are tagged.

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload with patterns

object (categorization.SwagID)
Array of objects (categorization.Pattern)

Responses

Request samples

Content type
application/json
{
  • "ids": {
    },
  • "patterns": [
    ]
}

Get Transactions

Returns the transactions of the user with the current valid tags

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
  • "accounts": [
    ]
}

Get Categorization for transaction

Returns the current tags of a transaction

path Parameters
user-id
required
string

The user id of the finoOS user

transaction-id
required
string

The transaction id

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
  • "tags": [
    ]
}

Categorization-Tree

This categorization-categories scope allows access to the categories and to determine their dependencies on each other. Additionally, a description of the categories is available with localization in German and English.

The hash version of the tree and the description is an aid to recognizing the changes, it is not a version per se. We reserve the right to adapt the hierarchies if we think that it fits better from a technical point of view.

Get Categorization Tree

Returns the categorization tree, which represents a hierarchy of tags when categorizing

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

Responses

Response samples

Content type
application/json
{
  • "nodes": {
    },
  • "treeVersionHash": "string",
  • "type": "string"
}

Get Categorization Description

Returns the description of tags

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

Responses

Response samples

Content type
application/json
{
  • "descriptionList": [
    ],
  • "descriptionVersionHash": "string",
  • "language": "string",
  • "type": "string"
}

Account-Detection

This Banking Module returns a list of Bank-Account & CreditCards that the User has connected. Additionally other Accounts that were found through the Analysis of the Users Transaction-Data are also returned. If an account was found through the analysis the field additionalAnalysesInfo.IsUserAdded will be true.

Get Account Detection

Returns a list of user connect accounts + other accounts found through transaction analysis

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
  • "accountsOverview": {
    }
}

Get Correlation

Scope: account-detection

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
  • "correlationID": "cc451d48-dbc2-4ea4-894a-fb4b299f9e56",
  • "correlationTimestamp": "2024-01-22T14:08:47+01:00"
}

Account-History

The Account-History section provides an overview of all accounts and their daily balances for the past 2 years.

Get Account History

Scope: account-history

Returns a list of accounts and their daily balances for the last two years

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
  • "histories": [
    ]
}

Get Correlation

Scope: account-history

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
  • "correlationID": "cc451d48-dbc2-4ea4-894a-fb4b299f9e56",
  • "correlationTimestamp": "2024-01-22T14:08:47+01:00"
}

Contracts

The finoOS Contracts service uses an intelligent bank account analysis algorithm to detect contracts and their respective transactions on one or multiple bank accounts of a user. This way, you can easily see the ongoing and past contracts of a user to get an understanding of his financial relationships. Use the finoOS Contracts service to manage these contracts by adding, updating or deleting contracts.

Be aware that we define a contract as any transactions which:

  • belong to one counter part (a person or a company)
  • recur in a certain interval
  • can be grouped together for a specific purpose

Before you can use the Contracts service, make sure to register your user with the Banking service and have one or multiple bank logins connected.

Get Contracts

Scope: contracts

Get all contracts of the connected bank logins of a user. This includes active and past contracts.

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete Contracts

Scope: contracts

Delete all contracts of the specified user

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "type": "invalidInput"
}

Get Correlation

Scope: contracts

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
  • "correlationID": "cc451d48-dbc2-4ea4-894a-fb4b299f9e56",
  • "correlationTimestamp": "2024-01-22T14:08:47+01:00"
}

Delete Contract

Scope: contracts

Delete a contract from the user's existing list of contracts.

path Parameters
user-id
required
string

The user id of the finoOS user

contract-id
required
string

The id of the contract to be deleted

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "type": "invalidInput"
}

Companies

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.

Search Companies

Scope: companies

Search for a companies via queries. Define a keyword to search for. Define the properties of the company model on which you want to perform the search. Specify a limit for the maximum search results for a unique query.

query Parameters
logo-size
integer

determines logo width to be returned - does not scale svg images (default is 0 and returns images in original size)

header Parameters
Authorization
required
string

The authorization token

Request Body schema: application/json
required

queries

required
Array of objects (companies.CompanyQuery)

Responses

Request samples

Content type
application/json
{
  • "queries": [
    ]
}

Response samples

Content type
application/json
{
  • "results": {
    }
}

Search Logos

Scope: companiesLogo

Search for logos of companies via queries. If you provide a queryID on each query object, you can match the query result objects to the respective queries. The order of the results list is not guaranteed to match the order of the queries list. The maximum number of queries in a request is 200.

query Parameters
exactMatch
boolean

determines whether to perform an exact match on the name instead of a fuzzy match (default is false)

fuzziness
string

determines the fuzziness (levenshtein distance) performed on the name - not used if exact match is set to true (recommended values 'AUTO'/'1'/'2', default is 'AUTO')

logo-size
integer

determines logo width to be returned - does not scale svg images (default is 0 and returns images in original size)

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

required
Array of objects (companies.LogoQuery)

The queries to search for the logos

Responses

Request samples

Content type
application/json
{
  • "queries": [
    ]
}

Response samples

Content type
application/json
{}

Cockpits

A cockpit manages to show, through analysing accounts, accumulated data about income, expenses, contracts, living situation, home situation, credits, asset accumulation and more based on the modules booked. There exists different types of cockpits - for private persons and for companies.

Before using the cockpit endpoints the following necessary steps need to be taken:

Get Cockpits paginated

Scope: cockpits Returns a paginated minimized cockpit model as list in json format.

query Parameters
page
integer

the page number (default: 1)

page-size
integer

ths page size (default: 20 min: 2)

advisor-id
string

search cockpits for the specified advisor-ID

custom-user-id
string

search cockpits for the custom-user-ID

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
  • "cockpits": [
    ],
  • "metaData": {
    }
}

Get Company Cockpit

Scope: cockpits Webhook Event: companycockpit

Returns a company cockpit in json format.

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
  • "accountData": {
    },
  • "caa": {
    },
  • "cashflow": {
    },
  • "collectivePayments": {
    },
  • "contracts": [
    ],
  • "createdAt": "string",
  • "credits": [
    ],
  • "customerTop": [
    ],
  • "facts": {
    },
  • "graphs": [
    ],
  • "insurances": [
    ],
  • "internalContracts": [
    ],
  • "liquidity": {
    },
  • "observationPeriod": {
    },
  • "savingSecurities": [
    ],
  • "securities": [
    ],
  • "supplierTop": [
    ],
  • "tenant": {
    },
  • "type": "string",
  • "user": {
    },
  • "version": "string"
}

Get Correlation

Scope: cockpit

path Parameters
user-id
required
string

The user id of the finoOS user

query Parameters
correlation-id
string

If specified, the corresponding correlation is returned

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
  • "correlationID": "cc451d48-dbc2-4ea4-894a-fb4b299f9e56",
  • "correlationTimestamp": "2024-01-22T14:08:47+01:00"
}

Get Cockpit PDF

Returns a cockpit in the pdf format

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Get Person Cockpit

Scope: cockpits Webhook Event: personcockpit

Returns a person cockpit in json format.

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
  • "accountData": {
    },
  • "accountHistories": {
    },
  • "contracts": [
    ],
  • "createdAt": "string",
  • "credits": [
    ],
  • "householdExpenditure": {
    },
  • "income": {
    },
  • "insurances": [
    ],
  • "internalContracts": [
    ],
  • "liquidity": {
    },
  • "observationPeriod": {
    },
  • "overview": {
    },
  • "savingSecurities": [
    ],
  • "securities": [
    ],
  • "spending": {
    },
  • "tenant": {
    },
  • "type": "string",
  • "user": {
    },
  • "version": "string",
  • "wealth": {
    }
}

Get Cockpit Recommendations

Scope: cockpits Webhook Event: companycockpit-recommendations,personcockpit-recommendations,cockpitrecommendations.notification

Returns cockpit recommendations in json format.

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
  • "recommendations": [
    ]
}

Cockpit-Advisors

Advisor is a submodule of the cockpit and offers the possibility to assign cockpits to an advisor in order to assign a specific contact person. After creating an advisor, cockpits can be created via the URL of the advisor. Depending on how it is configured, an advisor is automatically notified when a cockpit is created.

Get Advisors Paginated

Returns multiple advisors paginated

query Parameters
user-id
string

search users for the specified ID

user-name
string

filters users by the name (regexes possible)

email
string

filters users by the e-mail (regexes possible)

link-id