FinoOS2 Documentation (1.18.4)

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

customUserID
string

Optional CustomUserID of the created user.

name
string

Optional Name of the created user.

type
string
Enum: "person" "company"
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
{
  • "customUserID": "string",
  • "name": "string",
  • "type": "person",
  • "userScopes": [
    ]
}

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": "string",
  • "customUserID": "string",
  • "duplicates": [
    ],
  • "id": "string",
  • "tenant": "string",
  • "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": {
    }
}

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": "string",
  • "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

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

Add transactions to External Accounts

Scope: banking

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 External Accounts

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 Account Properties

Scope: banking

path Parameters
user-id
required
string

The user id of the finoOS user

account-id
required
string

The account id

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

status
string
Enum: "enabled" "disabled"

Status The accounts status. Must be one of enabled or disabled. Default value is enabled.

Responses

Request samples

Content type
application/json
{
  • "status": "enabled"
}

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

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.

multiple
string

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

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

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

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

List of account types to be shown during login

errorURL
required
string

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

exitURL
required
string

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

persistNonRecurring
boolean

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

recurring
boolean
Default: false

Whether this shall be a recurring user or not

redirectURL
required
string

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

storeSecrets
boolean

Whether the bank login credentials should be stored or not

Responses

Request samples

Content type
application/json
{}

Get Correlation

Scope: banking

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Disconnect User

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

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

User-IP
required
string

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

Responses

Response samples

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

Get Logins Synchronization Status

Scope: banking

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

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete Login

Scope: banking

Delete a connected bank login of the user.

path Parameters
user-id
required
string

The user id of the finoOS user

banklogin-id
required
string

The bankLoginId of the accounts to be deleted

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

The authorization token

TenantID
string

The client's tenant

User-IP
required
string

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

Responses

Response samples

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

Money Transfer

Scope: banking

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

path Parameters
user-id
required
string

The user id of the finoOS user

banklogin-id
required
string

The id of BankLogin to execute the money transfer on

header Parameters
Authorization
required
string

The authorization token

User-IP
required
string

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

Request Body schema: application/json
required

The payload of the request

accountId
string

Internal AccountID

executionDate
string

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

exitUrl
string

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

fallbackUrl
string

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

Array of objects (banking.MoneyTransferInfo)

Holds all user input for a single money transfer

redirectUrl
string

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

singleBooking
boolean

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

Responses

Request samples

Content type
application/json
{}

Response samples

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

Get Money Transfer

Scope: banking

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

path Parameters
user-id
required
string

The user id of the finoOS user

banklogin-id
required
string

The id of BankLogin the money transfer was executed on

money-transfer-id
required
string

The id of the money transfer

header Parameters
Authorization
required
string

The authorization token

User-IP
required
string

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

Responses

Response samples

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

Create Management Session

Scope: banking

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

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

The user id of the finoOS user

query Parameters
addBankLogin
required
string

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

demo
string

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

multiple
string

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

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

The authorization token

TenantID
string

The client's tenant

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

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

List of account types to be shown during login

bankLoginId
string

The ID of the bank login to be synchronized

errorURL
string

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

exitURL
string

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

redirectURL
string

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

Responses

Request samples

Content type
application/json
{}

Connect User Mock

Scope: banking

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

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

userName
string

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

Responses

Request samples

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

Response samples

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

Create Synchronization Session

Scope: banking

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

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

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

User-IP
required
string

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

Request Body schema: application/json
required

The payload of the request

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

List of account types to be shown during login

bankLoginId
string

The ID of the bank login to be synchronized

errorURL
string

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

exitURL
string

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

redirectURL
string

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

Responses

Request samples

Content type
application/json
{}

Response samples

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

Get Transactions

Scope: banking

Returns all transactions for this user

path Parameters
user-id
required
string

The user id of the finoOS user

query Parameters
since
string

RFC3339 formatted timestamp for inclusive filtering

until
string

RFC3339 formatted timestamp for inclusive filtering

transactionIds
string

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

lastMonths
string

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

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Categorization

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.

Get Categorization

Returns a paginated list or current tags for transactions. Use the correlation-id query parameter to only retrieve the recent changes on tagging

path Parameters
user-id
required
string

The user id of the finoOS user

query Parameters
correlation-id
string

optional: return diff of newly added tags for transactions since the provided correlation

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": [
    ]
}

Account-Detection

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

Get Account Detection

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

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Get Correlation

Scope: account-detection

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Account-History

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

Get Account History

Scope: account-history

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

path Parameters
user-id
required
string

The user id of the finoOS user

header Parameters
Authorization
required
string

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Get Correlation

Scope: account-history

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Contracts

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

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

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

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

Get Contracts

Scope: contracts

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

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete Contracts

Scope: contracts

Delete all contracts of the specified user

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Get Correlation

Scope: contracts

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Delete Contract

Scope: contracts

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

path Parameters
user-id
required
string

The user id of the finoOS user

contract-id
required
string

The id of the contract to be deleted

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Companies

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

Search Companies

Scope: companies

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

query Parameters
logo-size
integer

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

header Parameters
Authorization
required
string

The authorization token

Request Body schema: application/json
required

queries

required
Array of objects (companies.CompanyQuery)

Responses

Request samples

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

Response samples

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

Search Logos

Scope: companiesLogo

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

query Parameters
exactMatch
boolean

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

fuzziness
string

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

logo-size
integer

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

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

The authorization token

TenantID
string

The client's tenant

Request Body schema: application/json
required

The payload of the request

required
Array of objects (companies.LogoQuery)

The queries to search for the logos

Responses

Request samples

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

Response samples

Content type
application/json
{}

Cockpits

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

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

Get Cockpits paginated

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

query Parameters
page
integer

the page number (default: 1)

page-size
integer

ths page size (default: 20 min: 2)

advisor-id
string

search cockpits for the specified advisor-ID

custom-user-id
string

search cockpits for the custom-user-ID

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Get Company Cockpit

Scope: cockpits Webhook Event: companycockpit

Returns a company cockpit in json format.

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Get Correlation

Scope: cockpit

path Parameters
user-id
required
string

The user id of the finoOS user

query Parameters
correlation-id
string

If specified, the corresponding correlation is returned

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

Get Cockpit PDF

Returns a cockpit in the pdf format

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Get Person Cockpit

Scope: cockpits Webhook Event: personcockpit

Returns a person cockpit in json format.

path Parameters
user-id
required
string

The user id of the finoOS user

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

The authorization token

TenantID
string

The client's tenant

Responses

Response samples

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

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
{
  • "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",
  • "modifiedAt": "string",
  • "modules": {