API docs by Redocly

FinoOS2 Documentation (1.20.20)

Download OpenAPI specification:Download

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

Introduction

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

Legacy API finoOS1 Documentation: legacy.

Principles

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

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

Errors

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

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

Status Codes and Errors

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

Authentication

To authenticate yourself with the finoOS API, you exchange your client identifier and client secret for a temporary valid pair of JSON web tokens(JWT) via the Authenticate endpoint. The returned accessToken has to be provided in every following request via the Authorization header.

Authentication

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

Generate new token with:

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

5d7267d1b747aa683d88668f

client_secret
required
string

5d7267d1b747aa683d88668f

grant_type
required
string

client_credentials

Responses

Response samples

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

Scopes

Your client is assigned a set of scopes on creation. Scopes define which service or endpoints can be used with your client. For now, this can only be done manually by one of our engineers. If you want to book or cancel a certain scopes or services, please contact us.

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

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

Users

Users in the finoOS API represent the end-user of your application. All services that require some kind of data persistence are only usable in connection with a user.

Get Users

Gets all users paginated.

query Parameters
page
string

The page of users to retrieve

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Add User

Adds a user.

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

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

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

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

customUserID
string

Optional CustomUserID of the created user.

name
string

Optional Name of the created user.

type
string
Enum: "person" "company"

Type of the user.

userScopes
Array of strings

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

Responses

Request samples

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

Response samples

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

Update User

Updates a user.

header Parameters
Authorization
required
string

The authorization token

tenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

automaticAnalysis
string
Enum: "suspended" "active"

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

customUserID
string

Optional CustomUserID of the created user.

name
string

Optional Name of the created user.

Responses

Request samples

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

Response samples

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

Get User using customUserID

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

path Parameters
custom-user-id
required
string

The customUserID id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Delete Users

Delete multiple user.

header Parameters
Authorization
required
string

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

userIDs
Array of strings

Responses

Request samples

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

Response samples

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

Import User with External Accounts

Scope: banking or banking-upload and cockpits

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

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

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

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

The authorization token

Request Body schema: application/json
required

The payload of the request

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

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

customUserID
required
string

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

name
string

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

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

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

type
string
Enum: "person" "company"

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

Responses

Request samples

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

Response samples

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

Get User

Get a user.

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Delete User

Delete a user.

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Add scopes to user

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

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

userScopes
Array of strings

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

Responses

Request samples

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

Response samples

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

Trigger a new analysis for user.

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

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Banking

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

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

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

Get Accounts

Scope: banking

path Parameters
user-id
required
string

The user id of the finoOS user

query Parameters
includeTransactions
boolean

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

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Create External Accounts

Scope: banking,banking-upload

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

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

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

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

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

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

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

Responses

Request samples

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

Response samples

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

Delete External 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
{
  • "IDs": [
    ]
}

Response samples

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

Patch External Accounts

Scope: banking,banking-upload

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

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

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

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

Array of objects

Responses

Request samples

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

Response samples

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

Delete External 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
{
  • "message": "string",
  • "type": "invalidInput"
}

Patch transactions for External Account

Scope: banking,banking-upload

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

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

path Parameters
user-id
required
string

The user id of the finoOS user

account-id
required
string

The account id of the account

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

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

Array of objects

Responses

Request samples

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

Response samples

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

Get Account Summary as PDF

Scope: banking

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

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

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

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

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

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

path Parameters
user-id
required
string

The user id of the finoOS user

account-id
required
string

The id of account to get the summary for

query Parameters
since
string

RFC3339 formatted timestamp for inclusive filtering

until
string

RFC3339 formatted timestamp for inclusive filtering

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
No sample

Add transactions to External Accounts

Scope: banking,banking-upload

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

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

path Parameters
user-id
required
string

The user id of the finoOS user

account-id
required
string

The account id of the account

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

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

required
Array of objects (banking.TransactionRequest)

Responses

Request samples

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

Response samples

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

Delete transactions from External Accounts

Scope: banking,banking-upload

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

path Parameters
user-id
required
string

The user id of the finoOS user

account-id
required
string

The account id of the account

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

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

ids
Array of strings

The transactionIds to delete for the account

Responses

Request samples

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

Response samples

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

Create Connect User Session

Scope: banking

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

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

The user id of the finoOS user

query Parameters
demo
string

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

bankCode
string

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

multiple
string

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

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

persistNonRecurring
boolean

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

recurring
boolean
Default: false

Whether this shall be a recurring user or not

redirectURL
required
string

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

storeSecrets
boolean

Whether the bank login credentials should be stored or not

Responses

Request samples

Content type
application/json
{}

Get Correlation

Scope: banking

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Disconnect User

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

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

User-IP
required
string

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

Responses

Response samples

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

Get Logins Synchronization Status

Scope: banking

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

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete Login

Scope: banking

Delete a connected bank login of the user.

path Parameters
user-id
required
string

The user id of the finoOS user

banklogin-id
required
string

The bankLoginId of the accounts to be deleted

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

The authorization token

TenantID
string

The client's tenant

User-IP
required
string

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

Responses

Response samples

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

Money Transfer

Scope: banking

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

path Parameters
user-id
required
string

The user id of the finoOS user

banklogin-id
required
string

The id of BankLogin to execute the money transfer on

header Parameters
Authorization
required
string

The authorization token

User-IP
required
string

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

Request Body schema: application/json
required

The payload of the request

accountId
string

Internal AccountID

executionDate
string

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

exitUrl
string

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

fallbackUrl
string

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

Array of objects (banking.MoneyTransferInfo)

Holds all user input for a single money transfer

redirectUrl
string

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

singleBooking
boolean

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

Responses

Request samples

Content type
application/json
{}

Response samples

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

Get Money Transfer

Scope: banking

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

path Parameters
user-id
required
string

The user id of the finoOS user

banklogin-id
required
string

The id of BankLogin the money transfer was executed on

money-transfer-id
required
string

The id of the money transfer

header Parameters
Authorization
required
string

The authorization token

User-IP
required
string

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

Responses

Response samples

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

Create Management Session

Scope: banking

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

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

The user id of the finoOS user

query Parameters
addBankLogin
string

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

bankCode
string

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

demo
string

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

multiple
string

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

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

Request samples

Content type
application/json
{}

Connect User Mock

Scope: banking

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

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

userName
string

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

Responses

Request samples

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

Response samples

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

Create Synchronization Session

Scope: banking

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

  • 204: The synchronization was successful and you can query the latest bank accounts data via Get Accounts
  • 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
{
  • "active": true,
  • "bankLoginId": "507f1f77bcf86cd799439011",
  • "lastSynchronization": 1564102614,
  • "status": "OK"
}

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 samples

Content type
application/json
[
  • {
    }
]

Categorization

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

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

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

Returns a paginated list or current tags for transactions.

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

path Parameters
user-id
required
string

The user id of the finoOS user

query Parameters
page
integer

The page number. Default is 1.

pageSize
integer

The number of transactions to return. Default is 10.

correlationID
string

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

accountId
string

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

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Get Correlation

Scope: categorization

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Get Patterns

Returns a list of patterns that the user has added

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Add or update patterns

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

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload with patterns

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

Responses

Request samples

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

Get Transactions

Returns the transactions of the user with the current valid tags

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Get Categorization for transaction

Returns the current tags of a transaction

path Parameters
user-id
required
string

The user id of the finoOS user

transaction-id
required
string

The transaction id

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Categorization-Tree

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

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

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 samples

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

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 samples

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

Account-Detection

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

Get Account Detection

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

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Get Correlation

Scope: account-detection

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Account-History

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

Get Account History

Scope: account-history

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

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Get Correlation

Scope: account-history

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Contracts

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

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

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

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

Get Contracts

Scope: contracts

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

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete Contracts

Scope: contracts

Delete all contracts of the specified user

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Get Correlation

Scope: contracts

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Delete Contract

Scope: contracts

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

path Parameters
user-id
required
string

The user id of the finoOS user

contract-id
required
string

The id of the contract to be deleted

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Companies

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

Search Companies

Scope: companies

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

query Parameters
logo-size
integer

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

header Parameters
Authorization
required
string

The authorization token

Request Body schema: application/json
required

queries

required
Array of objects (companies.CompanyQuery)

Responses

Request samples

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

Response samples

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

Search Logos

Scope: companiesLogo

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

query Parameters
exactMatch
boolean

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

fuzziness
string

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

logo-size
integer

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

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

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

required
Array of objects (companies.LogoQuery)

The queries to search for the logos

Responses

Request samples

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

Response samples

Content type
application/json
{}

Cockpits

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

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

Get Cockpits paginated

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

query Parameters
page
integer

the page number (default: 1)

page-size
integer

ths page size (default: 20 min: 2)

advisor-id
string

search cockpits for the specified advisor-ID

custom-user-id
string

search cockpits for the custom-user-ID

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Get 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 samples

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

Get Company Cockpit

Scope: cockpits Webhook Event: companycockpit

Returns a company cockpit in json format.

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Get Correlation

Scope: cockpit

path Parameters
user-id
required
string

The user id of the finoOS user

query Parameters
correlation-id
string

If specified, the corresponding correlation is returned

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Get Cockpit PDF

Returns a cockpit in the pdf format

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

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 samples

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

Get Cockpit Recommendations

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

Returns cockpit recommendations in json format.

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Cockpit-Advisors

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

Get Advisors Paginated

Returns multiple advisors paginated

query Parameters
user-id
string

search users for the specified ID

user-name
string

filters users by the name (regexes possible)

email
string

filters users by the e-mail (regexes possible)

link-id
string

filters users by the link ID (regexes possible)

activated
boolean

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

since-last-activity
string

filters users by their last activity (inclusive)

until-last-activity
string

filters users by last activity (exclusive)

roles
Array of strings

filters users by their role

reportRoles
Array of strings

filters users by their report roles

reportAccess
boolean

Enable or disable access to the reports for the user

reportSend
boolean

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

header Parameters
Authorization
required
string

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Create Advisor

Create advisor user 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 user

linkID
string

LinkID of the user 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 user

onboardingMail
boolean

OnboardingMail

phoneNumber
string

PhoneNumber is an optional field representing the user phoneNumber

reportAccess
boolean

Enable or disable access to the reports for the user

reportInterval
string

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

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

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

reportSend
boolean

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

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

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

sendMail
boolean

SendMail notify user by email about every cockpit being created

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

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

welcomeMail
boolean

WelcomeMail

Responses

Request samples

Content type
application/json
{
  • "avatar": "https://this.is.a.link.to.an.avatar.de/image.jpg",
  • "linkID": "string",
  • "mail": "consultant-max-mustermann@huk.com",
  • "name": "max mustermann",
  • "onboardingMail": true,
  • "phoneNumber": "0123456789",
  • "reportAccess": false,
  • "reportInterval": "0 0 1W * *",
  • "reportRole": "report-tenant, report",
  • "reportSend": false,
  • "role": "tenantadmin, tenant-manager, employee",
  • "sendMail": true,
  • "type": "person, company, person-company, company-person",
  • "welcomeMail": true
}

Response samples

Content type
application/json
{}

Get Advisor

Returns one advisor

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

Responses

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
{
  • "message": "string",
  • "type": "invalidInput"
}

Patch Advisors

Returns patched advisor 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

avatar
string

Avatar contains a picture of the user

deactivated
boolean

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

linkID
string

New LinkID of the user 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 user

phoneNumber
string

PhoneNumber is an optional field representing the user phoneNumber

reportAccess
boolean

Enable or disable access to the reports for the user

reportInterval
string

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

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

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

reportSend
boolean

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

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

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

sendMail
boolean

SendMail notify user by email about every cockpit being created

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

New type of the user

Responses

Request samples

Content type
application/json
{
  • "avatar": "string",
  • "deactivated": true,
  • "linkID": "jjpt9o",
  • "mail": "consultant-max-mustermann@huk.com",
  • "name": "max mustermann",
  • "phoneNumber": "0123456789",
  • "reportAccess": true,
  • "reportInterval": "0 0 1W * *",
  • "reportRole": "employee",
  • "reportSend": true,
  • "role": "employee, companyadmin, superadmin",
  • "sendMail": true,
  • "type": "person"
}

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 samples

Content type
application/json
{
  • "fileHandle": "string",
  • "url": "string"
}

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
{
  • "message": "string",
  • "type": "invalidInput"
}

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 samples

Content type
application/json
{
  • "accentColor": "#002D67",
  • "createdAt": "string",
  • "createdByEvent": true,
  • "deactivated": true,
  • "displayName": "Huk",
  • "expireConfig": {
    },
  • "id": "4f155736-1824-4d82-9f1f-3d04a8ff6d84",
  • "logo": "https://cdn.fino.digital/tenants/stgng/fino-favicon-1.png",
  • "modifiedAt": "string",
  • "modules": {
    },
  • "name": "cockpit-huk",
  • "primaryColor": "#002D67",
  • "report": true,
  • "reportModules": {
    }
}

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

Request samples

Content type
application/json
{
  • "AdjustUsersPermission": true,
  • "accentColor": "#0000",
  • "deactivated": true,
  • "displayName": "Huk",
  • "expireConfig": {
    },
  • "logo": "https://this.is.a.logo.de/url/img.png",
  • "modules": {
    },
  • "primaryColor": "#0000",
  • "report": true,
  • "reportModules": {
    }
}

Response samples

Content type
application/json
{
  • "accentColor": "#002D67",
  • "createdAt": "string",
  • "createdByEvent": true,
  • "deactivated": true,
  • "displayName": "Huk",
  • "expireConfig": {
    },
  • "id": "4f155736-1824-4d82-9f1f-3d04a8ff6d84",
  • "logo": "https://cdn.fino.digital/tenants/stgng/fino-favicon-1.png",
  • "modifiedAt": "string",
  • "modules": {
    },
  • "name": "cockpit-huk",
  • "primaryColor": "#002D67",
  • "report": true,
  • "reportModules": {
    }
}

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 samples

Content type
application/json
{
  • "identity": {
    },
  • "observedMonths": 6,
  • "rental": {
    },
  • "salary": {
    },
  • "selfEmployment": {
    }
}

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 samples

Content type
application/json
{
  • "correlationID": "string",
  • "correlationTimestamp": "string"
}

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

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"

The module the feedback is about

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

The Type of the feedback influencing the Feedback object model

userID
string

Identifies the user sending the feedback

Responses

Request samples

Content type
application/json
{
  • "additionalInfo": {
    },
  • "content": "This is a feedback text with constructive criticism or praise.",
  • "feedback": { },
  • "module": "company-logos",
  • "type": "missing-logo",
  • "userID": "5dca8240-bfc1-4189-b8e2-09a776cd482b"
}

Response samples

Content type
application/json
{
  • "feedbackID": "5dca8240-bfc1-4189-b8e2-09a776cd482b"
}

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

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

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
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.

contracts

Type: object

Properties webhook data payload contains Contracts .

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
companycockpit

Type: object

Properties webhook data payload contains CompanyCockpit with the typecompany.

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.

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
renter-information

Type: object

Properties webhook data payload contains Renter-Information.

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 samples

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

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "string",
  • "secret": "string"
}

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

Responses

Request samples

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

Response samples

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

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
{
  • "message": "string",
  • "type": "invalidInput"
}

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

Responses

Request samples

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

Response samples

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

Server-Status

Get the current server status

Provides information whether the server is ready or not.

Responses

Response samples

Content type
application/json
{ }

CHANGELOG

Changelog

All notable changes to this project will be documented in this file.

[v1.20.20] - 2024-11-13

Fixed

[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

[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