Browse the extensions reference

Sign Off Reconciliation

post/extensions/roboledger/{graph_id}/operations/sign-off-reconciliation

Part of RoboLedger: Ledger & Events.

Record your review of a reconciliation for a period. Only a period that reconciles can be signed off, and only by a member of the graph: access that comes from an organization role is not enough. The sign-off records who ran the comparison and who reviewed it, and says so when they are the same person; a reconciliation with separate_reviewer set refuses that case instead. The sign-off stands for the balances as they were compared: if any of them changes afterwards, the period goes back to reconciled or unreconciled and needs signing off again, unless the balances return to the ones already signed. Signing off a period already reviewed changes nothing. Returns the reconciliation's standing for the period.

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

NameTypeDescription
graph_idrequiredstringGraph Id

Constraints: matches ^(kg[a-f0-9]{16,}(?:_[a-zA-Z0-9]{1,20})?|sec(?:_[a-zA-Z0-9]{1,20})?|library)$

Header parameters

NameTypeDescription
Idempotency-KeyoptionalstringIdempotency-Key

Request body

Required, application/json.

FieldTypeDescription
structure_idrequiredstring

The reconciliation block.

periodrequiredstring

The period signed off, as YYYY-MM.

noteoptionalstring

What the reviewer looked at, kept on the sign-off.

Example request

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

Responses

200 Successful Response

FieldTypeDescription
operationrequiredstring

Kebab-case operation name

operationIdrequiredstring

op_-prefixed ULID for audit and SSE correlation

statusrequiredstring

Operation lifecycle state

One of: completed, pending, failed

resultoptionalReconciliationSummary

Command-specific result payload

ReconciliationSummary fields
FieldTypeDescription
structure_idrequiredstring

The reconciliation block.

namerequiredstring

The block's name.

scoperequiredstring

ledger: the whole ledger against one source. account: one account against an independent balance.

methodrequiredstring

Where the independent side comes from. source_ledger is the synced accounting system's own trial balance. schedule_register is what the account's schedules say it carries. statement is the ending balance of a statement recorded for the account.

element_idoptionalstring

The account reconciled; null for a ledger-scope block.

required_for_closerequiredboolean

Whether the period's close waits on this reconciliation.

materialityrequirednumber

A difference up to this amount still counts as reconciled.

statement_cycleoptionalstring

statement blocks only: how often the account's statement is issued, monthly, quarterly or annual.

periodrequiredstring

The period, as YYYY-MM.

as_ofrequiredstring (date)

The period's last day.

statusrequiredstring

not_started: not compared for this period. stale: the books have changed since it was compared, so run refresh-reconciliations. unreconciled: the sides differ by more than the materiality. reconciled: they agree within it. reviewed: reconciled and signed off.

unreconciled_differenceoptionalnumber

What is left unexplained at the last comparison; null when the period has not been compared. For a ledger-scope block, the sum of every account's absolute difference. For an account-scope block, the ledger balance minus the independent one.

accounts_comparedoptionalinteger

Ledger-scope only: accounts with a balance on either side.

accounts_differentoptionalinteger

Ledger-scope only: accounts that do not tie.

ledger_balanceoptionalnumber

Account-scope only: the account's balance at the last comparison, debit-positive, as the period's close will leave it.

independent_balanceoptionalnumber

Account-scope only: what the independent source said at the last comparison, debit-positive.

balance_as_ofoptionalstring (date)

Account-scope only: the date the two balances are stated at. The period's last day, unless the statement covering it ended earlier.

componentsoptionalReconciliationComponent[]

Account-scope only: what makes up the independent balance. One entry per schedule for schedule_register; the recorded statement for statement, then each outstanding line.

ReconciliationComponent fields
FieldTypeDescription
namerequiredstring

The schedule's name, the statement and its date, or the outstanding line's description.

amountrequirednumber

What this part says the account holds, debit-positive.

kindoptionalstring

schedule, statement, outstanding: a ledger line on a bank-fed account that did not come from the feed, dated on or before the statement, so the bank had not cleared it; or stale_outstanding: such a line dated before the statement's cycle, which the bank should have cleared by now. A stale line is listed but not counted toward the balance, so the difference it would explain stays unexplained until it clears, is voided or is re-dated.

posting_dateoptionalstring (date)

An outstanding line's posting date.

entry_idoptionalstring

The journal entry an outstanding line belongs to.

structure_idoptionalstring

The schedule, for a schedule_register part.

event_idoptionalstring

The recorded balance, for a statement part; the event behind an outstanding line, when it has one.

document_idoptionalstring

The statement document given as evidence, when one was.

noteoptionalstring

Why a schedule carries nothing (disposed of, or ended early), or the note recorded with a statement balance.

roll_forwardoptionalReconciliationRollForward

statement on a bank-fed account whose statement ends before the period's last day: the statement carried to it by the feed's lines.

ReconciliationRollForward fields
FieldTypeDescription
statement_as_ofrequiredstring (date)

The statement's ending date.

throughrequiredstring (date)

The period's last day.

bank_linesrequiredinteger

Booked feed lines dated after the statement, to the period end.

bank_activityrequirednumber

Their net effect on the account, debit-positive.

bank_balancerequirednumber

The statement balance carried to the period end by those lines: what the bank held then, debit-positive.

ledger_balancerequirednumber

The ledger's balance at the period end, as the close will leave it, debit-positive.

outstandingrequirednumber

Ledger lines not from the feed and dated on or before the period end, net: the ledger minus the carried bank balance.

feed_balanceoptionalnumber

A cross-check, never the figure reconciled: the bank feed's own balance from the first reading on or after the period end, less the booked feed lines between the period end and that reading. Null when the feed has no reading within ten days.

feed_balance_read_onoptionalstring (date)

The day of the feed reading feed_balance starts from.

sourceoptionalstring

The system the independent side was read from.

compared_atoptionalstring (date-time)

When the two sides were last compared.

fact_set_idoptionalstring

The FactSet holding the period's comparison.

compared_byoptionalstring

The user whose action ran the last comparison.

compared_viaoptionalstring

operation when someone ran refresh-reconciliations; sync when a source sync refreshed it.

review_requiredrequiredboolean

Whether the close also waits for a sign-off.

separate_reviewerrequiredboolean

Whether the reviewer must be someone other than the person who ran the comparison.

reviewed_byoptionalstring

The user who signed off the comparison as it stands. Null when nobody has, or when the balances changed after the sign-off.

reviewed_atoptionalstring (date-time)

When the standing sign-off was made.

self_reviewedoptionalboolean

True when the reviewer is the person who ran the comparison they signed off. Null when there is no standing sign-off.

differencesoptionalReconciliationRow[]

Ledger-scope only: the accounts that did not tie at the last comparison, largest difference first.

ReconciliationRow fields
FieldTypeDescription
element_idoptionalstring

The chart account; null when the ledger has none for it.

account_codeoptionalstring

The chart account's code.

account_namerequiredstring

The account's name in the ledger, else in the source.

source_account_idoptionalstring

The account's id in the source system, when it has one.

statementoptionalstring

balance_sheet or income_statement. Balance-sheet accounts are compared cumulatively to the period end; income-statement accounts from the start of the fiscal year. Null when the ledger has no account.

ledger_balancerequirednumber

What the ledger holds. For source_ledger, landed entries only. For schedule_register, the balance as the period's close will leave it: landed entries, drafts awaiting the close, and schedule entries not yet drafted.

independent_balancerequirednumber

What the independent source says. For a statement on a bank-fed account, the statement balance adjusted by its outstanding lines.

differencerequirednumber

Ledger minus independent.

statusrequiredstring

tied: both sides agree to the cent. different: both know the account and disagree. not_in_ledger: the source reports an account the ledger has none for. not_in_source: the ledger holds a balance on an account the source does not have.

as_ofoptionalstring (date)

The date both balances are stated at, when it is not the period's last day: a statement that ends mid-period is compared with the ledger at the statement's own date.

componentsoptionalReconciliationComponent[]

Account-scope methods only: what makes up the independent balance. One entry per schedule for schedule_register; the recorded statement for statement, then each outstanding line.

roll_forwardoptionalReconciliationRollForward

statement on a bank-fed account whose statement ends before the period's last day: the statement carried to it by the feed's lines.

atrequiredstring

ISO-8601 UTC timestamp

createdByoptionalstring

User ID that initiated the operation

idempotentReplayoptionalboolean

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

Default: false

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