Developers — API, webhooks & MCP

Finocket has a developer platform for wiring your own products, scripts and AI tools into your books. Everything lives under Developers: API keys, OAuth clients, webhooks, delivery logs and the interactive API reference. Every call is scoped to your workspace and guarded by row-level security — a key can never read another tenant's data.

API keys and the REST API

Create a key under Developers → API keys and tick exactly the scopes it needs (for example invoices:write without payments:write). The key is shown once, at creation — copy it then. Send it on every request as Authorization: Bearer dmfy_live_….

The versioned REST API at /api/v1 covers your whole business:

• Money — clients (with a per-client ledger), invoices (create, send by email, remind, fetch the PDF, record payments, cancel), payments (including refunds), payment links, subscriptions and usage events.
• Books & inventory — expenses / purchase bills, items & products, live stock levels with weighted-average valuation and a stock ledger, and trial-balance, profit-loss and balance-sheet reports straight from your double-entry books.
• Trade & tenancy — sales and purchase orders, and your companies (list, create, switch).
• Reports & compliance (read) — trial balance, profit & loss, balance sheet, receivables & payables ageing, a client statement of account, the outstanding summary, GSTR-1 / 3B / 2B / 9, cost-centre P&L, budget-vs-actual, financial ratios, the day book, bank-reconciliation suggestions, a Tally XML export and e-way-bill / IRN payloads. These are what let an AI assistant actually answer questions about your books.
• CRM — contacts, deals (move stage, mark won / lost), pipelines, activities, tasks and tags.
• Compliance & partners — consent records (with proof), partner attributions, commission events, partners and merchants.

Writes are idempotent where it matters: clients, invoices and other creates dedupe on your own external_id or an Idempotency-Key header, so a retried request never acts twice.

Running more than one company

If you keep more than one company in Finocket, every API request works inside exactly one of them. List your companies with GET /api/v1/companies, then send X-Company-Id: <company-id> on a request to choose which one — the clients, invoices, expenses and reports you read or create all stay inside that company. Leave the header off and the request uses the company the key is pinned to, or your default company. A company the key can't reach is refused. GET /api/v1/ping always tells you which company you're working in and which ones the key can reach. Building an integration for a single business? Pin the API key to that one company when you create it. If you only run one company, you can ignore all of this — nothing changes.

OAuth clients

If a whole product (not one script) needs access, create an OAuth2 client under Developers → OAuth. It uses the client-credentials grant: exchange the client ID and secret at POST /api/oauth/token with grant_type=client_credentials and you get a short-lived bearer token carrying only the scopes you granted. Revoke a client any time — its tokens stop working.

Webhooks — and verifying the signature

Register an HTTPS endpoint under Developers → Webhooks and pick the events you care about — invoice.created, payment.recorded, expense.created, item.created, company.created, credit_note.created, a stock.low alert when a tracked item hits its reorder level, and more, or all of them. Finocket POSTs a JSON body with the event name, a timestamp and the data. Failed deliveries retry automatically with exponential backoff (up to six attempts), and every attempt shows in Developers → Logs.

Every delivery is signed so you can trust it came from us. To verify:

• Read the X-Demystify-Signature header — it looks like t=<timestamp>,v1=<signature>.
• Recompute HMAC-SHA256(secret, timestamp + "." + rawBody) using the endpoint's secret (shown on the Webhooks page) and the exact raw request body.
• Compare your hex digest to v1 with a constant-time comparison, and reject requests whose timestamp is more than a few minutes old to block replays.

Connect an AI agent over MCP

The same API is exposed as a Model Context Protocol server at /api/mcp, so Claude and other MCP-capable agents can create invoices, send reminders, record payments, work the CRM, record expenses, manage items, read stock and pull financial-statement reports as tools — each tool enforced by the key's scopes and scoped to the company you point it at. In your AI client, add a remote (“streamable HTTP”) MCP server pointing at https://<your-app>/api/mcp with your dmfy_live_… key as the bearer token. Copy-paste setup snippets are on Developers → Docs.

Interactive reference & OpenAPI

Developers → Docs is the guided walkthrough; Developers → API Reference is a live playground — authorize with your key and fire real requests from the browser. The machine-readable OpenAPI spec is served at /api/v1/openapi.json; import it into Postman or Insomnia, or generate a typed client for your language.

Related: Modules & plans, CRM & deals.