How to get a key
- In finiq, open “Settings” → the “API & webhooks” tab and click “Create key”.
- Name the key and choose its access: “Read only” or “Read and write”.
- Copy the key: finiq shows it only once and keeps just its fingerprint.
REST API
Address: https://app.finiq.com.ua/api/v1. Send every request with the header “Authorization: Bearer <key>”.
Amounts are strings of minor units (“125050” is 1,250.50 UAH), dates are YYYY-MM-DD. The transaction list comes in pages: pass nextCursor back as cursor.
What there is: /business, /accounts (with balances), /categories, /counterparties, /projects, /tags, /operations and /planned-operations (list with filters, create, update, delete), /reports/cash-flow, /reports/profit-and-loss, /forecast, /calendar.
Every request and response is described in https://app.finiq.com.ua/api/v1/openapi.json (OpenAPI 3), which Postman, Insomnia or Swagger Editor open.
Limits: 60 requests a minute per key on Pro and 300 on Advanced. Over the limit the API answers 429 with a Retry-After header.
Errors are { code, message }: 401 — no valid key, 402 — the plan has no API or the business is read-only, 403 — the key or its creator may not do this, 404 — not found in this business, 422 — invalid data.
curl https://app.finiq.com.ua/api/v1/operations?from=2026-10-01 \
-H "Authorization: Bearer fiq_…"curl -X POST https://app.finiq.com.ua/api/v1/operations \
-H "Authorization: Bearer fiq_…" \
-H "Content-Type: application/json" \
-d '{"type":"expense","date":"2026-10-31","accountId":"…","amount":"125050",
"description":"Office rent","splits":[{"categoryId":"…","amount":"125050"}]}'Webhooks
In the same tab, click “Add webhook”, give your server’s https address and the events. finiq shows the secret for verifying signatures once.
Events: transactions and planned payments created, changed and deleted — from any source: the app, a bank, an import, the Telegram bot or the API — and budgets reaching 80% and 100%.
The server must answer 2xx within 10 seconds. Otherwise finiq retries after 1, 5 and 30 minutes, 2, 6 and 12 hours and twice after a day; if no event is accepted for three days, the webhook is switched off and the owner is notified.
An event may arrive twice or out of order: keep the event id so as not to process it again, and go by the transaction’s updatedAt.
Verify the signature of every request: the Finiq-Signature header reads t=<time>,v1=<signature>, the signature being an HMAC-SHA256 of “<time>.<request body>” with the webhook’s secret.
{
"id": "0193…",
"type": "operation.created",
"createdAt": "2026-10-31T09:15:02.123Z",
"businessId": "0192…",
"data": { "operation": { "id": "…", "type": "expense", "amount": "125050", … } }
}import { createHmac, timingSafeEqual } from 'node:crypto';
// rawBody: the request body exactly as received, before JSON.parse.
function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(',').map((part) => part.split('=')));
const age = Math.abs(Date.now() / 1000 - Number(parts.t));
if (!parts.t || !parts.v1 || age > 300) return false;
const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
return timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}
// verify(rawBody, request.headers['finiq-signature'], 'whsec_…')MCP for ChatGPT and Claude
MCP server: https://app.finiq.com.ua/api/mcp. The assistant sees balances, transactions, the Cash Flow and P&L reports, the forecast and cash gaps, upcoming payments, and with a write key adds transactions and planned payments.
Claude (claude.ai and Claude Desktop): Settings → Connectors → Add custom connector, address https://app.finiq.com.ua/api/mcp/<key>.
ChatGPT: Settings → Apps & Connectors → Advanced settings → Developer mode, then Create connector with the address https://app.finiq.com.ua/api/mcp/<key> and authentication No authentication.
Claude Code and other clients that can add headers send the key in the Authorization header:
claude mcp add --transport http finiq https://app.finiq.com.ua/api/mcp \
--header "Authorization: Bearer fiq_…"Good to know
- A key acts with the role and access limits of the person who created it: it does not see accounts and projects hidden from them, and changes only what that person may change.
- A key and a webhook stop working as soon as their creator leaves the business. A key can be revoked at any time in the same tab.
- For an AI assistant we recommend a read-only key. The MCP address with the key in it is as secret as the key itself.
- The API, webhooks and MCP come with the Pro and Advanced plans and the trial.
Who can do this. The owner and admins of a business create and revoke keys and webhooks.