Documentation API Finch
(These developer docs are available in English only)
Connectez vos outils à Finch via notre API en lecture seule. Créez des tableaux de bord personnalisés, automatisez des rapports et interrogez soldes, transactions et patrimoine — le tout avec une sécurité de niveau suisse.
Pour commencer
- 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!
Endpoints principaux
Soldes des comptes
Récupérez les soldes en temps réel des banques, cartes et comptes d’investissement connectés.
Transactions
Exportez ou interrogez l’historique des transactions avec des filtres par date, compte, catégorie et devise.
Sécurité
Chiffrement bancaire, tokens en lecture seule et accès limité garantissent la sécurité de vos données.
Couverture
Compatible avec les banques suisses, les plateformes internationales comme Revolut et Wise, ainsi que les tickers boursiers.
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).
Besoin d’un accès ?
L’API Finch est disponible pour des intégrations sélectionnées et des partenaires entreprise. Contactez-nous pour demander vos accès et la documentation.
Demander un accès API