Record Statement Balance

post/extensions/roboledger/{graph_id}/operations/record-statement-balance

Record the ending balance of a statement (a bank, card or loan statement) for one balance-sheet account, and reconcile the account to it. Give the balance as the statement shows it, as a positive number in the account's normal direction, with the statement's ending date. The ledger's balance at that date is set beside it, counting the drafts the close will post, and the result is recorded on the account's statement reconciliation for the period the statement ends in. Attach the statement as evidence by passing the document_id of a document added with create-document. Writes no books. The first statement recorded for an account creates its reconciliation, which does not hold the close: turn required_for_close on with set-reconciliation-policy to make every period's close wait for a statement on that account. Recording the same account and date again replaces the earlier balance; when more than one statement ends in a period, the one with the latest date stands. Recording a balance that differs from one already signed off lapses that sign-off. A difference is not explained here: it is activity one side has and the other does not yet, or an error on either. 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

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
`element_id`required	string	The balance-sheet account the statement is for (a chart-of-accounts element id).
`as_of`required	string (date)	The statement's ending date.
`balance`required	number	The ending balance as the statement shows it, as a positive number in the account's normal direction: money in a bank account, or the amount owed on a loan or a card. Negative for the opposite, such as an overdrawn bank account. Constraints: -10000000000000–10000000000000
`document_id`optional	string	The statement itself, as a document already added with create-document. Kept on the record as evidence.
`note`optional	string	Anything worth keeping with the recorded balance.

Example request

curl

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/record-statement-balance" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "element_id": "string",
  "as_of": "2026-08-31",
  "balance": 18250.75
}'

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

ReconciliationSummary

Command-specific result payload

ReconciliationSummary fields

Field Type Description

structure_idrequired

string

The reconciliation block.

namerequired

string

The block's name.

scoperequired

string

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

methodrequired

string

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_idoptional

string

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

required_for_closerequired

boolean

Whether the period's close waits on this reconciliation.

materialityrequired

number

A difference up to this amount still counts as reconciled.

periodrequired

string

The period, as YYYY-MM.

as_ofrequired

string (date)

The period's last day.

statusrequired

string

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_differenceoptional

number

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_comparedoptional

integer

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

accounts_differentoptional

integer

Ledger-scope only: accounts that do not tie.

ledger_balanceoptional

number

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

independent_balanceoptional

number

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

balance_as_ofoptional

string (date)

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

componentsoptional

ReconciliationComponent[]

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

ReconciliationComponent fields

Field	Type	Description
`name`required	string	The schedule's name, or the statement and its date.
`amount`required	number	What this part says the account holds, debit-positive.
`structure_id`optional	string	The schedule, for a `schedule_register` part.
`event_id`optional	string	The recorded balance, for a `statement` part.
`document_id`optional	string	The statement document given as evidence, when one was.
`note`optional	string	Why a schedule carries nothing (disposed of, or ended early), or the note recorded with a statement balance.

sourceoptional

string

The system the independent side was read from.

compared_atoptional

string (date-time)

When the two sides were last compared.

fact_set_idoptional

string

The FactSet holding the period's comparison.

compared_byoptional

string

The user whose action ran the last comparison.

compared_viaoptional

string

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

review_requiredrequired

boolean

Whether the close also waits for a sign-off.

separate_reviewerrequired

boolean

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

reviewed_byoptional

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_atoptional

string (date-time)

When the standing sign-off was made.

self_reviewedoptional

boolean

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

differencesoptional

ReconciliationRow[]

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

ReconciliationRow fields

Field	Type	Description
`element_id`optional	string	The chart account; null when the ledger has none for it.
`account_code`optional	string	The chart account's code.
`account_name`required	string	The account's name in the ledger, else in the source.
`source_account_id`optional	string	The account's id in the source system, when it has one.
`statement`optional	string	`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_balance`required	number	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_balance`required	number	What the independent source says.
`difference`required	number	Ledger minus independent.
`status`required	string	`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_of`optional	string (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.
`components`optional	ReconciliationComponent[]	Account-scope methods only: what makes up the independent balance. One entry per schedule for `schedule_register`; the recorded statement for `statement`.

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