Browse the extensions reference

Set Reconciliation Policy

post/extensions/roboledger/{graph_id}/operations/set-reconciliation-policy

Part of RoboLedger: Ledger & Events.

Change how much the close cares about one reconciliation: whether the period's close waits on it (required_for_close); its materiality, the difference up to which it still counts as reconciled; whether the close also waits for a sign-off (review_required); and whether the reviewer must be someone other than the person who ran the comparison (separate_reviewer, which can only be turned on while the graph has at least two members who can write; if it later has one, turn it off or add a member). For a statement reconciliation, statement_cycle says how often the statement is issued (monthly, quarterly or annual): a period is covered by the latest statement ending within the cycle that ends with it, so a quarterly statement still covers the months between statements. Omitted fields keep their value. The next refresh-reconciliations uses the new materiality; comparisons already recorded are not re-judged.

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.

required_for_closeoptionalboolean

Whether the period's close waits on it. Omit to keep.

materialityoptionalnumber

A difference up to this amount still counts as reconciled. Omit to keep.

Constraints: 0–10000000000000

review_requiredoptionalboolean

Whether the close also waits for a sign-off, not just for the two sides to reconcile. Omit to keep.

separate_revieweroptionalboolean

Whether the person who signs off must be someone other than the person who ran the comparison. It can only be turned on when the graph has at least two members who can write. Omit to keep.

statement_cycleoptionalstring

statement blocks only: how often the account's statement is issued. A period is covered by the latest statement ending within the cycle that ends with it, so a quarterly statement covers the two months before the next one. Omit to keep.

One of: monthly, quarterly, annual

Example request

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

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

resultoptionalReconciliationPolicyResponse

Command-specific result payload

ReconciliationPolicyResponse fields
FieldTypeDescription
structure_idrequiredstring
required_for_closerequiredboolean
materialityrequirednumber
review_requiredrequiredboolean
separate_reviewerrequiredboolean
statement_cycleoptionalstring

statement blocks only: how often the statement is issued.

One of: monthly, quarterly, annual

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