Sync health

9 operations in the Tolvi API, version 1. Paths are relative to https://api.tolvi.co.uk. Every amount is integer pence.

Sync health overview

GET/api/v1/sync

Scopes: work:read

Counts by sync state (open engagements, plus completed ones the sign-off check still covers), the last and any running sign-off check, the schedule and rules, and counts by software. Part of the working_papers product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (SyncOverview).

200 OK response for GET /api/v1/sync
Field	Type	Description
`counts`required	`object (SyncCounts)`
`counts.connected`required	`integer`	Engagements on bookkeeping software (open, plus completed ones still checked). at least 0
`counts.manual`required	`integer`	at least 0
`counts.inSync`required	`integer`	at least 0
`counts.changed`required	`integer`	Open engagements whose figures changed since sign-off (the Work queue’s Changed view). at least 0
`counts.changedCompleted`required	`integer`	Completed engagements whose figures changed. at least 0
`counts.expired`required	`integer`	at least 0
`counts.error`required	`integer`	at least 0
`counts.neverSynced`required	`integer`	at least 0
`counts.manualOpen`required	`integer`	Open engagements on manual upload: not checkable. at least 0
`counts.resolvedToday`required	`integer`	Accepted, acknowledged or recorded as post-filing today (firm time zone). at least 0
`lastRun`required	`object (SyncCheckRun)`nullable	The last run that finished.
`lastRun.id`required	`string (uuid)`
`lastRun.trigger`required	`string (SyncCheckTrigger)`	schedule: the nightly or weekly run; manual: Run check now. One of: `schedule`, `manual`
`lastRun.startedAt`required	`string (date-time)`
`lastRun.finishedAt`required	`string (date-time)`nullable	Null while engagements are still being checked.
`lastRun.windowStart`required	`string (date-time)`	Checks start from here; a scheduled run spreads them over windowMinutes.
`lastRun.windowMinutes`required	`integer`	at least 0
`lastRun.total`required	`integer`	Engagements in scope. at least 0
`lastRun.checked`required	`integer`	Engagements checked so far. at least 0
`lastRun.changed`required	`integer`	at least 0
`lastRun.failed`required	`integer`	Expired connections and errors. at least 0
`lastRun.durationMinutes`required	`integer`nullable	From start to finish. at least 0
`lastRun.requestedBy`required	`string (uuid)`nullable
`running`required	`object (SyncCheckRun)`nullable	A run still checking engagements.
`running.id`required	`string (uuid)`
`running.trigger`required	`string (SyncCheckTrigger)`	schedule: the nightly or weekly run; manual: Run check now. One of: `schedule`, `manual`
`running.startedAt`required	`string (date-time)`
`running.finishedAt`required	`string (date-time)`nullable	Null while engagements are still being checked.
`running.windowStart`required	`string (date-time)`	Checks start from here; a scheduled run spreads them over windowMinutes.
`running.windowMinutes`required	`integer`	at least 0
`running.total`required	`integer`	Engagements in scope. at least 0
`running.checked`required	`integer`	Engagements checked so far. at least 0
`running.changed`required	`integer`	at least 0
`running.failed`required	`integer`	Expired connections and errors. at least 0
`running.durationMinutes`required	`integer`nullable	From start to finish. at least 0
`running.requestedBy`required	`string (uuid)`nullable
`schedule`required	`object (SyncSchedule)`
`schedule.frequency`required	`string (SyncFrequency)`	One of: `nightly`, `weekly`
`schedule.time`required	`string`	example "02:00"
`schedule.timeZone`required	`string`	example "Europe/London"
`schedule.ignoreUnderPence`required	`integer`	Integer pence (GBP). Movements smaller than this are ignored (firm default; a client can override it). at least 0
`schedule.comparePriorYear`required	`boolean`
`schedule.onChange`required	`string (SyncOnChange)`	One of: `notify`, `reopen`, `none`
`schedule.digest`required	`string (SyncDigest)`	One of: `daily`, `instant`, `off`
`bySoftware`required	`array of SyncSoftwareRow`
`bySoftware[].software`required	`string (Software)`	One of: `xero`, `qbo`, `sage`, `freeagent`, `tolvi_books`, `manual`
`bySoftware[].engagements`required	`integer`	at least 0
`bySoftware[].inSync`required	`integer`	at least 0
`bySoftware[].changed`required	`integer`	at least 0
`bySoftware[].fix`required	`integer`	Expired, error or never synced. at least 0

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

List engagements for Sync health

GET/api/v1/sync/engagements

Scopes: work:read

Earliest deadline first, each with its latest sign-off check result. Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/sync/engagements
Name	In	Type	Description
`limit`	query	`integer`	1 to 500; default 100
`includeCompleted`	query	`string`	changed only: include completed engagements. One of: `true`, `false`
`list`	query	`string`	changed (default), fix (reconnect or fix), manual (open manual uploads), resolved (today). One of: `changed`, `fix`, `manual`, `resolved`

Responses

200 OK, `application/json`

Body: object (SyncRowPage).

200 OK response for GET /api/v1/sync/engagements
Field	Type	Description
`list`required	`string (SyncList)`	One of: `changed`, `fix`, `manual`, `resolved`
`rows`required	`array of SyncRow`	Earliest deadline first; at most `limit`.
`rows[].engagementId`required	`string (uuid)`
`rows[].clientId`required	`string (uuid)`
`rows[].clientName`required	`string`
`rows[].entityType`required	`string (EntityType)`	One of: `LTD_FRS102_1A`, `LTD_FRS105_MICRO`, `LLP`, `SOLE_TRADER`, `INDIVIDUAL`, `PARTNERSHIP`, `TRUST`, `ESTATE`, `CHARITY_UNINCORPORATED`, `CHARITY_TRUST`, `CIO`, `SCIO`, `CHARITABLE_COMPANY`
`rows[].periodEnd`required	`string (date)`	example "2026-03-31"
`rows[].dueDate`required	`string (date)`	example "2026-03-31"
`rows[].status`required	`string (EngagementStatus)`	One of: `not_started`, `in_progress`, `submitted`, `returned`, `complete`
`rows[].software`required	`string (Software)`	One of: `xero`, `qbo`, `sage`, `freeagent`, `tolvi_books`, `manual`
`rows[].syncState`required	`string (SyncState)`	One of: `in_sync`, `changed`, `expired_token`, `error`, `never_synced`, `manual`
`rows[].lastSyncedAt`required	`string (date-time)`nullable
`rows[].result`required	`object (SyncResultSummary)`nullable	The latest sign-off check result.
`rows[].result.id`required	`string (uuid)`
`rows[].result.status`required	`string (SyncCheckStatus)`	One of: `running`, `in_sync`, `changed`, `acknowledged`, `expired_token`, `error`
`rows[].result.checkedAt`required	`string (date-time)`
`rows[].result.signedOffAt`required	`string (date-time)`nullable
`rows[].result.accountCount`required	`integer`	Accounts that moved. at least 0
`rows[].result.grossPence`required	`integer`	Integer pence (GBP). Sum of the absolute current year movements. at least 0
`rows[].result.affectedSections`required	`array of string`	Affected lead sections (W/P refs).
`rows[].result.resolution`required	`string (SyncResolution)`nullable	One of: `accepted`, `acknowledged`, `post_filing`
`rows[].result.resolvedAt`required	`string (date-time)`nullable
`rows[].result.outcome`required	`string`nullable	The outcome in words (who resolved it and how).
`rows[].result.message`required	`string`nullable	Why the check could not run, in words.
`total`required	`integer`	at least 0

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Run the sign-off check now

POST/api/v1/sync/runs

Scopes: engagements:write
Retries: Send an Idempotency-Key to make retries safe.

Starts a check of every connected engagement with a sign-off (or only engagementIds). The books are read in the background; poll GET /sync/runs/{id}. A run already in progress is returned instead of starting another. Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/sync/runs
Name	In	Type	Description
`Idempotency-Key`	header	`string`	A unique key (1-255 visible characters) to make retries safe. Replayed for 24 hours. 1 to 255 characters

Request body

Optional. application/json: object (StartSyncCheckRequest).

Request body for POST /api/v1/sync/runs
Field	Type	Description
`engagementIds`	`array of string`	Only these engagements (Work queue bulk action); default every engagement in scope. up to 500 items

Responses

202 Accepted, `application/json`

Body: object (SyncCheckRun).

202 Accepted response for POST /api/v1/sync/runs
Field	Type	Description
`id`required	`string (uuid)`
`trigger`required	`string (SyncCheckTrigger)`	schedule: the nightly or weekly run; manual: Run check now. One of: `schedule`, `manual`
`startedAt`required	`string (date-time)`
`finishedAt`required	`string (date-time)`nullable	Null while engagements are still being checked.
`windowStart`required	`string (date-time)`	Checks start from here; a scheduled run spreads them over windowMinutes.
`windowMinutes`required	`integer`	at least 0
`total`required	`integer`	Engagements in scope. at least 0
`checked`required	`integer`	Engagements checked so far. at least 0
`changed`required	`integer`	at least 0
`failed`required	`integer`	Expired connections and errors. at least 0
`durationMinutes`required	`integer`nullable	From start to finish. at least 0
`requestedBy`required	`string (uuid)`nullable

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 409 Conflict, 422 Unprocessable content, 429 Too many requests, as problem details (application/problem+json).

Remind people to reconnect bookkeeping

POST/api/v1/sync/reminders

Scopes: engagements:write
Retries: Send an Idempotency-Key to make retries safe.

For engagements whose connection has expired, failed or never synced: tells the preparer (else the manager, else the partner) which clients need reconnecting, in the app and by email unless they have turned those emails off. One reminder per person. You are never reminded yourself. Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/sync/reminders
Name	In	Type	Description
`Idempotency-Key`	header	`string`	A unique key (1-255 visible characters) to make retries safe. Replayed for 24 hours. 1 to 255 characters

Request body

Required. application/json: object (SyncRemindersRequest).

Request body for POST /api/v1/sync/reminders
Field	Type	Description
`engagementIds`required	`array of string`	Engagements whose bookkeeping connection needs reconnecting or fixing (Sync health’s Reconnect or fix list). 1 to 500 items

Responses

200 OK, `application/json`

Body: object (SyncReminders).

Who was reminded.

200 OK response for POST /api/v1/sync/reminders
Field	Type	Description
`notified`required	`integer`	People sent a reminder (one each, listing their clients). at least 0
`engagements`required	`integer`	Engagements covered by a reminder. at least 0
`skipped`required	`integer`	Engagements left out: not broken, on manual upload, or with nobody to remind but you. at least 0

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 409 Conflict, 422 Unprocessable content, 429 Too many requests, as problem details (application/problem+json).

Get a sign-off check run

GET/api/v1/sync/runs/{id}

Scopes: work:read

Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/sync/runs/{id}
Name	In	Type	Description
`id`required	path	`string (uuid)`	Run id.

Responses

200 OK, `application/json`

Body: object (SyncCheckRun).

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Get an engagement’s sign-off check

GET/api/v1/engagements/{id}/sync-check

Scopes: engagements:read

The latest result: account-by-account differences from the signed-off trial balance, the transactions behind them and the affected sections, with the engagement’s earlier resolutions. Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/engagements/{id}/sync-check
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.

Responses

200 OK, `application/json`

Body: object (SyncCheckDetail).

200 OK response for GET /api/v1/engagements/{id}/sync-check
Field	Type	Description
`engagementId`required	`string (uuid)`
`clientName`required	`string`
`periodEnd`required	`string (date)`	example "2026-03-31"
`status`required	`string (EngagementStatus)`	One of: `not_started`, `in_progress`, `submitted`, `returned`, `complete`
`filedOn`required	`string (date)`nullable	When the accounts were filed; a change after that is a post-filing change. example "2026-03-31"
`software`required	`string (Software)`	One of: `xero`, `qbo`, `sage`, `freeagent`, `tolvi_books`, `manual`
`syncState`required	`string (SyncState)`	One of: `in_sync`, `changed`, `expired_token`, `error`, `never_synced`, `manual`
`latest`required	`object (SyncCheckResult)`nullable	The latest result; null if never checked.
`latest.id`required	`string (uuid)`
`latest.status`required	`string (SyncCheckStatus)`	One of: `running`, `in_sync`, `changed`, `acknowledged`, `expired_token`, `error`
`latest.checkedAt`required	`string (date-time)`
`latest.signedOffAt`required	`string (date-time)`nullable
`latest.accountCount`required	`integer`	Accounts that moved. at least 0
`latest.grossPence`required	`integer`	Integer pence (GBP). Sum of the absolute current year movements. at least 0
`latest.affectedSections`required	`array of string`	Affected lead sections (W/P refs).
`latest.resolution`required	`string (SyncResolution)`nullable	One of: `accepted`, `acknowledged`, `post_filing`
`latest.resolvedAt`required	`string (date-time)`nullable
`latest.outcome`required	`string`nullable	The outcome in words (who resolved it and how).
`latest.message`required	`string`nullable	Why the check could not run, in words.
`latest.runId`required	`string (uuid)`
`latest.provider`required	`string (IntegrationProvider)`nullable	The OAuth provider read; null for Tolvi Books (see source). One of: `xero`, `quickbooks`, `sage`, `freeagent`
`latest.source`required	`string (BooksSource)`nullable	Where the books were read: an OAuth provider, or tolvi_books (the client’s Tolvi Books, through the firm’s practice link). One of: `xero`, `quickbooks`, `sage`, `freeagent`, `tolvi_books`
`latest.sourceLabel`required	`string`nullable	example "Tolvi Books"
`latest.tbVersionId`required	`string (uuid)`nullable	The trial balance version compared against.
`latest.tbVersion`required	`integer`nullable
`latest.asAt`required	`string (date)`nullable	example "2026-03-31"
`latest.priorAsAt`required	`string (date)`nullable	example "2026-03-31"
`latest.accounts`required	`array of SyncDiffAccount`
`latest.accounts[].code`required	`string`
`latest.accounts[].name`required	`string`
`latest.accounts[].status`required	`string (SyncDiffStatus)`	One of: `changed`, `added`, `removed`
`latest.accounts[].signedOff`required	`object (SyncBalances)`nullable	In the trial balance that was signed off.
`latest.accounts[].signedOff.cyPence`required	`integer`	Integer pence (GBP).
`latest.accounts[].signedOff.pyPence`required	`integer`	Integer pence (GBP).
`latest.accounts[].now`required	`object (SyncBalances)`nullable	In the bookkeeping software now.
`latest.accounts[].now.cyPence`required	`integer`	Integer pence (GBP).
`latest.accounts[].now.pyPence`required	`integer`	Integer pence (GBP).
`latest.accounts[].cyDiffPence`required	`integer`	Integer pence (GBP).
`latest.accounts[].pyDiffPence`required	`integer`	Integer pence (GBP).
`latest.accounts[].sections`required	`array of string`
`latest.accounts[].transactions`required	`array of SyncTransaction`	Postings behind the movement, when the software lists them.
`latest.accounts[].transactions[].id`required	`string`	The provider’s id for the source document or journal.
`latest.accounts[].transactions[].accountCode`required	`string`
`latest.accounts[].transactions[].date`required	`string (date)`	example "2026-03-31"
`latest.accounts[].transactions[].description`required	`string`
`latest.accounts[].transactions[].amountPence`required	`integer`	Integer pence (GBP). Debit positive.
`latest.accounts[].transactions[].updatedAt`required	`string (date-time)`nullable	When it was entered or last changed in the software.
`latest.accounts[].transactions[].sourceType`required	`string`nullable
`latest.accounts[].transactions[].postedBy`required	`string`nullable	Who entered it, when the software says (Tolvi Books does). example "Jo Owner (the business)"
`latest.accounts[].transactions[].explanation`required	`string`	example "Credit note CN-0192 (Kestrel Homes), dated 28 Mar 2026, entered 14 Oct 2026"
`latest.accounts[].unexplainedPence`required	`integer`	Integer pence (GBP). The movement the transactions do not account for.
`latest.transactionsAvailable`required	`boolean`	The software could list the transactions behind the movements. From Tolvi Books they are exactly the ledger entries posted after the signed-off trial balance’s ledger point, each with who posted it.
`latest.reason`required	`string`nullable
`latest.note`required	`string`nullable
`latest.resolvedBy`required	`string (uuid)`nullable
`latest.resolvedTbVersionId`required	`string (uuid)`nullable	Accept and re-sync: the trial balance version created.
`history`required	`array of SyncResultSummary`	Earlier resolved results, newest first (the engagement’s sync history).
`history[].id`required	`string (uuid)`
`history[].status`required	`string (SyncCheckStatus)`	One of: `running`, `in_sync`, `changed`, `acknowledged`, `expired_token`, `error`
`history[].checkedAt`required	`string (date-time)`
`history[].signedOffAt`required	`string (date-time)`nullable
`history[].accountCount`required	`integer`	Accounts that moved. at least 0
`history[].grossPence`required	`integer`	Integer pence (GBP). Sum of the absolute current year movements. at least 0
`history[].affectedSections`required	`array of string`	Affected lead sections (W/P refs).
`history[].resolution`required	`string (SyncResolution)`nullable	One of: `accepted`, `acknowledged`, `post_filing`
`history[].resolvedAt`required	`string (date-time)`nullable
`history[].outcome`required	`string`nullable	The outcome in words (who resolved it and how).
`history[].message`required	`string`nullable	Why the check could not run, in words.
`canResolve`required	`boolean`	Accept and re-sync, Acknowledge or Record as post-filing change can be used now.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Accept and re-sync

POST/api/v1/engagements/{id}/sync-check/accept

Scopes: engagements:write
Retries: Send an Idempotency-Key to make retries safe.

Pulls the books again into a new immutable trial balance version and reopens the affected sections; their sign-offs go stale through the content fingerprint (a new amendment round). 409 if there is no open change, or if journals would be removed without confirmJournalRemoval. Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/engagements/{id}/sync-check/accept
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.
`Idempotency-Key`	header	`string`	A unique key (1-255 visible characters) to make retries safe. Replayed for 24 hours. 1 to 255 characters

Request body

Optional. application/json: object (AcceptSyncChangeRequest).

Request body for POST /api/v1/engagements/{id}/sync-check/accept
Field	Type	Description
`confirmJournalRemoval`	`boolean`	Confirm removing journals on accounts no longer in the books (409 lists them otherwise).

Responses

200 OK, `application/json`

Body: object (SyncCheckDetail).

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 409 Conflict, 422 Unprocessable content, 429 Too many requests, as problem details (application/problem+json).

Acknowledge a change without re-syncing

POST/api/v1/engagements/{id}/sync-check/acknowledge

Scopes: review:write

Records why no action is needed (a note is required for “Other”). The same differences are not raised again by later checks. Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/engagements/{id}/sync-check/acknowledge
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.

Request body

Required. application/json: object (AcknowledgeSyncChangeRequest).

Request body for POST /api/v1/engagements/{id}/sync-check/acknowledge
Field	Type	Description
`reason`required	`string`	1 to 200 characters; example "Posted in error by client; they will reverse it"
`note`	`string`	Required when the reason is “Other”. Shown in the sync history. up to 2000 characters

Responses

200 OK, `application/json`

Body: object (SyncCheckDetail).

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Record a post-filing change

POST/api/v1/engagements/{id}/sync-check/post-filing

Scopes: review:write

For a completed engagement: records the change as a post-filing change (tell the client; consider amended accounts or next year’s opening balances). The same differences are not raised again. Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/engagements/{id}/sync-check/post-filing
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.

Request body

Optional. application/json: object (PostFilingChangeRequest).

Request body for POST /api/v1/engagements/{id}/sync-check/post-filing
Field	Type	Description
`note`	`string`	up to 2000 characters

Responses

200 OK, `application/json`

Body: object (SyncCheckDetail).

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Sync health

Sync health overview

Responses

200 OK, application/json

List engagements for Sync health

Parameters

Responses

200 OK, application/json

Run the sign-off check now

Parameters

Request body

Responses

202 Accepted, application/json

Remind people to reconnect bookkeeping

Parameters

Request body

Responses

200 OK, application/json

Get a sign-off check run

Parameters

Responses

200 OK, application/json

Get an engagement’s sign-off check

Parameters

Responses

200 OK, application/json

Accept and re-sync

Parameters

Request body

Responses

200 OK, application/json

Acknowledge a change without re-syncing

Parameters

Request body

Responses

200 OK, application/json

Record a post-filing change

Parameters

Request body

Responses

200 OK, application/json

200 OK, `application/json`

200 OK, `application/json`

202 Accepted, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`