Finch API-Dokumentation
(These developer docs are available in English only)
Verbinde deine Tools mit Finch über unsere Read-only-API. Erstelle individuelle Dashboards, automatisiere Berichte und rufe Salden, Transaktionen und Vermögensübersichten ab – alles mit Schweizer Sicherheitsstandards.
Erste Schritte
- 1Download the Finch app on mobile.
- 2Request API access in Menu > Customer Support and contact our team.
- 3Follow the detailed instructions below to get your API key and start fetching your data!
Kern-Endpunkte
Kontostände
Rufe Echtzeit-Salden für verbundene Banken, Karten und Anlagekonten ab.
Transaktionen
Exportiere oder durchsuche Transaktionsverläufe mit Filtern nach Datum, Konto, Kategorie und Währung.
Sicherheit
Bankenübliche Verschlüsselung, read-only Tokens und bereichsspezifischer Zugriff schützen deine Daten.
Abdeckung
Funktioniert mit Schweizer Banken, internationalen Plattformen wie Revolut und Wise sowie Investment-Tickern.
Get your API key
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).
Zugang benötigt?
Die Finch API ist für ausgewählte Integrationen und Enterprise-Partner verfügbar. Melde dich, um Zugangsdaten und Dokumentation anzufordern.
API-Zugang anfragen