---
title: "Propose Bank Mapping"
method: POST
path: "/onboarding/propose-bank-mapping"
tags: ["onboarding"]
---

# Propose Bank Mapping

`POST /onboarding/propose-bank-mapping`

## Request

- Base URL: `https://app.zeno-works.ch` (the document declares no server; this is the origin it was published from)
- URL: `https://app.zeno-works.ch/onboarding/propose-bank-mapping`
- Auth: none declared

Propose a ledger account for each submitted IBAN via the accountant (eligible).

Stateless. Drives the same "Suggest account" capability whether the IBAN came from a
statement upload or was typed manually. An empty chart returns ``needs_review`` for
every IBAN with no accountant call. **503** when the accountant is unreachable/failed.
Rate-limited per user (LLM call).

## Headers

- `authorization` string, nullable

## Cookies

- `access_token` string, nullable

## Request body

- ProposeBankMappingRequest: Inputs for a stateless bank-account → ledger-account proposal (no company needed). ``chart_accounts`` is the (already standardized) chart the proposal picks from. An empty chart yields ``needs_review`` proposals (nothing to map onto), with no accountant call.
  - `settings` OnboardingSettingsIn: The accounting settings the wizard collects (defaults applied in the service).
    - `fiscal_year_start_month` integer
    - `base_currency` string
    - `opening_balance_account_number` string
    - `ar_revenue_default_account_code` string, nullable
    - `vat_liable` boolean, nullable
    - `settlement_method` 'effective' | 'net_tax_rate' | 'flat_tax_rate' | 'unknown'
    - `timing_basis` 'agreed' | 'collected' | 'unknown'
    - `filing_period_type` 'monthly' | 'quarterly' | 'semi_annual' | 'annual' | 'unknown'
    - `uid` string, nullable
    - `canton` string, nullable
    - `vat_period_start` string, date, nullable
    - `vat_period_end` string, date, nullable
    - `ar_default_due_days` integer, nullable
  - `chart_accounts` OnboardingChartAccountIn[]
    - `account_number` string, required
    - `account_name` string, nullable
    - `category` 'asset' | 'liability' | 'equity' | 'income' | 'expense' | 'tax' | 'other' | 'unknown': The account-type axis of a ledger account (Swiss-KMU chart of accounts). Distinct from — but derived from — ``LineRole`` (the journal-line semantic role). ``unknown`` is the conservative default when classification can't decide; ``other`` covers genuinely ambiguous / closing (9xxx) accounts.
    - `is_profit_loss` boolean
    - `is_contra` boolean
    - `is_intentional` boolean
    - `account_number_guess` string, nullable
    - `journal_usage_count` integer
    - `prior_year_turnover_cents` integer, nullable
    - `prior_year_turnover_fiscal_year` integer, nullable
  - `vat_rates` OnboardingVatRateIn[]
    - `code` string, nullable
    - `rate_bps` integer, required
    - `name` string, nullable
    - `kind` string, nullable
    - `revenue_account_code` string, nullable
    - `valid_from` string, date, nullable
    - `valid_to` string, date, nullable
    - `active` boolean
  - `accounts` BankMappingHintIn[]
    - `iban` string, required
    - `owner_name` string, nullable
    - `bank_name` string, nullable
    - `currency` string, nullable
  - `language` 'de' | 'en' | 'fr' | 'it', nullable

## Response `200`

Successful Response

- ProposeBankMappingResponse: ``POST /onboarding/propose-bank-mapping`` → one proposal per submitted IBAN.
  - `proposals` BankMappingProposal[]
    - `iban` string, required
    - `ledger_account_number` string, nullable
    - `account_name` string, nullable
    - `status` string
    - `confidence` number
    - `rationale` string

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/zeno-works/apis/zeno-api.md) · [All operations](https://skmtc.dev/zeno-works/apis/zeno-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zeno-works/apis/zeno-api/revisions/1eb93dde146c?raw)