---
title: "Create a reconciliation match"
method: POST
path: "/v1/reconciliation/matches"
tags: ["Reconciliation"]
---

# Create a reconciliation match

`POST /v1/reconciliation/matches`

## Request

- Base URL: `https://api.cardda.com`
- URL: `https://api.cardda.com/v1/reconciliation/matches`
- Auth: HTTP bearer

Links two reconciliation records into a match. Both records must exist and be reconcilable
with each other; the concrete match subtype is determined automatically from the pair.

**Note:** the create response returns the bare match, including its `type` (a persisted STI
column, always present; the list endpoint's `methods: [:type]` is redundant). Only the embedded
`record_a` / `record_b` records are list-only — they are not populated on this create response.

## Headers

- `company-id` string, uuid, required

## Request body

- ReconciliationMatchCreate: Payload to create a reconciliation match between two records. Both records must exist and be reconcilable with each other; the match subtype is determined automatically. `company_id` must be supplied in the **body** — the controller does not read it from the `company-id` header.
  - `record_a_id` string, uuid, required: One record to link.
  - `record_b_id` string, uuid, required: The other record to link.
  - `company_id` string, uuid, required: The owning company id. Required in the body (not read from the `company-id` header).

## Response `201`

Match created

- ReconciliationMatch: A reconciliation match — a link between two reconciliation records (e.g. a payable and the bank transaction that paid it). The concrete subtype is chosen automatically from the pair of records being linked.
  - `id` string, uuid, required
  - `company_id` string, uuid
  - `record_a_id` string, uuid, required: One side of the match.
  - `record_b_id` string, uuid, required: The other side of the match.
  - `amount` integer, nullable: The reconciled amount in cents.
  - `type` 'Reconciliation::Match::PayableTransaction' | 'Reconciliation::Match::SubPayable' | 'Reconciliation::Match::PayableCreditNote' | 'Reconciliation::Match::PayableDebitNote' | 'Reconciliation::Match::PayableReimbursement', nullable: Fully-namespaced STI class name of the match, derived from the linked record pair.
  - `record_a` ReconciliationRecord: A reconciliation record — a normalized, read-only projection over reconcilable sources (bank transactions, payables, credit/debit notes, expense reports, imprest funds). Records are matched against each other to reconcile payables with the transactions that paid them. The `embedding` vector is never included in responses.
    - `id` string, uuid, required: The record id (equal to the underlying source record id).
    - `type` string, required: The reconciliation-record subtype.
    - `source_type` string: The polymorphic type of the underlying source record.
    - `company_id` string, uuid
    - `amount_cents` integer: The record's amount in cents.
    - `currency` string
    - `reference_date` string, date-time, nullable: Display date (issue/authorized/created date depending on the source).
    - `document_type` string, nullable: SII document type, for payable-like records.
    - `counterpart_company_id` string, uuid, nullable: The counterpart company id, when applicable.
    - `amount_to_be_reconciled` integer: Remaining amount still to reconcile, in cents.
    - `exhausted` boolean: Whether the record's available balance is genuinely zero.
    - `embedding_content` string, nullable: Text used to build the record's semantic embedding.
    - `matches_as_a` ReconciliationMatch[]: Matches where this record is `record_a`.
    - `matches_as_b` ReconciliationMatch[]: Matches where this record is `record_b`.
    - `matched_records` ReconciliationRecord[]: The records reconciled against this one.
    - `created_at` string, date-time
  - `record_b` ReconciliationRecord: A reconciliation record — a normalized, read-only projection over reconcilable sources (bank transactions, payables, credit/debit notes, expense reports, imprest funds). Records are matched against each other to reconcile payables with the transactions that paid them. The `embedding` vector is never included in responses.
    - `id` string, uuid, required: The record id (equal to the underlying source record id).
    - `type` string, required: The reconciliation-record subtype.
    - `source_type` string: The polymorphic type of the underlying source record.
    - `company_id` string, uuid
    - `amount_cents` integer: The record's amount in cents.
    - `currency` string
    - `reference_date` string, date-time, nullable: Display date (issue/authorized/created date depending on the source).
    - `document_type` string, nullable: SII document type, for payable-like records.
    - `counterpart_company_id` string, uuid, nullable: The counterpart company id, when applicable.
    - `amount_to_be_reconciled` integer: Remaining amount still to reconcile, in cents.
    - `exhausted` boolean: Whether the record's available balance is genuinely zero.
    - `embedding_content` string, nullable: Text used to build the record's semantic embedding.
    - `matches_as_a` ReconciliationMatch[]: Matches where this record is `record_a`.
    - `matches_as_b` ReconciliationMatch[]: Matches where this record is `record_b`.
    - `matched_records` ReconciliationRecord[]: The records reconciled against this one.
    - `created_at` string, date-time
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `401`: Unauthorized
- `422`: One of the records does not exist, or the pair cannot be reconciled

---

[API](https://skmtc.dev/cardda/apis/accounting-api.md) - [All operations](https://skmtc.dev/cardda/apis/accounting-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cardda/apis/accounting-api/revisions/49cf78d0f7ab?raw)