Preview Reconciling Item

post/extensions/roboledger/{graph_id}/operations/preview-reconciling-item

Read what changed on a reconciling item — an event whose source-system payload changed after it was posted (list them with list-event-blocks is_reconciling_item=true). Returns the posted entries against the accepted payload, the per-account net difference, which disposition applies by default, and anything blocking the others. Writes nothing. Run this before resolve-reconciling-item and agree the treatment with the user — restate moves prior months' figures, catch_up does not.

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

Header parameters

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

Request body

Required, application/json.

Field	Type	Description
`event_id`required	string	Event id (evt_ prefixed) to inspect

Example request

curl

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/preview-reconciling-item" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "event_id": "string"
}'

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

ReconcilingItemPlan

Command-specific result payload

ReconcilingItemPlan fields

Field Type Description

event_idrequired string

external_idoptional string

sourcerequired string

event_typerequired string

event_statusrequired string

drift_detected_atoptional

string (date-time)

When the sync first saw this difference

default_dispositionrequired

string

What resolve would do with no disposition given: restate while every affected period is open and nothing blocks it, catch_up otherwise.

One of: restate, catch_up, acknowledge

default_posting_dateoptional

string (date)

Where a catch-up entry would land by default

affected_posting_datesoptional

string (date)[]

Posting dates of the event's entries

closed_periodsoptional

string[]

Names of closed periods the event's entries sit in

prior_entriesoptional

ReconcilingItemEntrySummary[]

One entry on either side of the comparison.

ReconcilingItemEntrySummary fields

Field	Type	Description
`entry_id`optional	string	Entry id; null for the accepted side, which is not posted yet
`external_id`optional	string
`posting_date`optional	string (date)
`memo`optional	string
`status`optional	string	Entry status; null on the accepted side
`total_debit`optional	integer	Default: `0`
`total_credit`optional	integer	Default: `0`

accepted_entriesoptional

ReconcilingItemEntrySummary[]

One entry on either side of the comparison.

ReconcilingItemEntrySummary fields

Field	Type	Description
`entry_id`optional	string	Entry id; null for the accepted side, which is not posted yet
`external_id`optional	string
`posting_date`optional	string (date)
`memo`optional	string
`status`optional	string	Entry status; null on the accepted side
`total_debit`optional	integer	Default: `0`
`total_credit`optional	integer	Default: `0`

deltaoptional

ReconcilingItemDeltaLine[]

Per-account net change; empty when none

ReconcilingItemDeltaLine fields

Field	Type	Description
`element_id`optional	string	CoA element id; null when the account is unmapped
`element_external_id`optional	string	Source-system account id, when the line carried one
`element_code`optional	string	Account code
`element_name`optional	string	Account name
`prior_net`required	integer	Net of the posted entries, debit-positive
`accepted_net`required	integer	Net of the new payload, debit-positive
`delta`required	integer	accepted_net - prior_net

no_gl_effectoptional

boolean

The change moves no money — a memo or reference edit. catch_up posts nothing; restate still regenerates so the entries carry the new text.

Default: false

restate_blockersoptional

string[]

Why restate is unavailable, if it is: a closed period, an entry that was reversed or is not posted, or entries from elsewhere sharing this event's transaction.

unmapped_element_external_idsoptional

string[]

Accounts in the new payload with no mapping in this graph. Both dispositions that write need them mapped first.

atrequired

string

ISO-8601 UTC timestamp

createdByoptional

string

User ID that initiated the operation (null for legacy callers)

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