Finch API-documentatie
Koppel je tools aan Finch met onze alleen-lezen API. Bouw aangepaste dashboards, automatiseer rapporten en vraag saldi, transacties en vermogen op — allemaal met Zwitserse beveiliging.
Aan de slag
- 1Download de Finch-app op je mobiele apparaat.
- 2Vraag API-toegang aan via Menu > Klantenservice en neem contact op met ons team.
- 3Volg de gedetailleerde instructies hieronder om je API-key te verkrijgen en je gegevens op te halen!
Kern-endpoints
Accountsaldi
Haal realtime saldi op voor gekoppelde banken, kaarten en beleggingsrekeningen.
Transacties
Exporteer of doorzoek transactiegeschiedenis met filters op datum, rekening, categorie en valuta.
Beveiliging
Bankwaardige encryptie, alleen-lezen tokens en beperkte toegang houden je gegevens veilig.
Dekking
Werkt met Zwitserse banken, internationale platforms zoals Revolut en Wise, en beleggingstickers.
Get your API key
(Documentation only available in English)
Keys are created in the Finch app only (iOS or Android, version 0.4.7 or later). There is no web sign-in and no web key management. Go to Settings → Developer Portal — the entry appears only while the feature is enabled for your account.
- 1Turn on Developer mode.
- 2Tap Generate API key.
- 3Give it a Name (up to 60 characters, e.g. “Claude Desktop”).
- 4Choose Permissions — at least one, there is no “all”: accounts:read (accounts and balances), transactions:read (transactions), chat:write (send chat messages, uses your AI credits).
- 5Choose Expires after: 30, 60 or 90 days. 90 days is the maximum and the server enforces it.
- 6The key is shown once and copied to your clipboard automatically. It cannot be retrieved again — the app only shows the prefix afterwards. If you lose it, revoke it and create a new one.
Rules
- Maximum 5 active keys per user. Creating a sixth fails until one is revoked or expires.
- Revoke takes effect immediately, per key or with Revoke all keys if you suspect a leak.
- The key list shows name, prefix, permissions, created, expires, last used and last-used IP.
Quickstart
Base URL: https://api.fjnch.ch/v1. Send your key as a bearer token on every request: Authorization: Bearer fnch_sk_live_XXXXXXXX…. Keys look like fnch_sk_live_ followed by 43 URL-safe base64 characters. Treat one like a password and never commit it. Replace YOUR_API_KEY in every sample below.
1. Check your key
curl https://api.fjnch.ch/v1/me \
-H "Authorization: Bearer YOUR_API_KEY"Expected shape: { uid, currency, tier, scopes }.
2. List your accounts
curl https://api.fjnch.ch/v1/accounts \
-H "Authorization: Bearer YOUR_API_KEY"An array of active accounts. Fields include id, name, type, currency, balance, bank, iban, syncStatus, lastSyncedAt.
3. Read transactions
curl "https://api.fjnch.ch/v1/transactions?accountId=ACCOUNT_ID" \
-H "Authorization: Bearer YOUR_API_KEY"Newest first. accountId is required; without it the API answers 400. Fields include id, amount, currency, type, date, description and the category and tag relations.
Reference
/v1/meaccounts:readReturns { uid, currency, tier, scopes }. The cheapest way to check that a key works.
Example response
Errors
- 401 — missing, invalid, expired or revoked key
- 404 — the API is switched off for this user
/v1/accountsaccounts:readAn array of your active accounts with balances. Data is cached; no bank sync is triggered.
Fields include
Example response
Errors
- 401 — invalid key
- 403 — key lacks accounts:read
/v1/accounts/{id}accounts:readA single account.
Fields include
Example response
Errors
- 403 — key lacks accounts:read
- 404 — unknown account
/v1/transactions?accountId={id}transactions:readTransactions for one account, newest first. accountId is required.
Fields include
Example response
Errors
- 400 — missing accountId
- 403 — key lacks transactions:read
/v1/transactions/{id}transactions:readA single transaction with its category and tags.
Fields include
Example response
Errors
- 403 — key lacks transactions:read
- 404 — unknown transaction
/v1/usageaccounts:readYour remaining AI allowance and the state of the hourly chat window.
Example response
Errors
- 401 — invalid key
- 403 — key lacks accounts:read
/v1/chat/messageschat:writeSends a chat message and returns the full reply as one JSON object. There is no streaming. This spends your AI credits.
Request body:
{
"message": "How much did I spend on groceries last month?",
"conversationId": "optional — continue an existing conversation",
"rag": true
}Response: { conversationId, message, ...metadata from the assistant }. rag defaults to true and lets the assistant search your transactions.
Example response
Errors
- 400 — invalid chat body
- 402 — monthly AI allowance used up (code: AI_BUDGET_REACHED)
- 403 — key lacks chat:write
- 429 — 30 messages per hour window (code: RATE_LIMITED)
Limits & errors
Limits
- 120 requests per minute per key, sliding window. Over the limit you get 429 with a Retry-After value in seconds.
- Reads return cached data and never trigger a bank sync. Each account carries lastSyncedAt so you can tell how fresh it is. Polling refreshes nothing — refresh in the app.
- Chat shares your in-app allowance: the same monthly AI budget and the same 30 messages per hour window. A key does not get a second budget.
- Every plan limit that applies in the app applies through the API.
What the API will not do
- No writes: no creating accounts, transactions, categories or budgets. Chat is the only POST.
- No bank connection or refresh through the API.
- No access to any data but the key owner’s.
- No webhooks and no OpenAPI download.
| Status | When | Body |
|---|---|---|
| 401 | Missing, invalid, expired or revoked key | { "statusCode": 401, "message": "No API key provided" } or "Invalid API key" |
| 403 | Key lacks the scope, or the account is temporarily locked | { "statusCode": 403, "message": "…" } |
| 404 | Unknown account or transaction, or the API is switched off for this user | { "statusCode": 404 } |
| 400 | Missing accountId, or invalid chat body | validation message |
| 402 | Chat: monthly AI allowance used up (code: AI_BUDGET_REACHED) | { code, message } |
| 429 | 120/min key limit, or chat 30/hour window (code: RATE_LIMITED) | { code, message, retryAfterSeconds } |
Repeated invalid keys from one IP count toward Finch’s login lockout. A client that retries a dead key in a loop will get its IP blocked for a while.
Security
- Treat the key as a password. The fnch_sk_live_ prefix is recognised by secret scanners — never commit it.
- Keys expire after 30, 60 or 90 days; 90 is the maximum.
- Revoke immediately on any suspicion, per key or with “Revoke all keys”.
- Never put a key in a URL, a commit, or a screenshot. Send it only in the Authorization header.
- Scopes are least-privilege: grant only what the tool needs.
- chat:write spends money — grant it only to tools you trust.
- A Finch app session token is not accepted on /v1, and an API key is not accepted anywhere outside /v1, including key management.
Use with an AI assistant
Any tool that can make an HTTP request with a header can use the API: a Claude Desktop custom connector, a ChatGPT action, or a short script. Point it at https://api.fjnch.ch/v1, add the header Authorization: Bearer YOUR_API_KEY, and start from the Quickstart above. Give the tool only the scopes it needs — and remember that chat through the API bills the same AI credits as chatting in the app.
An assistant you hand a key to can read everything that key allows. Use a short expiry and revoke it when you are done experimenting.
Changelog
v1 — accounts, transactions, usage, chat (beta).
Access & Support
The Finch API is open to app users, Finch community members, and partners who want to build with their financial data. Reach out to request access and documentation.
Request API Access