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.
accounting:writeGrant 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
- 200
- 401
- 403
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.