> ## Documentation Index > Fetch the complete documentation index at: https://docs.reconifyhq.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Reconify's API reference is read-only for customer data. Do not invent endpoints or authentication behavior beyond the OpenAPI contract. > The public OpenAPI document contains only the documented external /v2 contract. # Config reference > Every reconify.yaml key: sources, pairs, passes, and the index backend. ## Top level ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} version: 1 timezone: "UTC" ``` | Field | Required | Description | | ---------- | -------- | ----------------------------------------------------------------------------------------- | | `version` | yes | Config schema version. Currently `1`. | | `timezone` | no | Default IANA timezone for date parsing when a source doesn't set `tz`. Defaults to `UTC`. | ## `sources` Each source maps one file family into Reconify's normalized transaction shape. ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} sources: left_source: file_pattern: "path/to/left-files/*.csv" parser: type: csv date_col: "Date" date_layout: "2006-01-02" amount_col: "Amount" decimal: "." thousands: "," multiplier: 100 currency_col: "Currency" name_col: "Details" ref_col: "Reference" group_col: "Reference" ``` | Field | Required | Description | | -------------- | -------- | -------------------------------------------------------------------------------------- | | `file_pattern` | yes | Path or glob `reconcile` reads when no explicit `--left-file`/`--right-file` is given. | ### Parser fields | Field | Required | Description | | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | no | `csv`, `json`, `xlsx`, or `auto`. `auto` (or omitted) infers from the extension: `.csv`, `.json`/`.ndjson`, `.xlsx`/`.xlsm`. | | `sheet` | no | XLSX/XLSM sheet name. Defaults to the first sheet. | | `date_col` | yes | Column that contains the transaction date. | | `date_layout` | yes | Go time layout, such as `2006-01-02`. | | `tz` | no | IANA timezone for parsing dates that lack an offset. Defaults to `UTC`. | | `amount_col` | yes | Column that contains the amount. | | `decimal` | no | Decimal separator, one character. Defaults to `.`. | | `thousands` | no | Thousands separator, one character. | | `multiplier` | yes | Converts the parsed amount to minor units. Must be greater than zero. | | `currency_col` | no | Currency code column. | | `name_col` | no | Description or merchant name column. | | `ref_col` | no | Reference, transaction ID, or order ID column: the matching key. | | `group_col` | no | Duplicate-detection key, independent of `ref_col`. Falls back to `ref_col` when omitted. Use it when several rows legitimately share a reference, such as an invoice paid in installments, but each row has its own unique matching identifier. | | `skip_raw` | no | Skip raw row map allocation, for lower memory use on large sources. | Column lookup is case-insensitive. Missing optional columns (`ref_col`, `name_col`, `currency_col`) are silently ignored rather than rejected. ### Parser types | Type | Files | | --------------- | -------------------------------------------------------- | | `auto` or empty | Infer from `.csv`, `.json`, `.ndjson`, `.xlsx`, `.xlsm`. | | `csv` | CSV files with a header row. | | `json` | JSON arrays and NDJSON objects. | | `xlsx` | Modern Excel workbooks (`.xlsx`, `.xlsm`). | Legacy `.xls` files are not supported. ### Date layouts Reconify uses Go reference-time layouts, not strftime or `YYYY-MM-DD`: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} date_layout: "2006-01-02" # 2026-06-16 date_layout: "02/01/2006" # 16/06/2026 ``` ### Amount examples ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} amount_col: "Amount" decimal: "." thousands: "," multiplier: 100 ``` `1,234.56` becomes `123456` (`1,234.56` in minor units). ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} amount_col: "amount" multiplier: 1 ``` `123456` stays `123456` (already minor units, `1,234.56`). Parenthetical negatives are supported: `(1,234.56)` becomes `-123456`. ## `pairs` Pairs define which sources to reconcile against each other and what tolerances apply. ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} pairs: left_source_vs_right_source: left: left_source right: right_source date_window: "1d" amount_tolerance_minor: 0 name_mode: "tokens" name_match_threshold: 0.5 result_mode: "all" ``` | Field | Required | Description | | ------------------------ | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `left` | yes | Source name for the left side. | | `right` | yes, unless `rights` is set | Single counterpart source name. Mutually exclusive with `rights`. | | `rights` | yes, unless `right` is set | Ordered list of counterpart source names for multi-counterpart runs. Mutually exclusive with `right`. Each entry must be non-empty and unique. See [Sources and pairs](/cli/concepts/sources-and-pairs#one-left-several-counterparts-rights). | | `date_window` | no | Timing tolerance, such as `1d` or `2d`. | | `amount_tolerance_minor` | no | Amount tolerance in minor units. Defaults to `0`. | | `name_mode` | no | `none` (default) or `tokens`. `tokens` enables name-token similarity matching after reference matching. | | `name_match_threshold` | no | Jaccard similarity threshold for `name_mode: tokens`, where `0 < x < 1`. Defaults to `0.5`. `1.0` is rejected: a strict comparison against a ceiling could never match. | | `result_mode` | no | Which events the writer emits: `all` (default), `exceptions_only`, or `summary_only`. See [`reference/output`](/cli/reference/output#result_mode). | Recommended defaults: use `name_mode: none` when both sources have reliable references. Use `name_mode: tokens` when references are sparse but names or descriptions are consistent. Start `amount_tolerance_minor` at `0`, and widen it only once you've confirmed a known rounding difference between the source systems. ## `passes` By default, a pair runs reference matching, then optional name-token matching when `name_mode: tokens` is set. Declare `passes` for explicit control over the matching pipeline: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} pairs: left_source_vs_right_source: left: left_source right: right_source date_window: "1d" amount_tolerance_minor: 0 passes: - type: reference_one_to_one - type: name_tokens_one_to_one ``` | Pass type | `group_by` | Description | | ------------------------ | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `reference_one_to_one` | n/a | Matches one left row to one right row by reference. The default first tier. | | `name_tokens_one_to_one` | n/a | Matches remaining unmatched rows by Jaccard token similarity on the name field. Equivalent to `name_mode: tokens`. | | `one_to_many` | `reference` \| `name` \| `group_key` (default `reference`) | Sums right rows sharing a group key and compares the total to one left row. See [Matching algorithm](/cli/concepts/matching-algorithm#one-invoice-many-payments-one_to_many). | | `many_to_many` | `reference` \| `name` \| `group_key` (default `reference`) | Sums both sides' rows sharing a group key and compares the totals. See [Matching algorithm](/cli/concepts/matching-algorithm#split-settlements-many_to_many). | Passes run in the order listed. Each pass sees only rows earlier passes left unmatched. Omitting `passes` preserves the default reference-then-tokens behavior. When `passes` is set, `name_mode: tokens` is rejected: add a `name_tokens_one_to_one` pass explicitly instead. `rights` and `passes` are orthogonal and combine freely: `rights` selects which counterpart *sources* to reconcile against, in order; `passes` defines the matching *strategy* used within each counterpart. ## `index` Reconify builds an index for the right source before matching the left source. The index backend controls how that index is stored. ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} index: backend: auto spill_dir: "/tmp/reconify" auto_max_right_file_mb: 2048 partition_count: 32 max_memory_mb: 8192 max_temp_disk_mb: 16384 ``` | Field | Required | Description | | ------------------------ | -------- | ------------------------------------------------------------------------------------------------- | | `backend` | no | `memory`, `disk`, `auto` (default), or `partitioned`. | | `spill_dir` | no | Directory for `disk`/`auto`/`partitioned` temporary files. Defaults to the system temp directory. | | `auto_max_right_file_mb` | no | File-size threshold above which `auto` selects `disk` instead of `memory`. Defaults to `2048`. | | `partition_count` | no | Partition count for `partitioned`. `0` selects adaptively; explicit values must be `>= 2`. | | `max_memory_mb` | no | Resource safeguard for `auto`. `0` leaves the budget uncapped. | | `max_temp_disk_mb` | no | Resource safeguard for `auto`/`partitioned`. `0` leaves the budget uncapped. | | Backend | Use when | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `memory` | The right-side index fits comfortably in RAM. Fastest. | | `disk` | Lower RAM usage, SQLite-backed spill, slower point lookups. | | `auto` | No budgets: threshold-based selection against `auto_max_right_file_mb`. With `max_memory_mb`/`max_temp_disk_mb` set: resource-aware fallback through memory, then disk, then partitioned. | | `partitioned` | Bounded memory for a large single-counterpart CSV run, including grouped passes, at the cost of extra sequential disk passes. | With either budget configured, `auto` records why each candidate backend was accepted or rejected in structured output. These are resource safeguards, not throughput guarantees: an unmet estimate fails the run explicitly rather than silently degrading. See [Handle large files](/cli/guides/large-data) for the full tuning guide. ## Full example ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} version: 1 timezone: "UTC" index: backend: auto auto_max_right_file_mb: 2048 sources: left_source: file_pattern: "path/to/left-files/*.csv" parser: type: csv date_col: "Date" date_layout: "2006-01-02" amount_col: "Amount" decimal: "." thousands: "," multiplier: 100 currency_col: "Currency" name_col: "Memo" ref_col: "SettlementBatchID" right_source: file_pattern: "path/to/right-files/*.csv" parser: type: csv date_col: "settlement_date" date_layout: "2006-01-02" amount_col: "net_amount" multiplier: 100 currency_col: "currency" name_col: "description" ref_col: "batch_id" another_source: file_pattern: "path/to/another-files/*.csv" parser: type: csv date_col: "settlement_date" date_layout: "2006-01-02" amount_col: "net_amount" multiplier: 100 currency_col: "currency" name_col: "description" ref_col: "batch_id" pairs: left_source_vs_counterparts: left: left_source rights: [right_source, another_source] date_window: "2d" amount_tolerance_minor: 0 passes: - type: many_to_many group_by: reference ``` This config reconciles `left_source` against two counterparts in order, using `many_to_many` to group and sum rows sharing a reference on both sides, with `auto` choosing the index backend per counterpart file size.