---
title: "Record Statement Balance"
method: POST
path: "/extensions/roboledger/{graph_id}/operations/record-statement-balance"
tags: ["RoboLedger: Ledger & Events"]
---

# Record Statement Balance

`POST /extensions/roboledger/{graph_id}/operations/record-statement-balance`

## Request

- Base URL: `https://api.robosystems.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/record-statement-balance`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

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. On an account a bank feed keeps, ledger lines that did not come from the feed and are dated on or before the statement are listed as outstanding and adjust the statement balance, since the bank had not cleared them; a statement ending before the period's last day is carried to it by the feed's own lines (`roll_forward`). Attach the statement as evidence by passing the `document_id` of its stored file (create-document-upload, then complete-document-upload); recording it again with another document lapses a sign-off. 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 left after the outstanding lines 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.

## Path parameters

- `graph_id` string, required

## Headers

- `Idempotency-Key` string, nullable

## Request body

- RecordStatementBalanceRequest: Record the ending balance of a statement for one account.
  - `element_id` string, required: The balance-sheet account the statement is for (a chart-of-accounts element id).
  - `entity_id` string, nullable: The entity whose books the account is in, by id. Omit for the group parent. The account must be in that entity's chart.
  - `as_of` string, date, required: The statement's ending date.
  - `balance` number, required: 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.
  - `document_id` string, nullable: The statement itself, as a document already added with create-document. Kept on the record as evidence.
  - `note` string, nullable: Anything worth keeping with the recorded balance.

## Response `200`

Successful Response

- OperationEnvelopeReconciliationSummary
  - `operation` string, required: Kebab-case operation name
  - `operationId` string, required: op_-prefixed ULID for audit and SSE correlation
  - `status` 'completed' | 'pending' | 'failed', required: Operation lifecycle state
  - `result` ReconciliationSummary: One reconciliation's standing for a period.
    - `structure_id` string, required: The reconciliation block.
    - `name` string, required: The block's name.
    - `scope` string, required: `ledger`: the whole ledger against one source. `account`: one account against an independent balance.
    - `method` string, required: 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_id` string, nullable: The account reconciled; null for a ledger-scope block.
    - `required_for_close` boolean, required: Whether the period's close waits on this reconciliation.
    - `materiality` number, required: A difference up to this amount still counts as reconciled.
    - `statement_cycle` string, nullable: `statement` blocks only: how often the account's statement is issued, `monthly`, `quarterly` or `annual`.
    - `period` string, required: The period, as YYYY-MM.
    - `as_of` string, date, required: The period's last day.
    - `status` string, required: `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_difference` number, nullable: 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_compared` integer, nullable: Ledger-scope only: accounts with a balance on either side.
    - `accounts_different` integer, nullable: Ledger-scope only: accounts that do not tie.
    - `ledger_balance` number, nullable: Account-scope only: the account's balance at the last comparison, debit-positive, as the period's close will leave it.
    - `independent_balance` number, nullable: Account-scope only: what the independent source said at the last comparison, debit-positive.
    - `balance_as_of` string, date, nullable: Account-scope only: the date the two balances are stated at. The period's last day, unless the statement covering it ended earlier.
    - `components` ReconciliationComponent[]: 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.
      - `name` string, required: The schedule's name, the statement and its date, or the outstanding line's description.
      - `amount` number, required: What this part says the account holds, debit-positive.
      - `kind` string, nullable: `schedule`, `statement`, or `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.
      - `posting_date` string, date, nullable: An `outstanding` line's posting date.
      - `entry_id` string, nullable: The journal entry an `outstanding` line belongs to.
      - `structure_id` string, nullable: The schedule, for a `schedule_register` part.
      - `event_id` string, nullable: The recorded balance, for a `statement` part; the event behind an `outstanding` line, when it has one.
      - `document_id` string, nullable: The statement document given as evidence, when one was.
      - `note` string, nullable: Why a schedule carries nothing (disposed of, or ended early), or the note recorded with a statement balance.
    - `roll_forward` ReconciliationRollForward: A statement carried from its ending date to the period's last day on a bank-fed account, where every line the feed brought is the bank's own.
      - `statement_as_of` string, date, required: The statement's ending date.
      - `through` string, date, required: The period's last day.
      - `bank_lines` integer, required: Booked feed lines dated after the statement, to the period end.
      - `bank_activity` number, required: Their net effect on the account, debit-positive.
      - `bank_balance` number, required: The statement balance carried to the period end by those lines: what the bank held then, debit-positive.
      - `ledger_balance` number, required: The ledger's balance at the period end, as the close will leave it, debit-positive.
      - `outstanding` number, required: Ledger lines not from the feed and dated on or before the period end, net: the ledger minus the carried bank balance.
      - `feed_balance` number, nullable: 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_on` string, date, nullable: The day of the feed reading `feed_balance` starts from.
    - `source` string, nullable: The system the independent side was read from.
    - `compared_at` string, date-time, nullable: When the two sides were last compared.
    - `fact_set_id` string, nullable: The FactSet holding the period's comparison.
    - `compared_by` string, nullable: The user whose action ran the last comparison.
    - `compared_via` string, nullable: `operation` when someone ran refresh-reconciliations; `sync` when a source sync refreshed it.
    - `review_required` boolean, required: Whether the close also waits for a sign-off.
    - `separate_reviewer` boolean, required: Whether the reviewer must be someone other than the person who ran the comparison.
    - `reviewed_by` string, nullable: 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` string, date-time, nullable: When the standing sign-off was made.
    - `self_reviewed` boolean, nullable: True when the reviewer is the person who ran the comparison they signed off. Null when there is no standing sign-off.
    - `differences` ReconciliationRow[]: Ledger-scope only: the accounts that did not tie at the last comparison, largest difference first.
      - `element_id` string, nullable: The chart account; null when the ledger has none for it.
      - `account_code` string, nullable: The chart account's code.
      - `account_name` string, required: The account's name in the ledger, else in the source.
      - `source_account_id` string, nullable: The account's id in the source system, when it has one.
      - `statement` string, nullable: `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` number, required: 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` number, required: What the independent source says. For a `statement` on a bank-fed account, the statement balance adjusted by its outstanding lines.
      - `difference` number, required: Ledger minus independent.
      - `status` string, required: `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` string, date, nullable: 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` ReconciliationComponent[]: 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.
        - `name` string, required: The schedule's name, the statement and its date, or the outstanding line's description.
        - `amount` number, required: What this part says the account holds, debit-positive.
        - `kind` string, nullable: `schedule`, `statement`, or `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.
        - `posting_date` string, date, nullable: An `outstanding` line's posting date.
        - `entry_id` string, nullable: The journal entry an `outstanding` line belongs to.
        - `structure_id` string, nullable: The schedule, for a `schedule_register` part.
        - `event_id` string, nullable: The recorded balance, for a `statement` part; the event behind an `outstanding` line, when it has one.
        - `document_id` string, nullable: The statement document given as evidence, when one was.
        - `note` string, nullable: Why a schedule carries nothing (disposed of, or ended early), or the note recorded with a statement balance.
      - `roll_forward` ReconciliationRollForward: A statement carried from its ending date to the period's last day on a bank-fed account, where every line the feed brought is the bank's own.
        - `statement_as_of` string, date, required: The statement's ending date.
        - `through` string, date, required: The period's last day.
        - `bank_lines` integer, required: Booked feed lines dated after the statement, to the period end.
        - `bank_activity` number, required: Their net effect on the account, debit-positive.
        - `bank_balance` number, required: The statement balance carried to the period end by those lines: what the bank held then, debit-positive.
        - `ledger_balance` number, required: The ledger's balance at the period end, as the close will leave it, debit-positive.
        - `outstanding` number, required: Ledger lines not from the feed and dated on or before the period end, net: the ledger minus the carried bank balance.
        - `feed_balance` number, nullable: 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_on` string, date, nullable: The day of the feed reading `feed_balance` starts from.
  - `at` string, required: ISO-8601 UTC timestamp
  - `createdBy` string, nullable: User ID that initiated the operation
  - `idempotentReplay` boolean: True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.

## Other responses

- `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

---

[API](https://skmtc.dev/robosystems/apis/robosystems-api.md) · [All operations](https://skmtc.dev/robosystems/apis/robosystems-api/llms.txt) · [OpenAPI document](https://skmtc.dev/robosystems/apis/robosystems-api/revisions/28ffd375c457?raw)