Reconciliation API

Reconciliation compares internal ledger records with external statements and operational evidence so breaks can be investigated, matched, accepted, rejected, and closed with a clear audit trail.

Who uses this. Reconciliation analysts, finance operations, treasury, and auditors use reconciliation runs during end-of-day, month-end, settlement review, and safeguarding checks.

How it works. A run groups source files, expected ledger data, matching decisions, discrepancies, notes, and run status. Automatic matching can propose links, while manual matching lets operations resolve exceptions with documented reasoning.

What users do. Users create a run, upload a bank or processor statement, trigger matching, review unmatched items, add notes, accept or reject matches, and close or reopen items when evidence changes.

Outcomes and side effects. Reconciliation does not change customer balances by itself. It records evidence, exposes breaks, and guides follow-up postings such as journals, reversals, or settlement corrections.

See also:

• Ledgers & Balance Management
• Journal Transactions
• OpenAPI spec
• Postman collection

Overview

Reconciliation flow:

1. Create a run (manual or automatic)
2. Upload source statement file
3. Trigger auto-match and/or create manual matches
4. Review items, matches, discrepancies
5. Accept/reject/update notes, close/reopen items

All endpoints require authentication.

Endpoints

Legacy Reconcile Trigger

POST /v1/ledgers/{id}/reconcile

Legacy ledger-level reconcile trigger.

Reconciliation Runs

POST /v1/ledgers/reconciliation/runs

Create run.

Request body:

{
  "ledger_id": "uuid",
  "mode": "automatic",
  "source_type": "upload",
  "idempotency_key": "optional-string",
  "note": "optional run name"
}

GET /v1/ledgers/reconciliation/runs

List runs (GetAll-compatible query params; supports ledger_id passthrough).

GET /v1/ledgers/reconciliation/runs/{runID}

Get run by ID.

PATCH /v1/ledgers/reconciliation/runs/{runID}

Update run note.

{
  "note": "optional run note"
}

DELETE /v1/ledgers/reconciliation/runs/{runID}

Delete run.

Source Files

POST /v1/ledgers/reconciliation/runs/{runID}/sources/upload

Upload source statement file (multipart form-data).

Form fields:

• file (required)
• idempotency_key (optional)

Response:

{
  "source_file": { "id": "uuid", "run_id": "uuid" },
  "imported": 12
}

DELETE /v1/ledgers/reconciliation/runs/{runID}/sources/{fileID}

Delete uploaded source file (scoped by runID + fileID).

GET /v1/ledgers/reconciliation/runs/{runID}/sources

List source files for run.

Matching

POST /v1/ledgers/reconciliation/runs/{runID}/auto-match

Run auto-match for selected run.

Response:

{
  "matched": 5
}

POST /v1/ledgers/reconciliation/runs/{runID}/manual-match

Create manual match links.

{
  "source_entry_ids": ["uuid"],
  "ledger_entry_ids": ["uuid"],
  "note": "optional note"
}

GET /v1/ledgers/reconciliation/runs/{runID}/matches

List matches for run.

POST /v1/ledgers/reconciliation/matches/{matchID}/accept

Accept suggested match.

POST /v1/ledgers/reconciliation/matches/{matchID}/reject

Reject match.

PATCH /v1/ledgers/reconciliation/matches/{matchID}/note

Update match note.

{
  "note": "optional note"
}

Run Data Views

GET /v1/ledgers/reconciliation/runs/{runID}/items

List source entries for run.

GET /v1/ledgers/reconciliation/runs/{runID}/gl-only

List GL entries not linked in this/other runs.

GET /v1/ledgers/reconciliation/runs/{runID}/gl-all

List all GL entries available for this run context.

GET /v1/ledgers/reconciliation/runs/{runID}/discrepancies

List discrepancies for run.

Item Resolution

POST /v1/ledgers/reconciliation/items/{itemID}/close

Close source item.

{
  "ledger_id": "uuid",
  "reason": "manual_review",
  "note": "optional note"
}

POST /v1/ledgers/reconciliation/items/{itemID}/reopen

Reopen source item.

Ledger Account Helper

GET /v1/ledgers/accounts

List ledger accounts with unreconciled counts, optional ledger_id query filter.

Status and Enumerations

• Run status: pending, running, completed, failed, closed
• Run mode: manual, automatic
• Source file format: csv
• Source file status: processed, failed
• Match status: suggested, accepted, rejected
• Source entry match status: unmatched, matched, partial, closed
• Discrepancy status: open, in_review, closed
• Discrepancy severity: info, warning, critical