Reconciliation API

This reference documents reconciliation routes registered in and handled by .

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, camt.053
• 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