Documentazione API Finch

Overview

Plans

API access is available on all paid plans (Premium, Premium Europe, Platinum, and referral Premium). On the free plan, the app displays an upgrade prompt. If a plan lapses, an existing key stops working (PAID_PLAN_REQUIRED).

What it reads

Accounts, balances, transactions, and your AI allowance. Every current endpoint is GET; nothing can be modified or written.

Authentication

Include your personal API key in the Authorization header: Authorization: Bearer fnch_sk_live_...

Personal use only

Keys are restricted to the account holder’s personal access. Every response includes: X-Finch-Data-Policy: personal-use-only

Freshness

Reading an account automatically triggers a bank refresh if the data is stale, subject to bank-specific rate limits. See Data Freshness.

Get your API key

API keys are generated solely within the Finch app. There is no web sign-in.

1. 1
   Go to Menu › API keys in the Finch app and switch on API access.
2. 2
   Tap Generate API key.
3. 3
   Name it (up to 60 characters, e.g., “My laptop”).
4. 4
   Select Permissions (at least one):

   • accounts:read — accounts and balances
   • transactions:read — transactions
5. 5
   Choose Expiry: 30, 60, 90 days (90 days maximum).
6. 6
   Confirm Personal Access: the key is strictly for your own use and will not be shared or connected to third-party apps or services.
7. 7
   Copy the key. It is displayed once and copied to your clipboard. Finch stores only a secure hash, so it cannot be displayed again. If misplaced, revoke it and generate a new key.

Management rules

• Key limit: maximum 5 active keys. Generating a 6th fails until an existing key expires or is revoked.
• Immediate revocation: revoke individually or via Revoke all keys. The change takes effect instantly.
• Audit information: the app lists each key’s name, prefix, active permissions, expiration date, last-used timestamp, and last IP address.

Quickstart

curl https://api.fjnch.ch/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"

curl https://api.fjnch.ch/v1/accounts \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://api.fjnch.ch/v1/transactions?accountId=ACCOUNT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

API reference

Object models

Account object

Transaction object

Data freshness

Calling /accounts, /accounts/{id}, or /transactions automatically checks the age of the account data. If it is older than the bank’s refresh window, Finch fetches fresh data before responding.

Requests within the window serve cached data without changing lastSyncedAt. Polling faster will not update your data.

• Shared quota: refresh windows are shared with the mobile app. A script refresh counts toward the app’s rate limits and vice versa.
• Per-call banks: each refresh consumes one monthly plan refresh, just like pull-to-refresh in the app. Once depleted, API reads return stored data until the quota resets.
• Timeout: if a bank does not respond within 25 seconds, the API falls back to stored data.

Data from Swiss banks

Swiss banks, including UBS, ZKB, and PostFinance, enforce strict personal-access restrictions.

• Filtered responses: withheld accounts are omitted from /accounts, return 404 on /accounts/{id} and /transactions?accountId=, and their transactions are excluded. The rest of the response remains unaffected.
• Notifications: you receive a push notification in the Finch app whenever Swiss bank data is filtered from an API call.

Limits and errors

• Rate limit: 120 requests per minute per key (sliding window). Exceeding this returns HTTP 429 with retryAfterSeconds.
• Security lockout: repeated failed requests using invalid or missing keys temporarily block the originating IP address.
• Quota envelope: app limits apply identically to API requests.

Standard error payload

All API errors return a standardized JSON structure:

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "This API key does not have the 'transactions:read' scope.",
  "correlationId": "1792...",
  "timestamp": "2026-10-16T12:00:00.000Z",
  "path": "/v1/transactions"
}

HTTP status codes

What the API will not do

• No write operations: cannot create, update, re-categorize, move, or delete any data.
• No connection management: cannot link or unlink bank connections.
• No multi-user access: cannot access third-party data.
• No webhooks / OpenAPI spec: push notifications and automated spec downloads are not supported.

Security best practices

• Treat keys like passwords: keys use the fnch_sk_live_ prefix. Never commit them to source control, paste them into URLs, or share screenshots containing keys.
• Least privilege: use the shortest expiration period feasible and assign only the required scopes.
• Revoke immediately: if exposure is suspected, revoke the affected key instantly in the Finch app.
• Personal use compliance: do not link API keys directly to third-party services or assistants.

When using the Finch API, the Terms & Conditions and the Privacy Policy apply.

Connecting an AI assistant