API Integration

This guide covers the public REST flow that exists today for partner developers. It does not document older app modules or unvalidated internal routes.

For new third-party apps, start with the Partner Bookkeeping API. The company-path API is the cleanest flow: connect once to the firm, list companies, then call /companies/{companyId}/....

Setup

Read the OpenAPI contract

https://ledgerhq.pro/api/openapi.json

Connect once with OAuth

Partner apps should use account-level OAuth from a LedgerHQ firm owner/admin. The connected token represents the firm account, not one client file:

GET  /api/oauth/authorize
POST /api/oauth/token

Map client companies

List companies managed by the connected firm, then store the selected company against the partner client record:

GET /api/v1/companies?limit=250&cursor=...
Authorization: Bearer mcp_at_your_token

Resolve accounts

Call /api/v1/companies/{companyId}/accounts and /api/v1/companies/{companyId}/bank-accounts to connect external source accounts to chart accounts and bank accounts.

Preferred Posting Flow

Use resource posting endpoints for normal accounting events:

Resolve the account IDs, contact IDs, tax codes, and bill IDs needed by the source transaction.
Send the transaction to /api/v1/companies/{companyId}/purchases, /deposits, /transfers, /bill-payments, or /journal-entries.
Include an Idempotency-Key generated from the source system transaction ID.
Store the returned journalEntryId and any bankTransactionIds against the source transaction.
Retry safely with the same idempotency key when the network or client process fails before receiving the receipt.

Posting endpoints create posted accounting entries immediately and create bank-register rows when a bank-linked account is involved.

Bank and card activity arrives through Plaid-connected feeds that sync internally on a webhook-driven basis. There is no public "import rows" endpoint; synced rows land as bank transactions with sourceType: "plaid_bank_feed".

List bank accounts with /api/v1/companies/{companyId}/bank-accounts.
List synced rows from /api/v1/companies/{companyId}/bank-transactions.
Reclassify account/contact/tax fields when review changes a category.
Match, split, reconcile, or exclude transactions.
Pull company-path reports such as /api/v1/companies/{companyId}/reports/profit-and-loss.

Reclassify

curl -X POST \
  -H "Authorization: Bearer mcp_at_your_token" \
  -H "x-organization-id: org_id" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "expense_account_id",
    "journalLineId": "journal_line_id",
    "reason": "Account review"
  }' \
  https://ledgerhq.pro/api/v1/bank-transactions/bank_transaction_id/reclassify

Behavior:

Updates the bank transaction classification fields.
Updates the selected editable non-bank journal line when a linked entry exists.
Requires journalLineId for multi-line linked entries.
Rejects period-locked or void entries.

Company Report JSON

curl -H "Authorization: Bearer mcp_at_your_token" \
  "https://ledgerhq.pro/api/v1/companies/company_uuid/reports/profit-and-loss?startDate=2026-01-01&endDate=2026-06-30"

Company-path report routes return JSON with integer-cent amounts. Partner apps can render PDF or HTML reports from that JSON.