# 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, 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, and Cancel.
- **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.
- **Delete the match row** — [Cancel match](https://www.invunion.com/knowledge-base/api/cancel-match/) (`DELETE /api/v1/matches/:id`). DELETE by UUID from List matches. Prefer Reconcile `unlink_all` when you only need to undo the allocation and keep working from the transaction code.

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.