Skip to main content
API docs by Redocly

finoOS2 Documentation (v1.23.1)

Support: os.support@fino.run

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 Schema: application/json
access_token
string
expires_in
integer
not-before-policy
integer
scope
string
session_state
string
token_type
string

Response samples

Content type
application/json
{
}

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 Schema: application/json
object (users.PagedMetaInfo)
Array of objects (users.UserInfo)

Response samples

Content type
application/json
{
}

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.

expiresIn
integer

Optional, can be set to automatically delete a user. Value is given in seconds. Needs to be higher than 86400 (1 day). Expired Users are removed once a day around 2 AM.

name
string

Optional Name of the created user. Formatting should be user's full name, including optional titles, first name, middle name, and last name. Must consist of words separated by whitespace. No underscores, digits, or concatenated words.

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,renter-information]. Only the given scopes will be accessible and calculated for the created user.

Responses

Response Schema: application/json
object (users.MetaInfo)
object (users.UserInfo)

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

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 Schema: application/json
advisorID
string

AdvisorID only for cockpit users.

advisorIDs
Array of strings

AdvisorIDs only for cockpit users.

createdAt
string

Timestamp of the user creation.

customUserID
string

Customized identifier for the user.

Array of objects (users.GetUserByCustomIDDuplicates)

Duplicates are present if a single customUserID was used multiple times for user creation.

id
string

UserID is the unique identifier for the user.

tenant
string

Tenant of the user.

type
string
Enum: "person" "company"

Type of the user.

Response samples

Content type
application/json
{
}

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

Response Schema: application/json
object (users.DeleteUserInfo)
deleted
Array of strings
failedToDelete
Array of strings
notFound
Array of strings

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

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.

Rate Limiting

This endpoint is rate limited. Every response includes headers describing your current quota:

Header Description
RateLimit-Limit Maximum requests per window
RateLimit-Remaining Requests remaining in the current window
RateLimit-Reset Seconds until the window resets
RateLimit-Policy Policy description, e.g. 100;w=60
X-RateLimit-Concurrent-Limit Maximum concurrent in-flight requests
X-RateLimit-Concurrent-Remaining Remaining concurrent slots
Retry-After On 429: seconds to wait before retrying

Inspecting the quota without consuming a request

Append ?inspect=rateLimit to the URL to get the current quota as a JSON body without counting against your limit. Useful for clients that want to check available capacity before submitting a large batch.

When the quota is exhausted, the endpoint returns 429 Too Many Requests with a response body matching the inspect shape (plus type and message). Use Retry-After or resetSeconds to schedule a retry.

query Parameters
inspect
string
Value: "rateLimit"

Set to rateLimit to return the current rate limit quota as a JSON body without consuming a request. When set, the endpoint responds with 200 and the InspectResponse body instead of processing the import.

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

Response Schema: application/json
object

Concurrency is the concurrency section, only present when concurrency limits are active.

endpoint
string

Endpoint is the path that this quota applies to.

object

RateLimit is the rate (requests-per-window) section, only present when rate limiting is active.

status
string

Status is the current state: "ok" or "throttled".

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

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 Schema: application/json
object (users.MetaInfo)
object (users.UserInfo)

Response samples

Content type
application/json
{
}

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
{
}

Update User

Updates a user.

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

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. Formatting should be user's full name, including optional titles, first name, middle name, and last name. Must consist of words separated by whitespace. No underscores, digits, or concatenated words.

Responses

Response Schema: application/json
object (users.MetaInfo)
object (users.UserInfo)

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

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
{
}

Response samples

Content type
application/json
{
}

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
{
}

Banking-Connect

Get Synchronization Status Paginated

Scope: banking

This system call retrieves the synchronization status of the connected bank logins across all users. Is still synchronized automatically in background or if you need to Trigger a Synchronization manually

query Parameters
page
string

page min 1 default 1

page-size
string

page size min 10, max 1000, default 10

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

The authorization token

TenantID
string

The client's tenant

Responses

Response Schema: application/json
object

Pagination details for the user information list.

Array of objects (banking.UserInformation)

List of user information objects.

Response samples

Content type
application/json
{
}

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
boolean

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
boolean

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.

lang
string

Is used to set the current used language (en, de).

embedded
boolean

Is used to customize the ui of UBA to improve visualization when uba ui is embedded in an app within a webview. It will hide the footer for example.

hideHeader
boolean

Is used to hide the headerbar in uba, for example when using iFrames.

hideAbort
boolean

Hides the exit button to abort the current uba process and to be directed to the exit or fallback URL.

preselectAccountTypes
string

Is used to preselect the account types (comma separated). For example: GIRO,TAGESGELD.

skipAccountSelect
boolean

Is used to skip the selection of the received bank accounts. When it's true, all given accounts will automatically be selected.

autoSelectSingleAccount
boolean

Select a single bank account automatically to skip account selection.

skipAccountTypes
boolean

Is used to skip the selection of the account types.

theme.primaryColor
string

Define the primary color of our Banking UI represented as a hex color code. For example: #FF0000.

theme.headerBackgroundColor
string

Define the background color of the header in our Banking UI represented as a hex color code. For example: #FF0000.

theme.headerColor
string

Define the color of the text in the header in our Banking UI represented as a hex color code. For example: #FF0000.

theme.logo
string

Define the logo of our Banking UI. The logo must be a URL.

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 (enum.BankAccountType)
Items Enum: "GIRO" "TAGESGELD" "SPARBUCH" "KREDIT_KARTE" "KREDIT_KONTO" "DEPOT" "PAYPAL" "FESTGELD" "KREDITDARLEHEN" "FONDSDEPOT" "BAUSPAREN" "VERSICHERUNG" "UNKNOWN"

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

recurring
boolean
Default: false

Enables automatic synchronization of this bank login. Requires storeSecrets=true to take effect.

redirectURL
required
string

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

storeSecrets
boolean
Default: true

Persists the bank login credentials. Must be true together with recurring=true for automatic synchronization to run; otherwise transactions only refresh when a synchronization session is triggered manually. Defaults to true if omitted.

Responses

Response Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
redirectURL
string

The redirect URL to our Banking Management UI

Request samples

Content type
application/json
{}

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
{
}

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 Schema: application/json
Array
active
boolean

Indicates if automatic background synchronization is activated.

bankLoginId
string

Identifier of the bank-login.

lastSynchronization
integer

UNIX timestamp (in seconds) of the last successful synchronization.

status
string
Enum: "OK" "SCA_REQUIRED" "SYNC_FAILED" "DEPRECATED_INTERFACE" "DEPRECATED_PROVIDER"

Current status of the bank login.

userId
string

User identifier.

Response samples

Content type
application/json
[
]

Delete Login

Scope: banking

Deletes a connected bank login of the user. This will also delete all stored banking data associated with this login such as his accounts and the respective transactions.

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
{
}

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
boolean

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
boolean

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
boolean

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.

lang
string

Is used to set the current used language (en, de).

embedded
boolean

Is used to customize the ui of UBA to improve visualization when uba ui is embedded in an app within a webview. It will hide the footer for example.

hideHeader
boolean

Is used to hide the headerbar in uba, for example when using iFrames.

hideAbort
boolean

Hides the exit button to abort the current uba process and to be directed to the exit or fallback URL.

preselectAccountTypes
string

Is used to preselect the account types (comma separated). For example: GIRO,TAGESGELD.

skipAccountSelect
boolean

Is used to skip the selection of the received bank accounts. When it's true, all given accounts will automatically be selected.

autoSelectSingleAccount
boolean

Select a single bank account automatically to skip account selection.

skipAccountTypes
boolean

Is used to skip the selection of the account types.

readonly
boolean

Is used to set the Banking UI in read-only mode. The user cannot perform any actions but can only view their connected accounts

theme.primaryColor
string

Define the primary color of our Banking UI represented as a hex color code. For example: #FF0000.

theme.headerBackgroundColor
string

Define the background color of the header in our Banking UI represented as a hex color code. For example: #FF0000.

theme.headerColor
string

Define the color of the text in the header in our Banking UI represented as a hex color code. For example: #FF0000.

theme.logo
string

Define the logo of our Banking UI. The logo must be a URL.

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 (enum.BankAccountType)
Items Enum: "GIRO" "TAGESGELD" "SPARBUCH" "KREDIT_KARTE" "KREDIT_KONTO" "DEPOT" "PAYPAL" "FESTGELD" "KREDITDARLEHEN" "FONDSDEPOT" "BAUSPAREN" "VERSICHERUNG" "UNKNOWN"

List of account types to be shown during login

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

Response Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
redirectURL
string

The redirect URL to our Banking Management UI

Request samples

Content type
application/json
{}

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
  • 206: 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.
    Note: The specified query parameters only apply if the user is redirected back to our Banking UI (409, 422 and 451).
path Parameters
user-id
required
string

The user id of the finoOS user

query Parameters
lang
string

Is used to set the current used language (en, de).

embedded
boolean

Is used to customize the ui of UBA to improve visualization when uba ui is embedded in an app within a webview. It will hide the footer for example.

hideHeader
boolean

Is used to hide the headerbar in uba, for example when using iFrames.

hideAbort
boolean

Hides the exit button to abort the current uba process and to be directed to the exit or fallback URL.

preselectAccountTypes
string

Is used to preselect the account types (comma separated). For example: GIRO,TAGESGELD.

skipAccountSelect
boolean

Is used to skip the selection of the received bank accounts. When it's true, all given accounts will automatically be selected.

autoSelectSingleAccount
boolean

Select a single bank account automatically to skip account selection.

skipAccountTypes
boolean

Is used to skip the selection of the account types.

theme.primaryColor
string

Define the primary color of our Banking UI represented as a hex color code. For example: #FF0000.

theme.headerBackgroundColor
string

Define the background color of the header in our Banking UI represented as a hex color code. For example: #FF0000.

theme.headerColor
string

Define the color of the text in the header in our Banking UI represented as a hex color code. For example: #FF0000.

theme.logo
string

Define the logo of our Banking UI. The logo must be a URL.

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

triggerChallenge
boolean

If true, a challenge might be triggered. Default true

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
}

Banking-General

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 Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
Array of objects (banking.AccountResponse)
Array
accountId
string

Internal AccountID

accountNumber
string

Domestic account number

balance
number

Current account balance

bankCode
string

The account code associated with the bank account

bankLoginId
string

Login ID for accessing the bank account. May be empty for uploaded accounts

bankName
string

The name of the bank

bic
string

Bank Identifier Code

creditLine
number

Current credit line, if available. !DEPRECATED!

currency
string

ISO 4217 currency code (otherwise OTHER if unsupported)

iban
string

Iban identifier of account

icon
string

URL to the bank's icon/image

monthlySpendingLimit
number

Monthly spending limit, if applicable. !DEPRECATED!

name
string

Name of account

object

Overdraft, if available

owner
string

Name of account owner

Array of objects (banking.Security)

List of securities of account

Array of objects (banking.StandingOrder)

Current list of standing orders related to account

supportedPayments
Array of strings

Array containing types of supported payments

Array of objects (banking.TransactionResponse)

List of transactions related to account

type
string
Enum: "GIRO" "TAGESGELD" "SPARBUCH" "KREDIT_KARTE" "KREDIT_KONTO" "DEPOT" "PAYPAL" "FESTGELD" "KREDITDARLEHEN" "FONDSDEPOT" "BAUSPAREN" "VERSICHERUNG" "UNKNOWN"

Type of account

Response samples

Content type
application/json
{
}

Delete Accounts

Scope: banking

Delete an account by multi account ids

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

IDs
Array of strings

Responses

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

Delete Account

Scope: banking

Delete an account by the account id

path Parameters
user-id
required
string

The user id of the finoOS user

account-id
required
string

ID of the account to delete

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
{
}

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

Response Headers
Content-Disposition
string

form-data; name=_kontoauszug.pdf; filename="_kontoauszug.pdf

Content-Length
string

length of pdf file

Content-Type
string

application/pdf

Response Schema:
string <binary>

Response samples

Content type
No sample

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 Schema: application/json
correlationID
string

Unique Process-ID

correlationTimestamp
string

A timestamp in RFC3339 format when the Process was started

Response 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

Response Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
alreadyConnected
boolean

Indicates whether the bank login has been already added

bankLoginId
string

BankLoginId the id of the bank login credentials

Array of objects (banking.BankLoginOutputSuccess)
status
string
Enum: "success" "challenge"

The status of the bank login

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

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

accountId
string

AccountId is used to filter the transactions for the matching account.

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

The authorization token

TenantID
string

The client's tenant

Responses

Response Schema: application/json
Array
accountId
string

ID of the account to which the transaction belongs

amount
number

The amount of the transaction

bookingDate
integer

Unix timestamp when an entry is posted to an account

bookingText
string

Description or text associated with the transaction

currency
string

ISO 4217 currency code (otherwise OTHER if unsupported)

differentCreditor
string

Person/Company which will receive the money

differentDebitor
string

Person/Company who sends the money

eref
string

The unique reference number. If omitted, this is checked in the purpose

merchantCategoryCode
string or null

Four-digit indicator used to classify a business by the types of goods or services it provides

mref
string

The mandate reference number. If omitted, this is checked in the purpose

object

Information about the payment partner. Can be a person, POS system or even a payment service such as PayPal

purpose
string

Purpose or reason for the transaction

sepaPurposeCode
string

Four-digit indicator used to classify payments

transactionCode
integer

Unique identifier assigned to a transaction

transactionId
string

The unique ID of the transaction

valueDate
integer

Unix timestamp when the money is actually available

Response samples

Content type
application/json
[
]

Banking-Money-Transfer

Money Transfer

Scope: banking, banking-payment

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

query Parameters
lang
string

Is used to set the current used language (en, de).

embedded
boolean

Is used to customize the ui of UBA to improve visualization when uba ui is embedded in an app within a webview. It will hide the footer for example.

hideHeader
boolean

Is used to hide the headerbar in uba, for example when using iFrames.

hideAbort
boolean

Hides the exit button to abort the current uba process and to be directed to the exit or fallback URL.

theme.primaryColor
string

Define the primary color of our Banking UI represented as a hex color code. For example: #FF0000.

theme.headerBackgroundColor
string

Define the background color of the header in our Banking UI represented as a hex color code. For example: #FF0000.

theme.headerColor
string

Define the color of the text in the header in our Banking UI represented as a hex color code. For example: #FF0000.

theme.logo
string

Define the logo of our Banking UI. The logo must be a URL.

autoRedirectAfterPayment
integer

Is used to automatically redirect the user to the redirect URL after the payment is done. Value is given in seconds and autoRedirectAfterPayment=0 directly redirects the user.

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

Response Schema: application/json
paymentId
string

Unique ID of the payment

sessionId
string

ID of current session related to user

status
string
Enum: "success" "challenge"

Status of the payment

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
}

Get Money Transfer

Scope: banking, banking-payment

Returns a detailed response for an existing MoneyTransfer with the executed payments and the current status OPEN indicates that the payment has been created in the system but has not yet been submitted to the bank. PENDING indicates that the payment has been requested at the bank but is not yet confirmed. SUCCESSFUL indicates that the payment has been successfully initiated. NOT_SUCCESSFUL indicates that the payment initiation was unsuccessful. DISCARDED indicates that the payment was discarded, either due to another payment being requested for the same account before initiation or because the user aborted the process.

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 Schema: application/json
Array of objects (banking.MoneyTransferDetails)
status
string
Enum: "OPEN" "PENDING" "SUCCESSFUL" "NOT_SUCCESSFUL" "DISCARDED"

The status of the payment

Response samples

Content type
application/json
{
}

Banking-Upload

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
Array (non-empty)
accountId
required
string

Internal AccountID

accountNumber
required
string

Domestic account number

balance
number

Current account balance

bankCode
string

The account number associated with the bank account

bankName
string

The name of the bank

bic
string

Bank Identifier Code

creditLine
number

Current credit line, if available. !DEPRECATED!

currency
string

ISO 4217 currency code

iban
string

Iban identifier of account

icon
string

URL to the bank's icon/image

monthlySpendingLimit
number

Monthly spending limit, if applicable. !DEPRECATED!

name
string

Name of account

object

Overdraft, if available

owner
string

Name of account owner

Array of objects (banking.Security)

Account securities if the account type is DEPOT

Array of objects (banking.StandingOrder)

Current list of standing orders related to account

Array of objects (banking.TransactionRequest)

List of transactions related to account

type
string
Enum: "GIRO" "TAGESGELD" "SPARBUCH" "KREDIT_KARTE" "KREDIT_KONTO" "DEPOT" "PAYPAL" "FESTGELD" "KREDITDARLEHEN" "FONDSDEPOT" "BAUSPAREN" "VERSICHERUNG" "UNKNOWN"

Type of account

Responses

Response Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
userId
string

The user id of the finoOS user

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

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
Array
accountId
required
string

Internal AccountID

accountNumber
required
string

Domestic account number

balance
number

Current account balance

bankCode
string

The account number associated with the bank account

bankName
string

The name of the bank

bic
string

Bank Identifier Code

creditLine
number

Current credit line, if available. !DEPRECATED!

currency
string

Account currency ISO 4217 (unsupported=OTHER)

iban
string

Iban identifier of account

icon
string

URL to the bank's icon/image

monthlySpendingLimit
number

Monthly spending limit, if applicable. !DEPRECATED!

name
string

Name of account

object

Overdraft, if available

owner
string

Name of account owner

supportedPayments
Array of strings

Array containing types of supported payments

Array of objects

List of transactions related to account

type
string
Value: "GIRO TAGESGELD SPARBUCH KREDIT_KARTE KREDIT_KONTO DEPOT PAYPAL FESTGELD KREDITDARLEHEN FONDSDEPOT BAUSPAREN VERSICHERUNG UNKNOWN"

Type of account

Responses

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

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
Array
accountId
required
string

ID of the account to which the transaction belongs

amount
number

The amount of the transaction

bookingDate
integer [ 0 .. 2147483646 ]

Unix timestamp when an entry is posted to an account

bookingText
string

Description or text associated with the transaction

currency
string

ISO 4217 Alpha 3 currency code

differentCreditor
string

Person/Company which will receive the money

differentDebitor
string

Person/Company who sends the money

eref
string

The unique reference number. If omitted, this is checked in the purpose

merchantCategoryCode
string

Four-digit indicator used to classify a business by the types of goods or services it provides

mref
string

The mandate reference number. If omitted, this is checked in the purpose

object

Information about the payment partner. Can be a person, POS system or even a payment service such as PayPal

purpose
string

Purpose or reason for the transaction

sepaPurposeCode
string

Four-digit indicator used to classify payments

transactionCode
integer

Unique identifier assigned to a transaction

transactionId
required
string

The unique ID of the transaction

valueDate
integer [ 0 .. 2147483646 ]

Unix timestamp when the money is actually available

Responses

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

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)
Array
amount
number

The amount of the transaction

bookingDate
integer [ 0 .. 2147483646 ]

Unix timestamp when an entry is posted to an account

bookingText
string

Description or text associated with the transaction

currency
string

ISO 4217 currency code

differentCreditor
string

Ultimate creditor (person or company) in case paymentPartner is a payment service, POS, etc

differentDebitor
string

Ultimate debitor (person or company) in case paymentPartner is a payment service, POS, etc

eref
string

The unique reference number. If omitted, this is checked in the purpose

merchantCategoryCode
string

Four-digit indicator used to classify a business by the types of goods or services it provides

mref
string

The mandate reference number. If omitted, this is checked in the purpose

object

Information about the payment partner. Can be a person, POS system or even a payment service such as PayPal

purpose
string

Purpose or reason for the transaction

sepaPurposeCode
string

Four-digit indicator used to classify payments

transactionCode
integer

Unique identifier assigned to a transaction

transactionId
required
string

The unique ID of the transaction. Is used internally to identify duplicates.

valueDate
integer [ 0 .. 2147483646 ]

Unix timestamp when the money is actually available

Responses

Response Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
transactionsAdded
integer

Count of transactions that were added to the account

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

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
{
}

Response samples

Content type
application/json
{
}

Categorization

FinoOS Categorization services categorizes Banking Transactions provided through finoOS Banking Services. Different Endpoints allow to get the whole Transactions including the categorization or explicitly the categorization tagging. Required scope is categorization.

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. Maximum pageSize is 1000.

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

accountId
string

optional: If provided, the response will only contain entries for the corresponding account.

includeTransactions
boolean

optional: If true, the response will also include the original transaction for each categorization entry. Default: false

lang
string

optional: If set entries will include the LocalizedTag Field with the requested language. Supported languages are: en, de

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

The authorization token

TenantID
string

The client's tenant

Responses

Response Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
Array of objects (categorization.CategorizationEntry)

Categorization holds tagging information for transactions

object

MetaData pagination response meta data

Response samples

Content type
application/json
{
}

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 Schema: application/json
correlationID
string

Unique Process-ID

correlationTimestamp
string

A timestamp in RFC3339 format when the Process was started

Response samples

Content type
application/json
{
}

Get Categorization by IDs

Returns a list or current tags for the requested transactions. Limited to 1000 per request.

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. Maximum pageSize is 1000.

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

accountId
string

optional: If provided, the response will only contain entries for the corresponding account.

includeTransactions
boolean

optional: If true, the response will also include the original transaction for each categorization entry. Default: false

lang
string

optional: If set entries will include the LocalizedTag Field with the requested language. Supported languages are: en, de

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

transactionIds
required
Array of strings

Responses

Response Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
Array of objects (categorization.CategorizationEntry)

Categorization holds tagging information for transactions

Array
accountId
string

AccountID is the unique ID of the transaction

creationDate
string

CreationDate timestamp of last change to the tagging of this transaction

descriptiveTag
string

DescriptiveTag returns the main descriptive tag for the transaction, e.g. for tags ["spending","fix","insurance","insurance_legal"] it is "insurance_legal"

localizedTag
string or null

LocalizedTag returns the localized string of the DescriptiveTag. Field is optional and only returned if language parameter is set in the request

tags
Array of strings

Tags of the transaction

object or null

Transaction, only included if requested via ?includeTransaction=true

transactionId
string

TransactionID is the unique ID of the transaction

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

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.

Please note that these attributes and advanced-attributes describe the “how” of a transaction and are less meaningful for what a payment was made for. For more detailed information about the purpose of a payment, the category tags (tags with level 2 and higher) are much more helpful.

In addition, transactions can have further attributes (level 0 tags) that provide additional information, for example:

earning / spending and card_payment: card payment
earning / spending and privacy: payments with particularly sensitive data
earning / spending and standing_order: standing order
earning / spending and SEPA_one-off: One-off SEPA direct debit
earning / spending and direct_debit: Direct debit
earning / spending and foreign: Payment to or from abroad
earning / spending and remittance_card: Refund of a card payment

Get Categorization Tree

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

query Parameters
type
required
string
Enum: "company" "person"

The type of the categorization tree

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

The authorization token

Responses

Response Schema: application/json
object

Nodes is the root node of the tree

treeVersionHash
string

TreeVersionHash is the hash of the tree

type
string

Type is the type of the description (company or person)

Response samples

Content type
application/json
{
}

Get Categorization Description

Returns the description of tags

query Parameters
type
required
string
Enum: "company" "person"

The type of the categorization tree

lang
required
string
Enum: "en" "de"

The language of the categorization description

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

The authorization token

Responses

Response Schema: application/json
Array of objects (categorization.Description)

DescriptionList is the list of descriptions

descriptionVersionHash
string

DescriptionVersionHash is the hash of the description to cross-check if the description is up-to-date

language
string

Language is the language of the description

type
string

Type is the type of the description (company or person)

Response samples

Content type
application/json
{
}

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

Scope: 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 Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
object (account_detection.AccountsOverview)
Array of objects (account_detection.Account)
Array of objects (account_detection.CreditCard)

Response samples

Content type
application/json
{
}

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 Schema: application/json
correlationID
string

Unique Process-ID

correlationTimestamp
string

A timestamp in RFC3339 format when the Process was started

Response samples

Content type
application/json
{
}

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 Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
Array of objects (accounthistory.AccountHistory)
Array
object (accounthistory.MiniAccount)
Array of objects (accounthistory.DailyAccountBalance)
object (accounthistory.DailyAccountBalance)

Response samples

Content type
application/json
{
}

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 Schema: application/json
correlationID
string

Unique Process-ID

correlationTimestamp
string

A timestamp in RFC3339 format when the Process was started

Response samples

Content type
application/json
{
}

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.

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 Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
Array
object

Additional information about the contract (currently insurance numbers only)

amount
number

The amount of the contract

amountConsistency
string

How consistent the amount of the contract is

attributes
Array of strings

Attributes the contracts transaction(s) have like privacy or containsInternalBooking

category
string

The contract category

contractId
string

A generated unique id to identify the contract

object

The contract partner

duration
integer

The duration in days

interval
string
Enum: "NONE" "WEEKLY" "BIWEEKLY" "MONTHLY" "BIMONTHLY" "QUARTERLY" "SEMIANNUALLY" "ANNUALLY"

The interval of the contract transactions

isActive
boolean

If the contract is still active (still booked on the account)

mref
string or null

The mref of the contract

nextBookingDate
string

A forecast when the next booking will take place

nextBookingRange
Array of strings

A forecast range when the next booking will take place

Array of objects (contracts.Transaction)

The transactions connected to the contract

Response samples

Content type
application/json
[
]

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 Schema: application/json
correlationID
string

Unique Process-ID

correlationTimestamp
string

A timestamp in RFC3339 format when the Process was started

Response samples

Content type
application/json
{
}

Person-Income

Get Income

At least one of the scopes: person-income-salary, person-income-pension, person-income-child-benefit, person-income-parental-allowance, person-income-investment, person-income-loan, person-income-rental, person-income-alimony, person-income-self-employment or person-income-other

path Parameters
user-id
required
string

The user id of the finoOS user

query Parameters
months
integer

number of months from current date to return income information (default: maximum available timeframe)

includeCurrentMonth
boolean

whether to include the current month in the response (default: false)

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

The authorization token

TenantID
string

The client's tenant

Responses

Response Schema: application/json
object or null

Alimony income data

object or null

Child benefit income data

object or null

Investment income data

object or null

Loan income data

object

Timespan for which the income analysis has been performed

object or null

Other income data

object or null

Parental allowance income data

object or null

Pension income data

object or null

Rental income data

object or null

Salary income data

object or null

Self-employment income data

Response samples

Content type
application/json
{
}

Get Correlation

At least one of the scopes: person-income-salary, person-income-pension, person-income-child-benefit, person-income-parental-allowance, person-income-investment, person-income-loan, person-income-rental, person-income-alimony, person-income-self-employment or person-income-other

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 Schema: application/json
correlationID
string

Unique Process-ID

correlationTimestamp
string

A timestamp in RFC3339 format when the Process was started

Response samples

Content type
application/json
{
}

Person-Spending

Get Spending

At least one of the scopes: person-spending-rent, person-spending-investment, person-spending-insurance, person-spending-credit, person-spending-credit-card or person-spending-other

path Parameters
user-id
required
string

The user id of the finoOS user

query Parameters
months
integer

number of months from current date to return spending information (default: maximum available timeframe)

includeCurrentMonth
boolean

whether to include the current month in the response (default: false)

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

The authorization token

TenantID
string

The client's tenant

Responses

Response Schema: application/json
object or null

Credit card spending data

object or null

Credit spending data

object or null

Insurance spending data

object or null

Investment spending data

object

Timespan for which the income analysis has been performed

object or null

Other spending data

object or null

Rent spending data

Response samples

Content type
application/json
{
}

Get Correlation

At least one of the scopes: person-spending-rent, person-spending-investment, person-spending-insurance, person-spending-credit, person-spending-credit-card or person-spending-other

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 Schema: application/json
correlationID
string

Unique Process-ID

correlationTimestamp
string

A timestamp in RFC3339 format when the Process was started

Response samples

Content type
application/json
{
}

Person-Risk

Get Risk

At least one of the scopes: person-risk-backdebit, person-risk-garnishment, person-risk-collection, person-risk-gambling, person-risk-overdraft-amount

path Parameters
user-id
required
string

The user id of the finoOS user

query Parameters
months
integer

number of months from current date to return risk information (default: maximum available timeframe)

includeCurrentMonth
boolean

whether to include the current month in the response (default: false)

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

The authorization token

TenantID
string

The client's tenant

Responses

Response Schema: application/json
Array of objects or null (risk.RiskFactor)

Backdebit risk factors

Array of objects or null (risk.RiskFactor)

Collection risk factors

Array of objects or null (risk.RiskFactor)

Gambling risk factors

Array of objects or null (risk.RiskFactor)

Garnishment risk factors

object

Timespan for which the income analysis has been performed

Array of objects or null (risk.OverdraftAmount)

Overdraft amount risk factors

Response samples

Content type
application/json
{
}

Get Correlation

At least one of the scopes: person-risk-backdebit, person-risk-garnishment, person-risk-collection, person-risk-gambling, person-risk-overdraft-amount

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 Schema: application/json
correlationID
string

Unique Process-ID

correlationTimestamp
string

A timestamp in RFC3339 format when the Process was started

Response samples

Content type
application/json
{
}

Person-Household-Budget

Get Household Budget

Scope: person-household-budget

Returns the household budget analysis for the given user.

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 Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
balance
number

Balance is MonthlyIncome.Total - MonthlySpending.Total

object

MonthlyIncome represents the average monthly income breakdown

object

MonthlySpending represents the average monthly spending breakdown

object

timespan for which the income analysis has been performed

Response samples

Content type
application/json
{
}

Get Correlation

Scope: person-household-budget

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 Schema: application/json
correlationID
string

Unique Process-ID

correlationTimestamp
string

A timestamp in RFC3339 format when the Process was started

Response samples

Content type
application/json
{
}

Person-Adult-Check

Get Adult Check

scope: person-adult-check

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 Schema: application/json
object

adult check decision and indicators

object

timespan for which the adult check analysis has been performed

Response samples

Content type
application/json
{
}

Get Correlation

scope: person-adult-check

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 Schema: application/json
correlationID
string

Unique Process-ID

correlationTimestamp
string

A timestamp in RFC3339 format when the Process was started

Response samples

Content type
application/json
{
}

Person-Living-Situation

Get Living Situation

scope: person-living-situation

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 Schema: application/json
object

The family situation of the account owner, including number of children and related financial information

object

The housing rent status of the account owner

object

The mobility situation of the account owner, including number of cars and related financial information

object

Timespan for which the income analysis has been performed

object

The property ownership status of the account owner

Response samples

Content type
application/json
{
}

Get Correlation

scope: person-living-situation

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 Schema: application/json
correlationID
string

Unique Process-ID

correlationTimestamp
string

A timestamp in RFC3339 format when the Process was started

Response samples

Content type
application/json
{
}

Renter-Information

This Module returns a users salary and rental information. Also returns account owner name for identity check.

Get Renter Information

Scope: renter-information

Returns a users information of salary, self-employment, and rental with a default timeframe of the account data we received.

path Parameters
user-id
required
string

The user id of the finoOS user

query Parameters
months
integer

number of months from current date to return salary, self-employment, and rental information (default: maximum available timeframe)

header Parameters
Authorization
required
string

The authorization token

TenantID
string

The client's tenant

Responses

Response Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
connectedAccounts
integer

Number of connected accounts

Array of objects (renter_information.SalaryTransaction)

FallbackIncome contains transactions that are not recognised as salary but might be income related

Array of objects (renter_information.RentalTransaction)

FallbackRental contains transactions that are not recognised as rental but might be rent related

object

Identity information

observedMonths
integer

Number of months the data is based on

object

Other income information

object

Rental information

object

Salary information

object

SelfEmployment information

Response samples

Content type
application/json
{
}

Get Correlation

Scope: renter-information

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 Schema: application/json
correlationID
string

Unique Process-ID

correlationTimestamp
string

A timestamp in RFC3339 format when the Process was started

Response samples

Content type
application/json
{
}

Company-Credits

Get Credits

Scope: company-credits

Returns credits information for the given user/company

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 Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
available
boolean
average
number
Array of objects (company.ContractSmall)
current
number
median
number
Array of objects (company.MonthlyOverview)
object (company.ObservedTimespan)

Response samples

Content type
application/json
{
}

Get Credits Correlation

Scope: company-credits Returns correlation details for the credits calculation

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 Schema: application/json
correlationID
string

Unique Process-ID

correlationTimestamp
string

A timestamp in RFC3339 format when the Process was started

Response samples

Content type
application/json
{
}

Company-Customer-Supplier

Get CustomersSuppliers

Scope: company-customer-supplier

Returns customers suppliers information for the given user/company

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 Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
object (company.CompanyPartner)
object (company.ObservedTimespan)
object (company.CompanyPartner)

Response samples

Content type
application/json
{
}

Get CustomersSuppliers Correlation

Scope: company-customer-supplier

Returns correlation details for the customers suppliers calculation

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 Schema: application/json
correlationID
string

Unique Process-ID

correlationTimestamp
string

A timestamp in RFC3339 format when the Process was started

Response samples

Content type
application/json
{
}

Company-Foreign-Payments

Get ForeignSales

Scope: company-foreign-payment

Returns foreign sales information for the given user/company

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 Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
Array of objects (company.ForeignSalesEntry)
object (company.ObservedTimespan)
object (company.ForeignSalesOverview)

Response samples

Content type
application/json
{
}

Get ForeignSales Correlation

Scope: company-foreign-payment

Returns correlation details for the foreign sales calculation

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 Schema: application/json
correlationID
string

Unique Process-ID

correlationTimestamp
string

A timestamp in RFC3339 format when the Process was started

Response samples

Content type
application/json
{
}

Company-Insurances

Get Insurances

Scope: company-insurance

Returns insurances information for the given user/company

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 Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
available
boolean
average
number
Array of objects (company.ContractSmall)
current
number
median
number
Array of objects (company.MonthlyOverview)
object (company.ObservedTimespan)

Response samples

Content type
application/json
{
}

Get Insurances Correlation

Scope: company-insurance

Returns correlation details for the insurances calculation

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 Schema: application/json
correlationID
string

Unique Process-ID

correlationTimestamp
string

A timestamp in RFC3339 format when the Process was started

Response samples

Content type
application/json
{
}

Company-Internal-Bookings

Get InternalBookings

Scope: company-internal-booking

Returns internal bookings information for the given user/company

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 Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
available
boolean
average
number
Array of objects (company.ContractSmall)
current
number
median
number
Array of objects (company.MonthlyOverview)
object (company.ObservedTimespan)

Response samples

Content type
application/json
{
}

Get InternalBookings Correlation

Scope: company-internal-booking

Returns correlation details for the internal bookings calculation

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 Schema: application/json
correlationID
string

Unique Process-ID

correlationTimestamp
string

A timestamp in RFC3339 format when the Process was started

Response samples

Content type
application/json
{
}

Company-Investments

Get Investments

Scope: company-investment

Returns investments information for the given user/company

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 Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
available
boolean
average
number
Array of objects (company.ContractSmall)
current
number
median
number
Array of objects (company.MonthlyOverview)
object (company.ObservedTimespan)

Response samples

Content type
application/json
{
}

Get Investments Correlation

Scope: company-investment

Returns correlation details for the investments calculation

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 Schema: application/json
correlationID
string

Unique Process-ID

correlationTimestamp
string

A timestamp in RFC3339 format when the Process was started

Response samples

Content type
application/json
{
}

Company-Liquidity

Get Liquidity

Scope: company-liquidity

Returns liquidity information for the given user/company

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 Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
Array of objects (company.AccountLiquidity)

Liquidity information on each single account

object (company.ObservedTimespan)
object

Overall liquidity information through all accounts

Response samples

Content type
application/json
{
}

Get Liquidity Correlation

Scope: company-liquidity

Returns correlation details for the liquidity calculation

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 Schema: application/json
correlationID
string

Unique Process-ID

correlationTimestamp
string

A timestamp in RFC3339 format when the Process was started

Response samples

Content type
application/json
{
}

Company-Risk

Get Risk

Scope: company-risk

Returns risk information for the given user/company

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 Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
Array of objects (company.AccountRisk)

Slice of AccountRisk

object (company.ObservedTimespan)

Response samples

Content type
application/json
{
}

Get Risk Correlation

Scope: company-risk

Returns correlation details for the risk calculation

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 Schema: application/json
correlationID
string

Unique Process-ID

correlationTimestamp
string

A timestamp in RFC3339 format when the Process was started

Response samples

Content type
application/json
{
}

Company-Staff

Get Staff

Scope: company-staff

Returns staff information for the given user/company

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 Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
object (company.Employees)
object (company.ObservedTimespan)
object (company.Salary)
object (company.Sources)

Response samples

Content type
application/json
{
}

Get Staff Correlation

Scope: company-staff

Returns correlation details for the staff calculation

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 Schema: application/json
correlationID
string

Unique Process-ID

correlationTimestamp
string

A timestamp in RFC3339 format when the Process was started

Response samples

Content type
application/json
{
}

Company-Top-Categories

Get TopCategories

Scope: company-top-category

Returns top categories information for the given user/company

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 Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
Array of objects (company.Graph)
object (company.ObservedTimespan)

Response samples

Content type
application/json
{
}

Get TopCategories Correlation

Scope: company-top-category

Returns correlation details for the top categories calculation

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 Schema: application/json
correlationID
string

Unique Process-ID

correlationTimestamp
string

A timestamp in RFC3339 format when the Process was started

Response samples

Content type
application/json
{
}

Company-Cash

Get Cashflow

Scope: company-cash

Returns the user's company cashflow information (overview + monthly breakdown)

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 Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
Array of objects (company.Monthly)
object (company.ObservedTimespan)
object (company.Overview)

Response samples

Content type
application/json
{
}

Get Cashflow Correlation

Scope: company-cash Returns correlation details for the cashflow calculation

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 Schema: application/json
correlationID
string

Unique Process-ID

correlationTimestamp
string

A timestamp in RFC3339 format when the Process was started

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 Schema: application/json
Array of objects (cockpit.ShortCockpit)
object (cockpit.MetaData)

Response samples

Content type
application/json
{
}

Get Recommendations paginated

Scope: cockpits Returns a paginated list of recommendations for multiple cockpits.

query Parameters
page
integer

the page number (default: 1 min: 1)

page-size
integer

ths page size (default: 100 min: 2 max: 500)

type
string

cockpit type (default: company)

since
string

timestamp filter to only return cockpits created after this timestamp

until
string

timestamp filter to only return cockpits created before this timestamp

only-meta
string

the response only contains meta information for the cockpits and not the raw result data

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

The authorization token

TenantID
string

The client's tenant

Responses

Response Schema: application/json
Array of objects (recommendations.Cockpit)

Array of Cockpit Recommendations

object (recommendations.MetaData)

Response samples

Content type
application/json
{
}

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 Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
object (cockpit.AccountDataResponse)
object (cockpit.CaaProcessed)
object

Cashflow

object

Info about non salary collective payments

Array of objects (cockpit.Contract)

Found and analyzed contracts

createdAt
string
Array of objects (cockpit.Contract)

Found and analyzed credits

Array of objects (cockpit.TopEntity)

Found and analyzed top customers

object (cockpit.Facts)
Array of objects (cockpit.Graph)
Array of objects (cockpit.Contract)

Found and analyzed insurances

Array of objects (cockpit.Contract)
object

Liquidity (similar to PK Liquidity)

object (cockpit.ObservationPeriod)
Array of objects (cockpit.Contract)

"Wertpapiere"

Array of objects (cockpit.Security)

Found and analyzed securities

Array of objects (cockpit.TopEntity)

Found and analyzed top supplier

object

The tenant who initiated the cockpit

type
string

Type of the cockpit

object (cockpit.User)
version
string

Version of the cockpit

Response samples

Content type
application/json
{
}

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 Schema: application/json
correlationID
string

Unique Process-ID

correlationTimestamp
string

A timestamp in RFC3339 format when the Process was started

Response samples

Content type
application/json
{
}

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

Response Headers
Content-Disposition
string

attachment; filename=Cockpit_user-id.pdf

Content-Length
string

length of pdf file

Response Schema:
string <binary>

Response samples

Content type
No sample

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 Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
object

General account Information

object (cockpit.AccountHistories)
Array of objects (cockpit.Contract)

Found and analyzed contracts

createdAt
string
Array of objects (cockpit.Credit)

Found and analyzed credits

object (cockpit.HouseholdExpenditure)
object (cockpit.Income)
Array of objects (cockpit.Insurance)

Found and analyzed insurances

Array of objects (cockpit.Contract)
object (cockpit.Liquidity)
object (cockpit.ObservationPeriod)
object (cockpit.Overview)
Array of objects (cockpit.Contract)

"Wertpapiere"

Array of objects or null (cockpit.Security)

Found and analyzed securities

object (cockpit.Spending)
object

The tenant who initiated the cockpit

type
string

Type of the cockpit

object (cockpit.User)
version
string

Version of the cockpit

versionHash
string
object (cockpit.Wealth)

Response samples

Content type
application/json
{
}

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 Headers
Finoos-Correlation-Id
string

Unique Process-Id

Finoos-Correlation-Timestamp
string

A timestamp in RFC3339 format when the Process was started

Response Schema: application/json
Array of objects (recommendations.Recommendation)

Array of Recommendations

Array
advisorText
string

AdvisorText to be displayed with the recommendation text

data
any

RawData of the recommendation

dataModel
string

Data model declares type of model contained in data field. Can be 'contract'. Corresponding data model can be found in module documentation.

dataType
string

Type of data in RawData field. Can be 'array', 'object', 'simple' or 'null'

hyperlinkLabel
string

HyperlinkLabel label text to be displayed with the hyperlink

icon
string

Icon of the recommendation

id
string

ID of the recommendation

name
string

Name of the recommendation/rule

priority
string

Priority to display the recommendation

product
string

Product to which the recommendation belongs

showAdvisor
boolean

ShowAdvisor is intended for the role of an advisor

showCustomer
boolean

ShowCustomer is intended for the role of a customer

text
string

Display Text of the recommendation

textHyperlink
string

TextHyperlink to be displayed with the recommendation text

title
string

Display Title of the recommendation

Response samples

Content type
application/json
{
}

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
page
integer

The page number to retrieve. (default: 1)

page-size
integer

The number of items per page. (default: 100, min: 1, max: 1000)

user-id
string

search advisors for the specified ID

customer-advisor-id
string

filters advisors by the customer advisor ID (regexes possible)

user-name
string

filters advisors by the name (regexes possible)

email
string

filters advisors by the e-mail (regexes possible)

link-id
string

filters advisors by the link ID (regexes possible)

activated
boolean

filter advisors by activated or deactivated state (true,false). If omitted both activated or deactivated advisors are returned

since-last-activity
string

filters advisors by their last activity (inclusive)

until-last-activity
string

filters advisors by last activity (exclusive)

roles
Array of strings

filters advisors by their role. Possible values: employee, tenantadmin, tenant-manager

reportRoles
Array of strings

filters advisors by their report roles. Possible values: report, report-branch and report-tenant

reportAccess
boolean

Enable or disable access to the reports for the advisor

reportSend
boolean

Enable or disable sending e-mails with report links to the advisor

header Parameters
Authorization
required
string

The authorization token

TenantID
string

The client's tenant

Responses

Response Schema: application/json
object

MetaData contains the context about pagination

Array of objects (advisor.Advisor)

Users contains the actual users

Response samples

Content type
application/json
{
}

Create Advisor

Create advisor to manage cockpits

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

avatar
string

Avatar contains a picture of the advisor

object

Credentials of the user

customAdvisorID
string

CustomAdvisorID is the custom ID of the advisor

linkID
string

LinkID of the advisor which is optional

mail
string

Mail represents the e-mail the users uses to get f.e. the cockpits

name
string

Name represents the name of the advisor

onboardingMail
boolean

OnboardingMail

phoneNumber
string

PhoneNumber is an optional field representing the advisor phoneNumber

reportAccess
boolean

Enable or disable access to the reports for the advisor

reportInterval
string

ReportInterval defines in which intervals the advisor wants to receive a report

reportRole
string
Enum: "report" "report-branch" "report-tenant"

ReportRole represents the permissions the advisor has to view all or a subset or only own reports

reportSend
boolean

Enable or disable sending e-mails with report links to the advisor

role
required
string
Enum: "employee" "tenantadmin" "tenant-manager"

Role represents the permissions the advisor has to view all or a subset of cockpits

sendMail
boolean

SendMail notify advisor by email about every cockpit being created

type
string
Enum: "person" "company" "person-company" "company-person"

Type of the advisor determines landing page and preferred cockpit selection or even disabling of person or company cockpit type

welcomeMail
boolean

WelcomeMail

Responses

Response Schema: application/json
id
string

ID represents the unique identifier that is used to identify the advisor

linkID
string

LinkID is the link id by which a cockpit generate flow can be started

url
string

Url represents the link that the advisor can share with customers to generate cockpits.
To create a personalized individual link the url can be adjusted by following query parameters

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{}

Get Advisor

Returns one advisor

query Parameters
advisor-id
string

search advisor for the specified ID

header Parameters
Authorization
required
string

The authorization token

TenantID
string

The client's tenant

Responses

Response Schema: application/json
avatar
string

Avatar contains a picture of the advisor

customAdvisorID
string or null

CustomAdvisorID is the custom ID of the advisor

deactivated
boolean

If true advisor is deactivated

id
string

ID of the advisor

lastActivity
string

Time of last activity

linkID
string

LinkID of the advisor

logo
string

Logo represents the url to the tenant's logo

mail
string

Mail of the advisor

phoneNumber
string

Phone number of the advisor

primaryColor
string

PrimaryColor represents the primary color that is presented in the cockpit

reportAccess
boolean

Is access to the reports granted for the advisor

reportInterval
string

ReportInterval defines in which intervals the advisor wants to receive a report

reportRole
string
Enum: "report" "report-branch" "report-tenant"

ReportRole represents the permissions the advisor has to view all or a subset or only own reports

reportSend
boolean

Is sending reports enabled for the advisor

role
string
Enum: "employee" "tenantadmin" "tenant-manager"

Role of the advisor

sendMail
boolean

SendMail notify advisor by email about every cockpit being created

tenant
string

Tenant is the name of the tenant the advisor belongs to

tenantID
string

TenantID references the tenant the advisor belongs to

type
string
Enum: "person" "company" "person-company" "company-person"

Type of the advisor

url
string

URL represents the link that the advisor can share with customers to generate cockpits.
To create a personalized individual link the url can be adjusted by following query parameters

userName
string

UserName is the name of the advisor

Response samples

Content type
application/json
{}

Delete Advisor

Delete requested advisor

query Parameters
advisor-id
string

specified advisors ID for delete

header Parameters
Authorization
required
string

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
{
}

Patch Advisors

Returns patched advisor

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

avatar
string

Avatar contains a picture of the advisor

object

Credentials of the user

deactivated
boolean

Deactivated deactivates the advisor if set to true. advisor is active if the value is null or false

linkID
string

New LinkID of the advisor which is optional

mail
string

Mail represents the new e-mail the users uses to get f.e. the cockpits

name
string

Name represents the new name of the advisor

phoneNumber
string

PhoneNumber is an optional field representing the advisor phoneNumber

reportAccess
boolean

Enable or disable access to the reports for the advisor

reportInterval
string

ReportInterval defines in which intervals the advisor wants to receive a report

reportRole
string
Enum: "report" "report-branch" "report-tenant"

ReportRole represents the permissions the advisor has to view all or a subset or only own reports

reportSend
boolean

Enable or disable sending e-mails with report links to the advisor

role
required
string
Enum: "employee" "tenantadmin" "tenant-manager"

New role represents the permissions the advisor has to view all or a subset of cockpits

sendMail
boolean

SendMail notify advisor by email about every cockpit being created

type
string
Enum: "person" "company" "person-company" "company-person"

New type of the advisor

Responses

Response Schema: application/json
avatar
string

Avatar contains a picture of the advisor

customAdvisorID
string or null

CustomAdvisorID is the custom ID of the advisor

deactivated
boolean

If true advisor is deactivated

id
string

ID of the advisor

lastActivity
string

Time of last activity

linkID
string

LinkID of the advisor

logo
string

Logo represents the url to the tenant's logo

mail
string

Mail of the advisor

phoneNumber
string

Phone number of the advisor

primaryColor
string

PrimaryColor represents the primary color that is presented in the cockpit

reportAccess
boolean

Is access to the reports granted for the advisor

reportInterval
string

ReportInterval defines in which intervals the advisor wants to receive a report

reportRole
string
Enum: "report" "report-branch" "report-tenant"

ReportRole represents the permissions the advisor has to view all or a subset or only own reports

reportSend
boolean

Is sending reports enabled for the advisor

role
string
Enum: "employee" "tenantadmin" "tenant-manager"

Role of the advisor

sendMail
boolean

SendMail notify advisor by email about every cockpit being created

tenant
string

Tenant is the name of the tenant the advisor belongs to

tenantID
string

TenantID references the tenant the advisor belongs to

type
string
Enum: "person" "company" "person-company" "company-person"

Type of the advisor

url
string

URL represents the link that the advisor can share with customers to generate cockpits.
To create a personalized individual link the url can be adjusted by following query parameters

userName
string

UserName is the name of the advisor

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{}

Update Advisor Avatar

Update an advisor avatar upload image to cdn and create link to this

query Parameters
advisor-id
string

search users for the specified ID

header Parameters
Authorization
required
string

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/x-www-form-urlencoded
required
file
required
string <binary>

raw image files

url
string

image URL

Responses

Response Schema: application/json
fileHandle
string
url
string

Response samples

Content type
application/json
{
}

Delete Advisor Avatar

Delete an advisor avatar

path Parameters
advisor-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
{
}

Cockpit-Tenants

Tenant is a submodule of the cockpit and offers the possibility to patch tenant configuration. Here you can set the DisplayName, PrimaryColor, AccentColor, Logo, activate/deactivate the report, after which period the cockpits are deleted, which modules are active and whether the entire tenant is activated.

Get Tenant

Returns a tenant

header Parameters
Authorization
required
string

The authorization token

TenantID
string

The client's tenant

Responses

Response Schema: application/json
accentColor
string

AccentColor represents the secondary color that is presented in the cockpit

createdAt
string

CreatedAt marks the time when the Document was created

createdByEvent
boolean

CreatedByEvent marks the tenant as created by eventbus handler so there are no users/links

deactivated
boolean

Deactivated deactivates the tenant if set to true. Tenant is active if the value is null or false

displayName
string

DisplayName represents the name of the tenant that is displayed in the UI

object

ExpireConfig represents the time when a cockpit will be seen as expired in days.

id
string

ID is a unique identifier to represent the tenant

logo
string

Logo represents the url to the tenant's logo

modifiedAt
string

ModifiedAt marks the time when the Document was last modified

object

Modules hold information on what modules are enabled for the tenant

name
string

Name represents the name of the tenant f.e. insurance huk

primaryColor
string

PrimaryColor represents the primary color that is presented in the cockpit

report
boolean

Report indicates wether the cockpit report is enabled or not

object

ReportModules hold information on what report modules are enabled for the tenant

Response samples

Content type
application/json
{
}

Patch Tenant

Patches a tenant

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

AdjustUsersPermission
boolean

Adjust all users' permissions in dependence to Report

accentColor
string

AccentColor represents the secondary color that is presented in the cockpit

deactivated
boolean

Deactivated deactivates the tenant if set to true. Tenant is active if the value is null or false, deactivating a tenant will deactivate each underlying user

displayName
string

DisplayName represents the new name of the tenant that is displayed in the UI

object

ExpireConfig represents the time when a cockpit will be seen as expired in days.

logo
string

Logo represents the new url to the tenant's logo

object

Modules if set will overwrite the existing module settings

primaryColor
string

PrimaryColor represents the new primary color that is presented in the cockpit

report
boolean

Report enabled/disabled the cockpit report

object

Modules holds information on the Report Modules configuration

Responses

Response Schema: application/json
accentColor
string

AccentColor represents the secondary color that is presented in the cockpit

createdAt
string

CreatedAt marks the time when the Document was created

createdByEvent
boolean

CreatedByEvent marks the tenant as created by eventbus handler so there are no users/links

deactivated
boolean

Deactivated deactivates the tenant if set to true. Tenant is active if the value is null or false

displayName
string

DisplayName represents the name of the tenant that is displayed in the UI

object

ExpireConfig represents the time when a cockpit will be seen as expired in days.

id
string

ID is a unique identifier to represent the tenant

logo
string

Logo represents the url to the tenant's logo

modifiedAt
string

ModifiedAt marks the time when the Document was last modified

object

Modules hold information on what modules are enabled for the tenant

name
string

Name represents the name of the tenant f.e. insurance huk

primaryColor
string

PrimaryColor represents the primary color that is presented in the cockpit

report
boolean

Report indicates wether the cockpit report is enabled or not

object

ReportModules hold information on what report modules are enabled for the tenant

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

Cockpit-Reports

Cockpit Report aggregates cockpits within a given time period and provides information such as how many cockpits were created or downloaded during that period. It also offers insights into the customer base, such as how many customers have children or own a car. A report has a modular structure so that it can be customised. The modules can be enabled (or disabled) via the PATCH tenant endpoint under reportModules.

Person Report Response

Click to expand 
{
    "clientBase": {
        "haveAlimonyIncome": {
            "existsSince": "2024-04-11", // Since when the KPI is recorded
            "percent": 0, // Percentage of all customers
            "total": 0 // How many customers receive alimony
        },
        "haveParentalAllowance": {
            "existsSince": "2024-04-11",
            "percent": 0, // Percentage of all customers
            "total": 0 // How many customers receive parental allowance
        },
        "havePension": {
            "existsSince": "2024-04-11",
            "percent": 0, // Percentage of all customers
            "total": 0 // How many clients receive a pension
        },
        "haveSalary": {
            "existsSince": "2024-04-11",
            "percent": 100, // Percentage of all customers
            "total": 2 // How many clients receive a salary/wage
        },
        "averageSalary": {
            "existsSince": "2024-04-11",
            "total": 3469.66 // Average salary/wage
        },
        "haveBudgetSurplus": {
            "existsSince": "2024-04-11",
            "percent": 100, // Percentage of all customers
            "total": 2 // How many clients have a surplus at the end of the month
        }
    },
    "cockpitUsage": {
        "visitedLandingPage": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 1 // Number of landing page visits
        },
        "startedChecks": {
            "existsSince": "2024-04-11",
            "percentChange": 100, // Percentage change compared to previous period
            "total": 2 // How many cockpits were started
        },
        "startedBankLogins": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 1 // How many bank logins were carried out
        },
        "successfulBankLogins": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 1 // Number of successful bank logins
        },
        "successfulFileUploads": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 0 // Number of successful file uploads
        },
        "successfulAccountUploads": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 2 // Number of successful account uploads
        },
        "downloadedCockpits": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 1 // Number of downloaded cockpits
        },
        "approvedCockpits": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 1 // How many cockpits were approved
        },
        "viewedByUsers": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 0 // How many cockpits were viewed by the customers
        }
    },
    "cockpitUsageOverall": { // person and company combined cockpit usage
        "visitedLandingPage": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 1
        },
        "startedChecks": {
            "existsSince": "2024-04-11",
            "percentChange": 100, // Percentage change compared to previous period
            "total": 2
        },
        "startedBankLogins": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 1
        },
        "successfulBankLogins": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 1
        },
        "successfulFileUploads": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 0
        },
        "successfulAccountUploads": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 2
        },
        "downloadedCockpits": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 1
        },
        "approvedCockpits": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 1
        },
        "viewedByUsers": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 0
        }
    },
    "credits": {
        "credits": {
            "existsSince": "2024-04-11",
            "percent": 100, // Percentage of all customers
            "total": 2 // How many customers have a credit
        },
        "housingFinancing": {
            "existsSince": "2024-04-11",
            "percent": 0, // Percentage of all customers
            "total": 0 // How many customers have a housing financing
        },
        "leasings": {
            "existsSince": "2024-04-11",
            "percent": 0, // Percentage of all customers
            "total": 0 // How many customers have a leasing contract
        }
    },
    "insurances": {
        "haveAccidentInsurance": {
            "existsSince": "2024-04-11",
            "percent": 0, // Percentage of all customers
            "total": 0 // How many customers have a accident insurance
        },
        "haveLifeInsurance": {
            "existsSince": "2024-04-11",
            "percent": 100, // Percentage of all customers
            "total": 2 // How many customers have a life insurance
        },
        "haveOccupationalDisability": {
            "existsSince": "2024-04-11",
            "percent": 0, // Percentage of all customers
            "total": 0 // How many customers have a occupational disablility insurance
        },
        "haveOtherInsurances": {
            "existsSince": "2024-04-11",
            "percent": 300, // Percentage of all customers
            "total": 6 // How many other insurances are there
        },
        "havePrivateHealthInsurance": {
            "existsSince": "2024-04-11",
            "percent": 100, // Percentage of all customers
            "total": 2 // How many customers have a private health insurance
        },
        "haveCarInsurances": {
            "existsSince": "2024-04-11",
            "percent": 100, // Percentage of all customers
            "total": 2 // How many customers have a car insurance
        },
        "haveLiabilityInsurances": {
            "existsSince": "2024-04-11",
            "percent": 100, // Percentage of all customers
            "total": 2 // How many customers have a liability insurance
        },
        "haveContentsInsurances": {
            "existsSince": "2024-04-11",
            "percent": 0, // Percentage of all customers
            "total": 0 // How many customers have a content insurance
        },
        "haveLegalInsurances": {
            "existsSince": "2024-04-11",
            "percent": 100, // Percentage of all customers
            "total": 2 // How many customers have a legal insurance
        }
    },
    "livingSituation": {
        "haveCars": {
            "existsSince": "2024-04-11",
            "percent": 100, // Percentage of all customers
            "total": 2 // How many customers have one or more cars
        },
        "haveChildren": {
            "existsSince": "2024-04-11",
            "percent": 100, // Percentage of all customers
            "total": 2 // How many customers have one or more children
        },
        "liveForRent": {
            "existsSince": "2024-04-11",
            "percent": 0, // Percentage of all customers
            "total": 0 // How many customers rent an apartment/house
        }
    },
    "liquidity": {
        "haveCreditCards": {
            "existsSince": "2024-04-11",
            "percent": 100, // Percentage of all customers
            "total": 2 // How many customers have a credit card
        },
        "haveCallMoneyAccounts": {
            "existsSince": "2024-04-11",
            "percent": 100, // Percentage of all customers
            "total": 2 // How many customers have a call money account
        }
    },
    "assetAccumulation": {
        "haveDepots": {
            "existsSince": "2024-04-11",
            "percent": 100, // Percentage of all customers
            "total": 2 // How many customers have a depot
        },
        "haveSecuritiesSavingPlans": {
            "existsSince": "2024-04-11",
            "percent": 100, // Percentage of all customers
            "total": 2 // How many customers have securities saving plans
        },
        "haveHousingSavings": {
            "existsSince": "2024-04-11",
            "percent": 0, // Percentage of all customers
            "total": 0 // How many customers have housing savings
        },
        "haveProperty": {
            "existsSince": "2024-04-11",
            "percent": 0, // Percentage of all customers
            "total": 0 // How many customers own an apartment/house
        }
    }
}

Company Report Response

Click to expand 
{
    "cockpitUsage": {
        "visitedLandingPage": {
            "existsSince": "2024-04-11", // Since when the KPI is recorded
            "percentChange": 0, // Percentage change compared to previous period
            "total": 1 // Number of landing page visits
        },
        "startedChecks": {
            "existsSince": "2024-04-11",
            "percentChange": 100, // Percentage change compared to previous period
            "total": 2 // How many cockpits were started
        },
        "startedBankLogins": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 1 // How many bank logins were carried out
        },
        "successfulBankLogins": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 1 // Number of successful bank logins
        },
        "successfulFileUploads": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 0 // Number of successful file uploads
        },
        "successfulAccountUploads": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 2 // Number of successful account uploads
        },
        "downloadedCockpits": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 1 // Number of downloaded cockpits
        },
        "approvedCockpits": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 1 // How many cockpits were approved
        },
        "viewedByUsers": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 0 // How many cockpits were viewed by the customers
        }
    },
    "cockpitUsageOverall": { // person and company combined cockpit usage
        "visitedLandingPage": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 0
        },
        "startedChecks": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 3
        },
        "startedBankLogins": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 0
        },
        "successfulBankLogins": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 0
        },
        "successfulFileUploads": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 0
        },
        "successfulAccountUploads": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 1
        },
        "downloadedCockpits": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 0
        },
        "approvedCockpits": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 3
        },
        "viewedByUsers": {
            "existsSince": "2024-04-11",
            "percentChange": 0, // Percentage change compared to previous period
            "total": 0
        }
    },
    "credits": {
        "credits": {
            "existsSince": "2024-04-11",
            "relative": 100, // Relative share of credits and leasings
            "absolute": 2 // Total number of credits
        },
        "leasings": {
            "existsSince": "2024-04-11",
            "relative": 0, // Relative share of credits and leasings
            "absolute": 0 // Total number of leasing contracts
        }
    },
    "insurances": {
        "legalInsurance": {
            "existsSince": "2024-04-11",
            "relative": 33.33, // Relative share of all insurance
            "absolute": 3 // Total number of legal insurances
        },
        "carInsurance": {
            "existsSince": "2024-04-11",
            "relative": 55.56, // Relative share of all insurance
            "absolute": 5 // Total number of car insurances
        },
        "lifeInsurance": {
            "existsSince": "2024-04-11",
            "relative": 0, // Relative share of all insurance
            "absolute": 0 // Total number of life insurances
        },
        "insuranceBusinessLiability": {
            "existsSince": "2024-04-11",
            "relative": 11.11, // Relative share of all insurance
            "absolute": 1 // Total number of business liability insurances
        },
        "privateHealthInsurance": {
            "existsSince": "2024-04-11",
            "relative": 0, // Relative share of all insurance
            "absolute": 0 // Total number of private health insurances
        },
        "insuranceMulti": {
            "existsSince": "2024-04-11",
            "relative": 0, // Relative share of all insurance
            "absolute": 0 // Total number of multi insurances
        }
    },
    "assetAccumulation": {
        "depot": {
            "existsSince": "2024-04-11",
            "relative": 40, // Relative share of all assets
            "absolute": 2 // Total number of depots
        },
        "timeDeposit": {
            "existsSince": "2025-02-03",
            "relative": 0, // Relative share of all assets
            "absolute": 0 // Total number of time deposits
        },
        "callMoney": {
            "existsSince": "2024-04-11",
            "relative": 60, // Relative share of all assets
            "absolute": 3 // Total number of call money accounts
        },
        "riesterRente": {
            "existsSince": "2025-02-14",
            "relative": 0, // Relative share of all assets
            "absolute": 0 // Total number of riester rente contracts
        }
    },
    "customerSupplierRelations": {
        "customerHighDependency": {
            "existsSince": "2024-04-11",
            "relative": 50, // Relative share of all customers
            "absolute": 3 // Total number of customers for which there is at least a 75% dependency
        },
        "customerMiddleDependency": {
            "existsSince": "2024-04-11",
            "relative": 0, // Relative share of all customers
            "absolute": 0 // Total number of customers for which there is at least a 50% dependency
        },
        "supplierHighDependency": {
            "existsSince": "2024-04-11",
            "relative": 25, // Relative share of all suppliers
            "absolute": 1 // Total number of suppliers for which there is at least a 75% dependency
        },
        "supplierMiddleDependency": {
            "existsSince": "2024-04-11",
            "relative": 75, // Relative share of all suppliers
            "absolute": 3 // Total number of suppliers for which there is at least a 50% dependency
        }
    },
    "paymentTransaction": {
        "creditCard": {
            "existsSince": "2024-04-11",
            "relative": 0, // Relative share of all customers
            "absolute": 0 // Total number of credit cards
        },
        "cardPaymentTerminalProvided": {
            "existsSince": "2024-04-11",
            "relative": 0, // Relative share of all customers
            "absolute": 0 // Total number of card payments via terminal
        },
        "overallEarning": {
            "existsSince": "2024-04-11",
            "total": 305927.47 // Total overall earning
        },
        "overallSpending": {
            "existsSince": "2024-04-11",
            "total": -392492.27 // Total overall spending
        },
        "overallTotal": {
            "existsSince": "2024-04-11",
            "total": 66398.93 // Total total overall
        },
        "liquidityMonthly": { // Overview of monthly earnings and spendings (across all accounts)
            "existsSince": "2025-04-09",
            "data": [
                {
                    "date": "2024-10-01",
                    "earnings": 20623.96,
                    "spendings": -15179.96
                },
                {
                    "date": "2024-11-01",
                    "earnings": 7868.32,
                    "spendings": -13405.16
                },
                {
                    "date": "2024-12-01",
                    "earnings": 7868.32,
                    "spendings": -15729.64
                },
                {
                    "date": "2025-01-01",
                    "earnings": 7868.32,
                    "spendings": -14084.36
                }
            ]
        },
        "cashCount": {
            "existsSince": "2025-02-03",
            "total": 0 // Total number of cash bookings
        },
        "cashOutgoing": {
            "existsSince": "2024-04-11",
            "total": 0 // Average cash outgoing
        },
        "cashIncoming": {
            "existsSince": "2024-04-11",
            "total": 0 // Average cash incoming
        },
        "foreignCount": {
            "existsSince": "2025-02-03",
            "total": 0 // Total number of foreign bookings
        },
        "foreignSpending": {
            "existsSince": "2024-04-11",
            "total": 0 // Average number of foreign spending
        },
        "foreignEarning": {
            "existsSince": "2024-04-11",
            "total": 0 // Average numbers of foreign earning
        },
        "collectivePayments": {
            "existsSince": "2024-04-11",
            "total": 0 // Average collective payments
        }
    },
    "detectedAccounts": {
        "existsSince": "2025-02-03",
        "data":[
            {
                "bankGroup": "sparkassen",
                "absolute": 4, // Total number of all sparkassen accounts
                "relative": 33.33, // Relative share of all bank accounts
                "detectedAccounts": [
                    {
                        "bank": "Kasseler Sparkasse",
                        "absolute": 2, // number of Kassler Sparkasse accounts
                        "relative": 50.0, // Relative share of all Sparkassen accounts
                        "logo": "sparkasse-logo"
                    },
                    {
                        "bank": "Sparkasse Oberhessen",
                        "absolute": 1, // number of Sparkasse Oberhessen accounts
                        "relative": 25.0, // Relative share of all Sparkassen accounts
                        "logo": "sparkasse-logo"
                    },
                    {
                        "bank": "Sparkasse Bremen",
                        "absolute": 1, // number of Sparkasse Bremen accounts
                        "relative": 25.0, // Relative share of all Sparkassen accounts
                        "logo": "sparkasse-logo"
                    }
                ]
            },
            {
                "bankGroup": "commerzbank",
                "absolute": 2,
                "relative": 16.67,
                "detectedAccounts": [
                    {
                        "bank": "Commerzbank",
                        "absolute": 2, // number of Commerzbank accounts
                        "relative": 100.0, // Relative share of all Commerzbank accounts
                        "logo": "commerzbank-logo"
                    }
                ]
            },
            {
                "bankGroup": "deutschebank",
                "absolute": 1,
                "relative": 8.33,
                "detectedAccounts": [
                    {
                        "bank": "Deutsche Bank",
                        "absolute": 1, // number of Deutsche Bank accounts
                        "relative": 100.0, // Relative share of all Deutsche Bank accounts
                        "logo": "deutsche-bank-logo"
                    }
                ]
            },
            {
                "bankGroup": "genossenschaftsbanken",
                "absolute": 1,
                "relative": 8.33,
                "detectedAccounts": [
                    {
                        "bank": "Raiffeisenbank Kassel",
                        "absolute": 1, // number of Raiffeisenbank Kassel accounts
                        "relative": 100.0, // Relative share of all Raiffeisenbank Kassel accounts
                        "logo": "vr-bank-logo"
                    }
                ]
            },
            {
                "bank": "postbank",
                "absolute": 1,
                "relative": 8.33,
                "detectedAccounts": [
                    {
                        "bank": "Postbank",
                        "absolute": 1, // number of Postbank accounts
                        "relative": 100.0, // Relative share of all Postbank accounts
                        "logo": "postbank-logo"
                    }
                ]
            },
            {
                "bankGroup": "bundesbank",
                "absolute": 1,
                "relative": 8.33,
                "detectedAccounts": [
                    {
                        "bank": "Bundesbank",
                        "absolute": 1, // number of Bundesbank accounts
                        "relative": 100.0, // Relative share of all Bundesbank accounts
                        "logo": "bundesbank-logo"
                    }
                ]
            },
            {
                "bankGroup": "nogroup", // banks or payment service providers that cannot be assigned to a group 
                "absolute": 2,
                "relative": 16.67,
                "detectedAccounts": [
                    {
                        "bank": "N26",
                        "absolute": 1, // number of N26 accounts
                        "relative": 50.0, // Relative share of all bank accounts
                        "logo": "n26-logo"
                    },
                    {
                        "bank": "Revolut",
                        "absolute": 1, // number of Revolut accounts
                        "relative": 50.0, // Relative share of all bank accounts
                        "logo": "revolut-logo"
                    }
                ]
            }
        ]
    },
    "furtherInformation": {
        "employeeRange": {
            "existsSince": "2025-02-03",
            "data": [
                {
                    "relative": 20, // Relative share of all companies
                    "absolute": "0-0" // Min-Max number of employees
                },
                {
                    "relative": 20,
                    "absolute": "0-10"
                },
                {
                    "relative": 20,
                    "absolute": "12-22"
                },
                {
                    "relative": 20,
                    "absolute": "100-150"
                },
                {
                    "relative": 20,
                    "absolute": "no entry"
                }
            ]
    },
    "risk": {
        "backDebits": {
            "existsSince": "2025-02-03",
            "percent": 25, // Percentage of all customers
            "total": 1 // Number of customers with back debits
        },
        "overdraws": {
            "existsSince": "2025-02-18",
            "percent": 25, // Percentage of all customers
            "total": 1 // Number of customers with overdraws
        },
        "garnishments": {
            "existsSince": "2025-02-18",
            "percent": 0, // Percentage of all customers
            "total": 0 // Number of customers with garnishments
        }
    }
}

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)
Array
keyword
required
string

The keyword to search for

limit
integer

The limit how many results will be returned

required
Array of objects (companies.Property)

The properties on which to perform the search

Responses

Response Schema: application/json
object (companies.SearchResults)
additional property
Array of objects (companies.CompanyQueryResult)
Array
object

The company

score
number

The score of the company

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

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

Array
bankCode
string

The bank code of the company

bic
string

The BIC of the company

creditorID
string

The creditor ID of the company

domain
string

The web domain of the company

iban
string

The IBAN of the company

name
string

The name of the company

queryID
string

The ID of the query. This can be defined to later retrieve the matching query result in the response

Responses

Response Schema: application/json
Array of objects (companies.LogoQueryResult)

The query results

Array
company
string

The logo's company name

companyID
string

The logo's company identifier (encrypted)

queryID
string

The ID of the query. If this was specified in the query, this is the matching result to the query

squareLogoURL
string

The URL of the square or quadratic logo

status
string
Enum: "ok" "not found" "usage forbidden"

Signals if company was found and whether we are allowed to display the logo

url
string

The URL to the logo

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{}

Webhooks

Overview

Webhooks are HTTP callbacks which can be used to send notifications to your service/server when data in a user on your client has been changed. Rather than making an API call, finoOS2 sends an HTTP request with the data that has been changed to an endpoint you configure.

Setup

The webhooks module allows you to set up such user-defined HTTP callbacks by subscribing to events.

Using the webhook module requires the following:

  • Make sure your client has the webhooks scope to have access to the webhooks module
  • Create a webhook endpoint on your server
  • Use the finoOS2 webhook module to set up your webhook
    • Select your preferred HTTP method that shall be used to send the event related data to your webhook
    • Pick one or multiple events you want to subscribe to from the event list below
    • (Optional) generate a secret to secure your webhook
    • Create your webhook
  • Make sure your webhook endpoint can process the payload sent by finoOS2.
  • Send a 2XX http status code back after processing the payload to signal finoOS2 everything went fine
  • If the webhook response returns an HTTP status code above 299, a retry mechanism is triggered. After a certain number of failed attempts, the process stops.

Securing The Webhook

Before you create a webhook with our webhooks module. Consider to securing the webhook you want to configure by generating a secret and configure you webhook with it. finoOS2 does nothing with your secret but sending the secret along with the payload that gets send after a subscribed event triggers on a user. Your webhook endpoint needs validate the secret to accept the request on your server.

If you already have configured a webhook and want to secure it afterwards. You can * update your webhook* with a secret.

The Payload

After setting up and optionally securing your webhook. It is time to receive the payload associated to the subscribed events after an event triggers. Down below you can see the generic payload that gets sent to your configured endpoint.

  • webhookID represents the unique identifier of the webhook
  • userID represents the user experiencing the change in data
  • customUserID is a identifier you can choose on create user
  • tenantID under which tenantID the user was created
  • correlationID which calculation process this event belongs to
  • correlationTimestamp when the calculation process was started
  • secret to secure your webhook
  • event that got triggered
  • data that changes relevant to the event that got triggered.
The generic payload

Type: object

Properties

  • webhookID
    • Type: string
  • userID
    • Type: string
  • customUserID
    • Type: string
  • tenantID
    • Type: string
  • correlationID
    • Type: string
  • correlationTimestamp
    • Type: string
  • secret
    • Type: string
  • event
    • Type: string
  • data
    • Type: object

Headers

Along with the payload additional headers are sent to your configured webhook. These headers are:

  • X-Request-Id representing a unique identifier for the request or event trigger. For example used to trace back the path the event took.
  • FinoOS-Tenant-ID representing the tenant the event belongs to.

Subscribable Events And Their Payloads

Banking
transactions.raw

Type: object

Properties
webhook data payload contains Accounts with empty tags field.

transactions.raw.notification

webhook data payload contains notification message without raw data.
Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
    • Type: string
  • service
    • Type: string
    • The finoos2 service which triggered the notification
transactions

Type: object

Properties
webhook data payload contains Accounts.

transactions.notification

webhook data payload contains notification message without raw data.
Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
    • Type: string
  • service
    • Type: string
    • The finoos2 service which triggered the notification
ubasyncerror

This event is triggered if our automatic banking sync cannot be successfully completed. The user consent is expired and a user action is required to renew the sync with /management or /sync (session). Otherwise there is a temporary issue with our infrastructure.

Type: object

Properties

  • errorEvent
    • Type: string
  • errorData
    • Type: object
    • Properties
      • msg
        • Type: string
      • bankLoginID
        • Type: string
      • type
        • Type: string
        • The value is restricted to the following:
          1. "CHALLENGE_REQUIRED"
          2. "ERROR"
  • timestamp
    • Type: string
Categorization
categorization

Type: object

Properties
webhook data payload contains Categorization.

categorization.diff

Type: object

Properties
webhook data payload contains Categorization only containing transactions with changed tagging.

General Analytics
account-detection

Type: object

Properties
webhook data payload contains Account-Detection.

account-detection.notification

webhook data payload contains notification message without raw data.
Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object Properties

  • message

    • Type: string
    • service
      • Type: string
      • The finoos2 service which triggered the notification
contracts

Type: object

Properties
webhook data payload contains Contracts.

Person Analytics
person-income

Type: object

Properties
webhook data payload contains Person-Income.

person-income.notification

webhook data payload contains notification message without raw data.
Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
    • Type: string
  • service
    • Type: string
    • The finoos2 service which triggered the notification
person-spending

Type: object

Properties
webhook data payload contains Person-Spending.

person-spending.notification

webhook data payload contains notification message without raw data.
Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
    • Type: string
  • service
    • Type: string
    • The finoos2 service which triggered the notification
person-risk

Type: object

Properties
webhook data payload contains Person-Risk.

person-risk.notification

webhook data payload contains notification message without raw data.
Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
    • Type: string
  • service
    • Type: string
    • The finoos2 service which triggered the notification
person-household-budget

Type: object

Properties
webhook data payload contains Person-Household-Budget.

person-household-budget.notification

webhook data payload contains notification message without raw data.
Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
    • Type: string
  • service
    • Type: string
    • The finoos2 service which triggered the notification
person-adult-check

Type: object

Properties
webhook data payload contains Person-Adult-Check.

person-adult-check.notification

webhook data payload contains notification message without raw data.
Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
    • Type: string
  • service
    • Type: string
    • The finoos2 service which triggered the notification
person-living-situation

Type: object

Properties
webhook data payload contains Person-Living-Situation.

person-living-situation.notification

webhook data payload contains notification message without raw data.
Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
    • Type: string
  • service
    • Type: string
    • The finoos2 service which triggered the notification
renter-information

Type: object

Properties
webhook data payload contains Renter-Information.

renter-information.notification

webhook data payload contains notification message without raw data.
Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
    • Type: string
  • service
    • Type: string
    • The finoos2 service which triggered the notification
Cockpit
companycockpit

Type: object

Properties
webhook data payload contains CompanyCockpit with the type company.

personcockpit

Type: object

Properties
webhook data payload contains PersonCockpit with the type person.

cockpit.approved

This event is triggered when a customer approves a cockpit and so also unlocks it for advisor access.

Type: object

Properties

  • cockpitID
    • Type: string
  • advisorID
    • Type: string
cockpit.notification

webhook data payload contains notification message without raw data.
Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
    • Type: string
  • service
    • Type: string
    • The finoos2 service which triggered the notification
cockpitrecommendations.notification

webhook data payload contains notification message without raw data.
Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
    • Type: string
  • service
    • Type: string
    • The finoos2 service which triggered the notification
personcockpit-recommendations

Type: object

Properties
webhook data payload contains Recommendations.

companycockpit-recommendations

Type: object

Properties
webhook data payload contains Recommendations.

Get Webhooks

Scope: webhooks

Get all registered webhooks

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

The authorization token

TenantID
string

The client's tenant

Responses

Response Schema: application/json
Array of objects (webhooks.Webhook)
Array
callbackURL
string
events
Array of strings
object
httpMethod
string
id
string
secret
string
tenantID
string

Response samples

Content type
application/json
{
}

Create Webhook

Scope: webhooks Creates a user-defined callback(webhook) associated to one or multiple events.

  • callbackURL is the URL that receives the payload associated to the subscribed events after at least one subscribed event is triggered
  • secret is a custom secret set by the user that can be checked after receiving an event payload to secure the callback
  • events represents the events the user wants to subscribe
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

object
callbackURL
string
events
Array of strings
object

Add up to 20 custom headers with up to 4096 bytes per header

httpMethod
string
secret
string

Responses

Response Schema: application/json
id
string
secret
string

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

Update Webhook

Scope: webhooks

Update a specific webhook

path Parameters
webhook-id
required
string

The id of the webhook to be updated

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

object
callbackURL
string
events
Array of strings
object

Add up to 20 custom headers with up to 4096 bytes per header

httpMethod
string
secret
string

Responses

Response Schema: application/json
object (webhooks.Webhook)
callbackURL
string
events
Array of strings
object
httpMethod
string
id
string
secret
string
tenantID
string

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

Delete Webhook

Scope: webhooks

Delete a webhook

path Parameters
webhook-id
required
string

The id of the webhook 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
{
}

Patch Webhook

Scope: webhooks

Patch a specific webhook

path Parameters
webhook-id
required
string

The id of the webhook to be updated

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

object
callbackURL
string
errorCallbackURL
string
events
Array of strings
object

Add up to 20 custom headers with up to 4096 bytes per header`

httpMethod
string
secret
string

Responses

Response Schema: application/json
object (webhooks.Webhook)
callbackURL
string
events
Array of strings
object
httpMethod
string
id
string
secret
string
tenantID
string

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

Feedback

Improving our services is important to us. Therefore, sending us feedback helps us. Through the endpoint Create a feedback this is possible.

Each feedback has a module and type. The module gives us information about the context of the feedback, e.g., the service or module the feedback is about. The type corresponds to the information that is given to us, on which we can act upon. Both of these fields are related to each other and can only be used in these combinations:

Module Supported Types
contractor rating, interaction
cockpit cockpit
company-logos missing-logo, wrong-logo, outdated-logo

Important: Each type influences the required feedback-field model!

Type: rating 
"feedback":{
    "rating": "<int>"
}

Limitations:

  • rating value in range: minimum: 1 and maximum: 5
Type: interaction 
"feedback":{
    "interaction": "<string>"
}

Limitations:

  • interaction any value of: tagChange
Type: cockpit 
"feedback": {
    "rating": "<int>",
    "cockpitID": "<string>",
    "cockpitTenantID": "<string>",
    "cockpitLink": "<string>"
}

Limitations:

  • rating is optional and may contain a value in range: 1 - 5
  • cockpitLink is optional
Type: missing-logo, wrong-logo, outdated-logo 
"feedback": {
    "url": "<string>",
    "squareURL": "<string>",
    "bankCode": "<string>",
    "bic":"<string>",
    "creditorID":"<string>",
    "domain":"<string>",
    "iban":"<string>",
    "name":"<string>",
    "companyID":"<string>",
    "requestBody":"<object>",
    "logoTypes":"<[]string>"
}

Limitations:

  • logoTypes is optional and may contain any value of: default or square
  • logoTypes default value is ["default"]
  • At least one of the following fields must be set (we encourage you to set more fields):
    • url
    • squareURL
    • bankCode
    • bic
    • creditorID
    • domain
    • iban
    • name
    • companyID
    • requestBody
Type: renter-information-selection 
{
  "feedback": {
    "userSelections": [
      {
        "transactionIDs": ["<transactionID>"],
        "category": "salary"
      },
      {
        "transactionIDs": ["<transactionID>"],
        "category": "fallbackIncome"
      },
      {
        "transactionIDs": ["<transactionID>"],
        "category": "rental"
      },
      {
        "transactionIDs": ["<transactionID>"],
        "category": "fallbackRental"
      },
      {
        "transactionIDs": ["<transactionID>"],
        "category": "salesOfSecurities"
      },
      {
        "transactionIDs": ["<transactionID>"],
        "category": "childBenefit"
      },
      {
        "transactionIDs": ["<transactionID>"],
        "category": "rentalIncoming"
      },
      {
        "transactionIDs": ["<transactionID>"],
        "category": "pocketMoney"
      },
      {
        "transactionIDs": ["<transactionID>"],
        "category": "governmentSupport"
      },
      {
        "transactionIDs": ["<transactionID>"],
        "category": "governmentChildSupport"
      },
      {
        "transactionIDs": ["<transactionID>"],
        "category": "commissionIncome"
      },
      {
        "transactionIDs": ["<transactionID>"],
        "category": "studentLoan"
      },
      {
        "transactionIDs": ["<transactionID>"],
        "category": "parentalAllowance"
      },
      {
        "transactionIDs": ["<transactionID>"],
        "category": "maternityAllowance"
      },
      {
        "transactionIDs": ["<transactionID>"],
        "category": "cryptocurrencyPayout"
      },
      {
        "transactionIDs": ["<transactionID>"],
        "category": "studiesSupport"
      }
    ]
  }
}

Limitations:

  • <transactionID> values are of type string and the selected transactions in the renter information scope

Create Feedback

Creates and sends feedback.

Request Body schema: application/json

The create feedback request

object

Any additional information that the feedback creator wants to attach

content
required
string >= 0 characters

Any free text the feedback creator wants to send

feedback
required
object

Feedback model related to the set Type - any of: rating, interaction, cockpit and company-logos

module
required
string
Enum: "company-logos" "cockpit" "contractor" "renter-information"

The module the feedback is about

type
required
string
Enum: "missing-logo" "wrong-logo" "outdated-logo" "cockpit" "rating" "interaction" "renter-information-selection"

The Type of the feedback influencing the Feedback object model

userID
string

Identifies the user sending the feedback

Responses

Response Schema: application/json
feedbackID
string

Feedback identifier

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

Server-Status

Get the current server status

Provides information whether the server is ready or not.

Responses

Response Schema: application/json
object (status.ServerStatus)

Response samples

Content type
application/json
{ }

CHANGELOG

Changelog

All notable changes to finoOS2 are documented in this changelog. We follow semantic versioning (MAJOR.MINOR.PATCH) so you can immediately see whether a release introduces breaking changes, new features, or bug fixes. Each entry reflects our ongoing effort to craft the best possible API and documentation, making your integration with the finoOS platform clearer, smoother, and more delightful to build on.

[v1.23.1] - 2026-04-28

Changed

  • Clarified recurring and storeSecrets field documentation on Connect Bank Account — both must be set to true for automatic synchronization to run; without storeSecrets=true, transactions only refresh when a synchronization session is triggered manually. storeSecrets defaults to true when omitted

[v1.23.0] - 2026-04-15

Added

  • Rate limiting documentation for POST /users/import-user
    • Rate limit response headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy, X-RateLimit-Concurrent-Limit, X-RateLimit-Concurrent-Remaining, Retry-After)
    • ?inspect=rateLimit query parameter to check current quota without consuming a request
    • 429 Too Many Requests response body shape with rate and concurrency quota details

[v1.22.1] - 2026-02-24

Changed

  • Improved currency parsing for securities positions in Banking section
    • If the depot currency is known, it is now used as fallback instead of defaulting to OTHER
    • If the currency of all securities positions is known and uniform, this uniform currency is used as fallback

[v1.21.0] - 2026-01-12

Documentation restructuring for Banking section

Changed

Renamed

[v1.20.44] - 2025-10-25

Added

[v1.20.43] - 2025-10-15

Added

[v1.20.42] - 2025-09-16

Fixed

[v1.20.41] - 2025-08-20

Added

Changed

  • replaced user(s) with advisor(s) in all descriptions within Cockpit-Advisors section

Fixed

  • field descriptions in Cockpit-Advisors section
    • added missing descriptions
    • replaced incorrect descriptions with correct ones
    • replaced incorrect field type in ReportRole with correct ones

[v1.20.40] - 2025-07-21

Removed

  • not supported enpoints in Contracts section
    • Delete Contract
    • Delete Contracts

[v1.20.39] - 2025-07-18

Fixed

[v1.20.38] - 2025-07-14

Added

[v1.20.37] - 2025-07-07

Added

  • Renter-Information
    • new fields fallbackIncome and fallbackRental in the response the model
    • new field identity.accountOwners for all account owner values of the user
  • Feedback
    • new feedback type renter-information-selection to provide feedback on the selection of renter information

[v1.20.36] - 2025-06-16

Added

[v1.20.35] - 2025-06-06

Added

[v1.20.34] - 2025-05-08

Added

[v1.20.33] - 2025-03-31

Added

[v1.20.32] - 2025-03-26

Added

  • Support for automatic user deletion
    • Added optional field expiresIn to Add User request model. If set, the user will be marked for automatic deletion after the specified time in seconds. User marked as deleted are removed once a day.

[v1.20.31] - 2025-03-24

Added

  • identity.nameVerificationPassed to result Renter-Information when name-verification scope is activated

[v1.20.30] - 2025-03-19

Changed

[v1.20.29] - 2025-03-13

Changed

  • mark specific properties as nullable add some missing properties on

[v1.20.28] - 2025-03-06

Changed

[v1.20.27] - 2025-03-05

Added

[v1.20.26] - 2025-02-21

Added

[v1.20.25] - 2025-01-31

Added

  • extended descriptions included Banking

[v1.20.24] - 2025-01-23

Added

  • new webhooks for credit-rating scope
    • credit-rating.notification and credit-rating

[v1.20.23] - 2025-01-23

Changed

  • mark specific properties as nullable

[v1.20.22] - 2025-01-13

Added

  • Credit-Rating Endpoints to fetch credit rating information for a user

[v1.20.21] - 2024-12-18

Added

[v1.20.20] - 2024-11-13

Fixed

Updated

Added

[v1.20.19] - 2024-11-11

Added

[v1.20.18] - 2024-10-29

Added

[v1.20.17] - 2024-10-24

Added

  • triggerChallenge as new request parameter to Create Synchronization Session
    • default value is true
    • further information about the parameter can be found in the endpoint description

[v1.20.16] - 2024-10-14

Added

[v1.20.15] - 2024-10-11

Fixed

  • float values with .00 so that they are displayed correctly

[v1.20.14] - 2024-10-04

Added

[v1.20.13] - 2024-10-04

Added

[v1.20.12] - 2024-10-02

Added

[v1.20.11] - 2024-10-01

Fixed

[v1.20.10] - 2024-09-18

Added

[v1.20.9] - 2024-09-17

Added

[v1.20.8] - 2024-09-09

Added

[v1.20.7] - 2024-08-15

Added

[v1.20.6] - 2024-08-09

Added

Changed

  • update bookingDate and valueDate to be optional and type to be unix timestamp for external import,account and transaction upload

Removed

[v1.20.5] - 2024-07-31

Added

[v1.20.4] - 2024-07-23

Added

[v1.20.3] - 2024-07-10

Added

[v1.20.2] - 2024-07-10

Added

  • Added LogoURL and SquareLogoURL to Renter-Information Transaction Model Renter-Information
    • only available if a Logo is found for Payment Partner

[v1.20.1] - 2024-07-09

Removed

[v1.20.0] - 2024-07-05

Added

[v1.19.0] - 2024-07-03

Added

  • selfEmployment model to renter-information

[v1.18.10] - 2024-06-26

Fixed

  • all json consuming endpoint now specifically declare the content-type as application/json

[v1.18.9] - 2024-06-20

Fixed

[v1.18.8] - 2024-06-13

Added

[v1.18.7] - 2024-06-05

Added

[v1.18.6] - 2024-05-22

Added

[v1.18.5] - 2024-05-17

Added

  • cockpit recommendations Cockpit Recommendations
  • cockpit recommendation webhooks companycockpit-recommendations, personcockpit-recommendations, cockpitrecommendations.notification Webhooks

[v1.18.4] - 2024-04-26

Added

Fixed

  • Banking endpoints where client sends transactions now have correctly the requried transactionId in request model

[v1.18.3] - 2024-03-05

Changed

  • update TenantID header to be universally optional

[v1.18.2] - 2024-03-01

Added

  • Transaction IDs in each property of Income and Spending

[v1.18.1] - 2024-02-27

Added

[v1.18.0] - 2024-02-27

Added

[v1.17.3] - 2024-02-27

Fixed

  • removed tenant-id path parameter on cockpit-tenants endpoints group

[v1.17.2] - 2024-02-16

Fixed

  • webhooks create and put request models now corrected
  • Create External Accounts
    • clarify request requirements
    • update response
  • Banking
    • extended SessionResponse.RedirectURL to include new theme parameter represented as JSON string

[v1.17.1] - 2024-02-08

Added

[v1.17.0] - 2024-02-08

Added

[v1.16.0] - 2024-02-06

Changed

  • rename user scopes to userScopes in Add User request model
  • rename user scopes to userScopes in Add scopes to user request model
  • remove payment endpoints from Banking

[v1.15.5] - 2024-01-31

Added

[v1.15.4] - 2024-01-23

Changed

  • update Banking section
    • add missing descriptions and examples

[v1.15.5] - 2024-01-31

Added

[v1.15.3] - 2024-01-18

Changed

[v1.15.2] - 2023-12-29

Added

  • new patch webhook endpoint to update only fields contained in the request

Changed

  • new webhook headers field to allow setting of up to 20 custom headers which will be sent when the webhook is triggered
  • update webhook response to return updated webhook

[v1.15.1] - 2023-12-08

Added

Changed

  • The-Payload webhook generic payload additional fields for tenantID,correlationID,correlationTimestamp

[v1.15.3] - 2024-01-18

Changed

[v1.15.0] - 2023-11-22

Added

Changed

  • advisors advisors responses now have url field in responses when applicable
  • create webhook obsolete id field is removed

[v1.14.1] - 2023-11-20

Added

[v1.14.0] - 2023-11-08

Added

  • new advisors group
    • allows creation of cockpit advisors which have a cockpit-link to share with customers

[v1.13.0] - 2023-10-27

Added

  • new webhooks
    • transactions.raw uncategorized transactions
    • cockpit.approved customer approved cockpit and can now be accessed
  • endpoint for retrieving user by using customUserID

[v1.12.0] - 2023-10-09

Added

  • user scopes feature to create users with reduced calculations and later update users to expand calculations
    • users.CreateUser request model update
      • optional field name for username
      • optional field scopes to create a user with reduced calculations
    • users.UserScopes new endpoint to expand and start calculations for a given user

[v1.11.2] - 2023-08-22

Added

  • Note on standingOrderId (updates at each sync)

[v1.11.1] - 2023-06-28

Added

  • companies.companies-search-logos response code 200 new status enum type usage forbidden for disallowed logos

[v1.11.0] - 2023-04-20

Changed

  • contracts.Get Contracts response model transactions now only contain transactionId
  • banking.Create Management Session and Create Connect User Session now have additional query parameters demo and multiple
  • banking.Create Synchronization Session additional response case status 422

[v1.10.0] - 2023-03-23

Changed

  • Search Logos response added fields for squareLogoURL and companyID
  • Get Company Cockpit added calculations to response model
    • Liquidity
    • CollectivePayments
    • Cashflow
    • Graphs
    • AccountData
    • SavingSecurities
    • InternalContracts
  • Get Person Cockpit added calculations to response model
    • Overview.Income
    • Income
    • HouseholdExpenditure
    • SavingSecurities
    • InternalContracts
    • AccountHistoies

Removed

[v1.9.1] - 2023-01-10

Added

  • Detailed description of the Feedback module in theFeedback section

Fixed

  • Feedback payload body

[v1.9.0] - 2022-09-08

Removed

  • Clients section

Changed

  • banking scope Get Accounts 204 Status code response for no accounts found
  • Update contract model with additional fields
    • Attributes
    • Contract.ContractPartner
      • Id
      • AdditionalInfos
      • Logos
    • Contract.ContractPartner.Contact
      • PreferredContact

[v1.8.0] - 2022-04-25

Added

  • GET Money Transfer EP
  • Field supportedPayments to Accounts model
    • Possible Values:
      • SINGLE_MONEY_TRANSFER (supports one transaction per money transfer)
      • COLLECTIVE_MONEY_TRANSFER (supports multiple transactions in one money transfer)

[v1.7.0] - 2022-03-25

Added

  • Cockpit-Link Endpoint description
  • Correlation (cockpit) description

Fixed

  • Param descriptions in get_company_cockpit and get_person_cockpits

[v1.6.0] - 2022-03-09

Added

  • Account type Field for session and user creation
    • whitelists account types to be shown during login

[v1.5.0] - 2022-01-28

Added

  • Get Correlation endpoints for banking, contracts and categorization
  • PATCH /banking/accounts/:account-id

[v1.4.0] - 2022-01-21

Added

  • Feedback section

[v1.3.0] - 2022-01-12

Added

  • Cockpit section and description of what a cockpit is and how it can be created
  • Person Cockpit and Company Cockpit endpoints get a cockpit in json format
  • StandingOrders have IDs

[v1.2.0] - 2021-11-19

Added

  • Categorization endpoint group to get categorized transactions and allow the user to set custom tags

Changed

  • Clarify Authentication request body description for generate and refresh Token cases

[v1.1.0] - 2021-10-21

Added