---
title: "Preview Reconciliations"
method: POST
path: "/extensions/roboledger/{graph_id}/operations/preview-reconciliations"
tags: ["RoboLedger: Ledger & Events"]
---

# Preview Reconciliations

`POST /extensions/roboledger/{graph_id}/operations/preview-reconciliations`

## 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/preview-reconciliations`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Compare the ledger at a period end with something outside it, without recording anything. `method` picks the check. `source_ledger` (the default) reads QuickBooks' own trial balance for the period end and sets it beside the ledger's, account by account: balance-sheet accounts cumulatively, income and expense accounts from the start of the fiscal year. A difference there means the ledger's copy of the books has drifted from the source (a transaction deleted or back-dated there after it was synced, or activity not yet synced), so run it before trusting any other figure on a synced ledger; it needs a connected QuickBooks ledger. `schedule_register` compares each asset account a schedule carries a balance on (a prepaid, accumulated depreciation, a fixed-asset cost account) with what its schedules say it holds, and lists the schedules behind each figure. A difference there is a balance with no schedule behind it, or a scheduled amount the ledger does not hold. Each row carries both balances, the difference, and whether the account ties.

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

- PreviewReconciliationsRequest: Compare the ledger's balances at a period end with an independent source.
  - `period` string, required: Period to compare at its last day, as YYYY-MM.
  - `method` 'source_ledger' | 'schedule_register' | 'statement': Which check to preview. `source_ledger` compares every account with the synced accounting system's own trial balance. `schedule_register` compares each asset account a schedule carries a balance on with what its schedules say it holds. `statement` compares each account that has a statement covering the period with that balance, adjusted on a bank-fed account by the lines the bank had not cleared.
  - `include_tied` boolean: Also return the accounts that tie. Off by default: the differences are the work, and the counts cover the rest.
  - `entity_id` string, nullable: The entity whose books to compare, by id. Omit for the group parent. `source_ledger` applies to the group parent only: QuickBooks keeps its books, not a subsidiary's.

## Response `200`

Successful Response

- OperationEnvelopeReconciliationPreviewResponse
  - `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` ReconciliationPreviewResponse: The comparison for one period end. Nothing is written.
    - `period` string, required
    - `as_of` string, date, required: The period's last day.
    - `fiscal_year_start` string, date, required: Income-statement accounts are compared from this date to `as_of`.
    - `method` 'source_ledger' | 'schedule_register' | 'statement', required
    - `source` string, required: The system the independent side was read from.
    - `report_basis` string, nullable: Accounting basis the source reported on.
    - `last_sync_at` string, date-time, nullable: When the source was last synced. A difference on a sync older than the period end may be activity not yet synced, not a fault in the mirror.
    - `accounts_compared` integer, required: Accounts with a balance on either side; zero on both is left out.
    - `accounts_tied` integer, required
    - `accounts_different` integer, required: Every account that does not tie, whatever the reason.
    - `total_difference` number, required: Sum of the absolute differences across accounts, not a net figure: one missing transaction counts on each account it touches.
    - `rows` ReconciliationRow[], required: Accounts that do not tie, largest difference first; tied accounts follow when `include_tied` is set.
      - `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.
    - `notes` string[]: How the comparison was made, and anything that qualifies it.
  - `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)