Skip to main content

Run Books Health Check

POST 

/api/ledger/health-check/run

Start a books health check for a window of at most 24 months, ending no later than the current month. The run reads the provider's month-end trial balances in the background (progress is reported as a tracked job), then grades each section. Only one run happens at a time: if one is already running, it is returned with already_running: true and nothing new starts.

Required scope: accounting:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

A provider error (rate limit, expired connection) stops the run as partial with every month already read kept; resume it with Resume Books Health Check Run. A provider whose base currency differs from the account's stops the run as failed with error.kind = currency_mismatch before any figures are read.

Authentication: Requires Bearer token + accounting.sync permission. Rate limited to 10 requests per minute.

Request body:

  • from (string YYYY-MM, required)
  • to (string YYYY-MM, required)

Errors: 422 with errors.health_check[0].data.reason = not_connected (no run is started) or invalid_window; 422 field errors for a malformed month.

Request​

Responses​

OK

Response Headers
    Content-Type