Refresh Reconciliations

post/extensions/roboledger/{graph_id}/operations/refresh-reconciliations

Compare the ledger with its independent sources at a period end and record the result on each reconciliation block. For a ledger synced from QuickBooks this reads QuickBooks' own trial balance and records one comparison for the whole ledger: how many accounts were compared, how many do not tie, and the total difference. The block reconciles for the period when the difference is within its materiality. Running it again replaces the period's comparison, so the answer is always as of the last run. Returns every reconciliation's standing for the period, with the accounts that did not tie. Creates the block the first time it runs. Use preview-reconciliations to see the comparison without recording it.

Idempotency: supply an Idempotency-Key header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.

Authentication

Authenticate in any one of these ways — not all of them:

API key in the X-API-Key header.
Bearer token in the Authorization header.

Path parameters

Name	Type	Description
`graph_id`required	string	Graph Id Constraints: matches `^(kg[a-f0-9]{16,}(?:_[a-zA-Z0-9]{1,20})?\|sec(?:_[a-zA-Z0-9]{1,20})?\|library)$`

Header parameters

Name	Type	Description
`Idempotency-Key`optional	string	Idempotency-Key

Request body

Required, application/json.

Field	Type	Description
`period`required	string	Period to reconcile at its last day, as YYYY-MM.

Example request

curl

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/refresh-reconciliations" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "period": "2026-08"
}'

Responses

200 Successful Response

Field Type Description

operationrequired

string

Kebab-case operation name

operationIdrequired

string

op_-prefixed ULID for audit and SSE correlation

statusrequired

string

Operation lifecycle state

One of: completed, pending, failed

resultoptional

ReconciliationListResponse

Command-specific result payload

ReconciliationListResponse fields

Field Type Description

periodrequired

string

The period, as YYYY-MM.

as_ofrequired

string (date)

The period's last day.

reconciliationsrequired

ReconciliationSummary[]

One entry per reconciliation block, oldest block first.

ReconciliationSummary fields

Field	Type	Description
`structure_id`required	string	The reconciliation block.
`name`required	string	The block's name.
`scope`required	string	`ledger`: the whole ledger against one source. `account`: one account against an independent balance.
`method`required	string	Where the independent side comes from. `source_ledger` is the synced accounting system's own trial balance.
`element_id`optional	string	The account reconciled; null for a ledger-scope block.
`required_for_close`required	boolean	Whether the period's close waits on this reconciliation.
`materiality`required	number	A difference up to this amount still counts as reconciled.
`period`required	string	The period, as YYYY-MM.
`as_of`required	string (date)	The period's last day.
`status`required	string	`not_started`: not compared for this period. `unreconciled`: the sides differ by more than the materiality. `explained`: they differ and items account for all of it. `reconciled`: nothing is left unexplained. `reviewed`: reconciled and signed off.
`unreconciled_difference`optional	number	What is left unexplained at the last comparison; null when the period has not been compared.
`accounts_compared`optional	integer	Ledger-scope only: accounts with a balance on either side.
`accounts_different`optional	integer	Ledger-scope only: accounts that do not tie.
`source`optional	string	The system the independent side was read from.
`compared_at`optional	string (date-time)	When the two sides were last compared.
`fact_set_id`optional	string	The FactSet holding the period's comparison.
`compared_by`optional	string	The user whose action ran the last comparison.
`compared_via`optional	string	`operation` when someone ran refresh-reconciliations; `sync` when a source sync refreshed it.
`review_required`required	boolean	Whether the close also waits for a sign-off.
`separate_reviewer`required	boolean	Whether the reviewer must be someone other than the person who ran the comparison.
`reviewed_by`optional	string	The user who signed off the comparison as it stands. Null when nobody has, or when the balances changed after the sign-off.
`reviewed_at`optional	string (date-time)	When the standing sign-off was made.
`self_reviewed`optional	boolean	True when the reviewer is the person who ran the comparison they signed off. Null when there is no standing sign-off.
`differences`optional	ReconciliationRow[]	Ledger-scope only: the accounts that did not tie at the last comparison, largest difference first.

atrequired

string

ISO-8601 UTC timestamp

createdByoptional

string

User ID that initiated the operation

idempotentReplayoptional

boolean

True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.

Default: false

Status	Meaning
400	Invalid request
401	Authentication required
403	Access denied
404	Resource not found
409	Idempotency-Key conflict — key reused with different body
422	Validation error
429	Rate limit exceeded
500	Internal server error