# Matches

Allocate a bank line to an invoice, read auto-matches, and change or undo an allocation. Start from invoice number and transaction code, not a match UUID.

- HTML docs: https://www.invunion.com/knowledge-base/api/matches/
- Markdown docs: https://www.invunion.com/knowledge-base/api/matches.md

## What you will find here

A match is an allocation between an invoice and a bank transaction. List and create use the codes you see in Invunion: invoice number and `transaction_code`. Get, update, reverse, and delete use a match UUID that is not shown in the product. Take that `id` from List matches, Create match, Get invoice, Get transaction, or a `match.created` / `match.suggested` / `match.confirmed` webhook.

Auto-match writes one live row per pair (`confirmed` or `pending_review`). Filter List matches with both codes to find it. Invoice number alone is not enough: one invoice can receive several payments.

## Which call to use

- **Find a live match** — [List matches](https://www.invunion.com/knowledge-base/api/list-matches/) (`GET /api/v1/matches`). Filter with invoice number (`invoiceId`) and transaction code (`transactionId`). Use `status=confirmed` for an auto-match, `active` for a manual match, or `pending_review` for a suggestion. Each item’s `id` is the UUID for Get, Update, Reverse, and Delete. To read several statuses at once, pass `statuses=confirmed,active`.
- **Allocate a payment to an invoice** — [Create match](https://www.invunion.com/knowledge-base/api/create-match/) (`POST /api/v1/matches`). Send the invoice number, transaction code, and `matchedAmount`. This is the public write. The response includes `match.id`.
- **Change the allocated amount on the same pair** — [Update match](https://www.invunion.com/knowledge-base/api/update-match/) (`PUT /api/v1/matches/:id`). List the pair first, then PUT `matchedAmount`. This does not change which invoice or bank line is linked.
- **Confirm a suggestion** — [Update match](https://www.invunion.com/knowledge-base/api/update-match/) (`PUT /api/v1/matches/:id`). List `pending_review` for that pair, then PUT `status: confirmed` with the item `id`.
- **Deny a suggestion** — [Create match](https://www.invunion.com/knowledge-base/api/create-match/) (`POST /api/v1/matches`). POST the invoice number, transaction code, and `status: rejected`. `matchedAmount` is not required. No match UUID.
- **Undo an auto-match** — [Reconcile transaction](https://www.invunion.com/knowledge-base/api/reconcile-transaction/) (`POST /api/v1/transactions/:code/reconcile`). POST `{ "action": "unlink_all" }` on the transaction code. That cancels every live match on the bank line. No match UUID.
- **Point the payment at another invoice** — [Create match](https://www.invunion.com/knowledge-base/api/create-match/) (`POST /api/v1/matches`). Unlink with Reconcile transaction `unlink_all`, then Create match with the new invoice number, the same transaction code, and `matchedAmount`. Do not use Update match.
- **Reverse a wrong payment** — [Reverse match](https://www.invunion.com/knowledge-base/api/reverse-match/) (`POST /api/v1/matches/:id/reverse`). POST `reason` (`wrong_transaction`, `wrong_amount`, `duplicate`, or `other`) and an optional `note` on the match UUID. Add `replacement` with the right transaction code to match it in the same step. The match is kept as cancelled with who, when, and why, and one `invoice.settlement_changed` webhook is sent. `wrong_transaction` also records the pair as rejected.
- **Delete a suggestion or a rejected pair** — [Delete match](https://www.invunion.com/knowledge-base/api/cancel-match/) (`DELETE /api/v1/matches/:id`). DELETE by UUID from List matches. Only for `pending_review`, `rejected`, or `cancelled` rows: an active or confirmed payment returns 409. Reverse it instead.

Do not use Reconcile `save` to edit an allocation. That path is the Invunion workbench: it needs the match UUID plus counterparty, payment method, invoice, and amount together.