---
title: "Submit a reconciliation"
method: POST
path: "/api/v1/reconciliations"
tags: ["ReconcileIQ"]
---

# Submit a reconciliation

`POST /api/v1/reconciliations`

## Request

- Base URL: `https://api.reconcileiq.com`
- URL: `https://api.reconcileiq.com/api/v1/reconciliations`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Submits a bank dataset and a book dataset for reconciliation. The job is queued and processed asynchronously; poll the returned `poll_url`.

**Strict canonical format.** No column mapping or auto-detection is performed. Each row of both `bank` and `book` must be exactly `{ date, amount, description }` with no extra keys:
- `date`: string, exact ISO 8601 `YYYY-MM-DD`, must be a real calendar date.
- `amount`: a finite JSON number, signed (negatives allowed).
- `description`: string, 1 to 500 characters.

No extra top-level keys are allowed (only `bank`, `book`, `options`). Any structural deviation is rejected with HTTP **422 `invalid_dataset_format`**, listing the offending dataset, row index, and field.

**Credits.** A reconciliation costs credits equal to the number of bank rows, and is charged ONLY if the run completes and is verified (`result.verification.is_verified === true`). If the dataset is obviously unaffordable at submit time, the request is rejected synchronously with 402. Requires scope `reconcileiq:write`.

## Request body

- ReconciliationRequest
  - `bank` CanonicalRow[], required
    - `date` string, date, required: Exact ISO 8601 YYYY-MM-DD; must be a real calendar date.
    - `amount` number, required: Signed finite number (negatives allowed).
    - `description` string, required
  - `book` CanonicalRow[], required
    - `date` string, date, required: Exact ISO 8601 YYYY-MM-DD; must be a real calendar date.
    - `amount` number, required: Signed finite number (negatives allowed).
    - `description` string, required
  - `options` object
    - `allowedDateDifferenceInDays` integer
    - `includeMatched` boolean
    - `allowOverage` boolean

## Response `202`

Reconciliation queued.

- object
  - `reconciliation_id` string, required
  - `status` 'queued', required
  - `poll_url` string, required

## Other responses

- `400`: Structurally invalid request (Zod). Distinct from the 422 format-contract gate.
- `401`: Missing, invalid, or revoked API key.
- `402`: Not enough credits to run/charge the job.
- `403`: Authenticated but the key lacks the required scope.
- `422`: Bank Reconciler canonical dataset contract violation.
- `429`: Per-key rate limit exceeded (120 requests / 60s window).
- `503`: The serial job queue for this product is full; retry shortly.

---

[API](https://skmtc.dev/reconcileiq/apis/reconcileiq-public-api.md) · [All operations](https://skmtc.dev/reconcileiq/apis/reconcileiq-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/reconcileiq/apis/reconcileiq-public-api/revisions/5401beef8653?raw)