Finance & Payments pack

Bank accounts CSV import API

Import bank account records from any CSV with IBAN mod-97 and BIC validation built in. Multilingual headers handled at zero cost.

Try in Workbench Quickstart

30-second curl

curl -X POST https://api.adaptivmapr.com/v1/uploads \
  -H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \
  -F "template=bank_accounts_v1" \
  -F "file=@your_data.csv"

→ 6 canonical fields · 2 validated · high risk

Canonical columns

The whole schema, printed as it ships.

Every canonical column, the type each row carries, whether it is required, the field-level validators that fire on commit, and the multilingual header hints the cascade resolves against. This is the shipped definition, not a summary of it.

bank_accounts_v1

fields: 6
required: 2
validated: 2
hints: 26

Canonical column	Type	Required	Validators	Header hints the cascade matches
`account_holder`	string	yes	—	kontoinhabertitulairetitolareaccount holdertitular
`iban`	string	yes	`iban`	ibancomptekontobank account
`bic`	string	—	`bic`	bicswiftswift code
`account_number`	string	—	—	kontonummernuméro de comptenumero di contoaccount numbernúmero de cuenta
`routing_number`	string	—	—	bankleitzahlblzcode guichetabarouting
`currency`	string	—	—	währungdevisevalutamoneda

Read the same definition as JSON at GET /v1/templates/bank_accounts_v1. A hint match resolves on layer 2 — no LLM call, no token spend, just the flat per-map fee. Hover a validator id to see what it checks.

6 canonical fields
2 required
2 validated
26 header hints, 5 languages

Why it exists

Written for the file you actually receive.

The Bank accounts template is the canonical schema for payee and beneficiary banking detail — the file a treasury export, a supplier-payment list, or a payout-account directory reduces to. Each row carries an account_holder (required), an IBAN (required, validated), an optional BIC/SWIFT, an account_number and routing_number for non-IBAN regions, and a currency. Finance and treasury teams reach for it when onboarding a new payments rail, when migrating a payee master between ERPs, and when consolidating banking detail after an acquisition. The IBAN is the load-bearing field: it runs mod-97 validation with a country restriction (CH, LI, DE, FR, IT, ES by default) so a transposed digit is caught before a failed transfer costs a return fee. Because banking detail is regulated data, schema-only mode is the default ingress — raw account rows never leave the customer; only headers and clamped sample cells are processed to make the mapping decision.

Two validators do the heavy lifting: IBAN runs mod-97 in chunks (no BigInt needed, so it works inside a Cloudflare Worker) and rejects out-of-country-list IBANs at import; BIC is checked against the SWIFT format (8 or 11 alphanumerics). account_holder and iban are required; bic, account_number, routing_number, and currency are optional so both IBAN-region and ABA-region files ingest cleanly. Hints cover DE / FR / IT / ES / EN naming so a multilingual treasury export does not fall through to the LLM.

Migration scenarios & the foreign headers they ship

Migration scenarios for the Bank accounts template: standing up a new payments or payroll rail that needs a clean payee master on day one, migrating a beneficiary list between ERPs (SAP → NetSuite, Sage → Xero), consolidating banking detail after a group acquisition, and quarterly refreshes of supplier payout accounts. Foreign headers we see in the wild: "Kontoinhaber / Titulaire / Titolare / Titular / IBAN / Compte / Konto / BIC / SWIFT / Kontonummer / Numéro de compte / Numero di conto / Número de cuenta / Bankleitzahl / BLZ / Code guichet / ABA / Routing / Währung / Devise / Valuta / Moneda". The cascade absorbs the cross-language variation through the registered hints and never escalates to the paid layer — the mod-97 IBAN check then catches the typos before they reach the bank.

The cascade

Six layers, and the cheapest one wins.

Layers run in order and stop the moment a column resolves. That is the single biggest cost lever in the system: a column caught on layer 2 never reaches the metered layer 5.

L1Statisticsno LLM
Auto-accepts a header that past confirmations already resolved the same way, at {minN:100, minRatio:0.95} or {minN:20, minRatio:1.00}.
L2Heuristicno LLM
Normalises accents, punctuation and whitespace, then compares against the column name, the label, and every registered hint (DE / FR / IT / EN / ES).
L3Fuzzyno LLM
Token-set ratio plus Levenshtein over the normalised strings. Auto-accepts at 0.80 — it absorbs typos and reordered words.
L4Semanticcheap, cached
Embedding cosine between the header and the field’s label + hints. Catches the long tail of paraphrases.
L5LLMmetered
Everything still unresolved goes up in ONE batched, collision-aware call, constrained to this template’s column set so it cannot invent a field.

Try it

One template id, two ways in.

REST for your import pipeline, MCP for your editor. Both run the same cascade and both honour the same schema-only clamp.

REST · POST /v1/uploads

Name the template; the cascade picks up the rest. The canonical definition is read-only at GET /v1/templates/bank_accounts_v1.

bash

curl -X POST https://api.adaptivmapr.com/v1/uploads \
  -H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \
  -F "template=bank_accounts_v1" \
  -F "file=@your_data.csv"

→ upload created · mappings ready · confirm before commit

MCP · Cursor / Claude Desktop

Drop AdaptivMapr into your editor and call the same cascade as a tool. Schema-only calls leave only column names and up to three clamped sample rows.

mcp

// In Cursor or Claude Desktop with the AdaptivMapr MCP server installed:
adaptivmapr.match_headers({
  template_id: "bank_accounts_v1",
  headers: ["account_holder", "iban", "bic", "account_number"]
})

schema-only · headers and ≤3 rows, 80 chars each

MCP install instructions

high-risk template

The mappings response comes back flagged. PATCH /uploads/:id/mappings returns requires_hitl: true and hitl_status: "pending_review" so you can hold the commit in your own workflow — the flag is a signal, not a queue we run. Schema-only mode (headers plus at most three sample rows, each clamped to 80 characters) is a data-minimization mode enforced at the HTTP edge. Full-data mode routes the metered layer-5 call to phi-cloud in-region under a BAA, costs 20% more on the whole map charge, and stays locked until the workspace accepts the BAA/NDA in Settings → Security & Data.

How the wallet is charged

Questions

Bank accounts CSV import — FAQ

What if my account list crosses the IBAN country restriction?

Fork the template and broaden the `countries` array on the IBAN validator. The default allow-list is CH / LI / DE / FR / IT / ES; the validator otherwise treats an out-of-list IBAN as a hard reject at import.

Can I import US accounts that have no IBAN?

The canonical template marks IBAN as required because most regulated EU/CH payment flows depend on it. For ABA-region files, fork the template to make iban optional and rely on account_number + routing_number instead.

Does AdaptivMapr verify the account against the bank?

No — only the IBAN mod-97 checksum and BIC format are verified locally. Live account verification (e.g. confirmation-of-payee) is a separate, paid banking service; the cascade stays offline-safe.

How is banking data protected during mapping?

Schema-only mode is the default: only headers and three clamped sample rows (≤80 chars each) are processed. Full account rows never leave your environment unless you opt into full-data mode under an active subscription.

Map bank accounts in production — without shipping raw records.

Schema-only mode leaves only headers and a handful of clamped samples. Add full-data when you need row-level AI, routed in-region under a BAA.

Get an API key More Finance & Payments templates →