Skip to main content

Adding Data

Scopes Required: banking-upload

Create External Accounts​

This endpoint allows you to add new bank accounts for a user. Use it when you already have the user's banking data and do not rely on the Banking UI.

Endpoint: POST /users/{user-id}/banking/accounts

What's Possible​

  • Add one or multiple external accounts for a user.
  • Include account metadata: balance, bank name, IBAN, owner, account type, and optional visuals like icons.
  • Include transactions, securities, or standing orders associated with the account.
  • Override existing accounts if accountId and accountNumber match.

Model​

  • accountId - Internal identifier for the account
  • accountNumber - Domestic account number
  • balance - Current account balance
  • bankCode - Bank's internal code
  • bankName - Name of the bank
  • bic - Bank Identifier Code
  • currency - ISO 4217 currency code
  • iban - IBAN of the account
  • icon - URL to bank's logo/icon
  • name - Friendly account name
  • owner - Name of account owner
  • type - Account type (GIRO, KREDIT_KARTE, DEPOT, etc.)
  • transactions - Array of transactions to pre-fill the account
  • securities - For DEPOT accounts
  • standingOrders - Pre-existing recurring payments

Journey / Narrative​

You have raw banking data for your user. Send a POST request with account metadata and optionally transactions. finoOS creates the account, stores metadata, and links any transactions, securities, or standing orders you provided. If an account with the same accountId and accountNumber exists, it will be replaced.

Add Transactions to an Existing Account​

After creating an account, you can add transactions to it.

Endpoint: POST /users/{user-id}/banking/accounts/{account-id}/transactions

What's Possible​

  • Upload one or multiple transactions to an existing account.
  • Include payment metadata such as bookingText, purpose, merchantCategoryCode, paymentPartner.
  • Add detailed timestamps: bookingDate (when booked) and valueDate (when funds available).
  • Prevent duplicates by providing unique transactionId.
  • Overwrite existing transactions by re-uploading with the same transactionId.

Model​

  • transactionId - Unique ID for each transaction
  • amount - Transaction amount
  • currency - ISO 4217 currency code
  • bookingDate - Unix timestamp of booking
  • valueDate - Unix timestamp when funds are available
  • bookingText - Description of transaction
  • purpose - Purpose of transaction
  • paymentPartner - Merchant or service provider details
    • bic - Bank Identifier Code
    • creditorId - Creditor identifier
    • iban - IBAN of the merchant
    • name - Name of the merchant
  • differentCreditor / differentDebitor - Ultimate payer/receiver if different from paymentPartner
  • eref / mref - Reference numbers
  • merchantCategoryCode - Four-digit merchant classification code
  • sepaPurposeCode - Four-character SEPA classification code
  • transactionCode - Classification ID (typically a one- to three-digit code)

Journey / Narrative​

Prepare transaction data from your source system. Ensure each transaction has a unique transactionId. Send a POST request to the account endpoint with the transaction array. finoOS adds transactions to the account. Duplicate transactionIds overwrite the existing transaction automatically.