# List matches

List reconciliation matches for the authenticated tenant.

Returns a paginated list of matches with joined transaction and invoice fields. Filters combine with AND.

This is how you find a match without a UUID from the product. Filter with invoice number (`invoiceId`) and transaction code (`transactionId`). A live auto-match is unique for that pair. Each item’s `id` is the UUID required by Get match, Update match, and Cancel match.

## See also

- [Matches](https://www.invunion.com/knowledge-base/api/matches/). Which call to use for each change.
- [Get invoice](https://www.invunion.com/knowledge-base/api/get-invoice/) (`GET /api/v1/invoices/:code`). Live matches are also nested on the invoice.
- [Get transaction](https://www.invunion.com/knowledge-base/api/get-transaction/) (`GET /api/v1/transactions/:code`). Live matches are also nested on the transaction.

- HTTP method: `GET`
- Path: `/api/v1/matches`
- URL: `https://api.invunion.com/api/v1/matches`
- Required scope: `matches:read`
- HTML docs: https://www.invunion.com/knowledge-base/api/list-matches/
- Markdown docs: https://www.invunion.com/knowledge-base/api/list-matches.md


## Query parameters

| Name | Type | Required | Description | Allowed values | Example |
| --- | --- | --- | --- | --- | --- |
| `page` | integer | optional | Page number. Default 1. |  | `1` |
| `pageSize` | integer | optional | Page size. Default 20, maximum 100. |  | `20` |
| `sortBy` | string, no maximum | optional | Sort column. Default created_at. | `created_at`, `matched_amount`, `confidence_score` |  |
| `sortOrder` | string, no maximum | optional | Sort direction. Default desc. | `asc`, `desc` |  |
| `status` | string, no maximum | optional | Filter by match status. | `active`, `cancelled`, `pending_review`, `confirmed`, `rejected` |  |
| `matchType` | string, no maximum | optional | Filter by how the match was created. | `ai_auto`, `manual`, `rule`, `wallet` |  |
| `minConfidence` | number | optional | Minimum confidence_score (0-100). |  | `80` |
| `transactionId` | string, no maximum | optional | Filter by transaction code (`transaction_code`). |  | `TX-8891` |
| `invoiceId` | string, no maximum | optional | Filter by invoice number. |  | `INV-2026-0042` |


## Errors

| Error | HTTP code | Description |
| --- | --- | --- |
| `Missing Bearer token` | `401` | The Authorization header is missing or is not a Bearer token. |
| `Invalid or revoked API key` | `401` | The API key is unknown, malformed, expired, or has been revoked. |
| `API key is missing scope matches:read` | `403` | The key does not include matches:read. A write scope does not imply the matching read scope. |
| `Too many requests, please try again later` | `429` | Wait and retry. The Retry-After header is the number of seconds to wait. |
| `Invalid query parameters` | `400` | A query value failed validation. details lists field and message. |
| `Internal server error` | `500` | Unexpected server error. The JSON body includes correlationId. Retry with backoff. |

## Request (curl)

```bash
curl --request GET \
  --url https://api.invunion.com/api/v1/matches?page=1&pageSize=20&status=active \
  --header 'accept: application/json' \
  --header 'authorization: Bearer uk_live_YOUR_API_KEY'
```

## Request (Python)

```python
import requests

url = "https://api.invunion.com/api/v1/matches?page=1&pageSize=20&status=active"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer uk_live_YOUR_API_KEY",
}
response = requests.get(url, headers=headers)
print(response.json())
```

## Request (Ruby)

```ruby
require 'net/http'
require 'json'
require 'uri'

uri = URI("https://api.invunion.com/api/v1/matches?page=1&pageSize=20&status=active")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['Accept'] = 'application/json'
request['Authorization'] = 'Bearer uk_live_YOUR_API_KEY'
response = http.request(request)
puts response.body
```

## Request (JavaScript)

```javascript
const response = await fetch("https://api.invunion.com/api/v1/matches?page=1&pageSize=20&status=active", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer uk_live_YOUR_API_KEY"
  },
});
const data = await response.json();
```

## Request (Go)

```go
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.invunion.com/api/v1/matches?page=1&pageSize=20&status=active", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Authorization", "Bearer uk_live_YOUR_API_KEY")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}
```

## Request (Node)

```javascript
const response = await fetch("https://api.invunion.com/api/v1/matches?page=1&pageSize=20&status=active", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer uk_live_YOUR_API_KEY"
  },
});
console.log(await response.json());
```

## Success (200)

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "1c9e6679-7425-40de-944b-e07fc1f90ae7",
        "tenant_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "transaction_id": "2d0e6679-7425-40de-944b-e07fc1f90ae7",
        "invoice_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
        "matched_amount": 1000,
        "match_type": "manual",
        "confidence_score": 100,
        "status": "active",
        "transaction_amount": 1000,
        "direction": "in",
        "flow_type": "payment",
        "transaction_description": "Leones Cars — wire payment",
        "transaction_date": "2026-09-12",
        "transaction_code": "TX-8891",
        "counterparty_name": "Leones Cars",
        "invoice_number": "INV-2026-0042",
        "invoice_kind": "invoice",
        "invoice_amount": 12000,
        "invoice_counterparty_name_display": "Leones Cars",
        "created_at": "2026-09-12T09:00:00.000Z"
      },
      {
        "id": "9fbe3506-5c28-41a3-ec25-32619d4fb7e5",
        "tenant_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "transaction_id": "7d9c13e4-3a06-4f81-ca03-104f7b2d95c3",
        "invoice_id": "8ead24f5-4b17-4092-db14-21508c3ea6d4",
        "matched_amount": 4200,
        "match_type": "ai_auto",
        "confidence_score": 94,
        "status": "active",
        "transaction_amount": 4200,
        "direction": "out",
        "flow_type": "payment",
        "transaction_description": "Grove Street Garage — PayPal",
        "transaction_date": "2026-09-08",
        "transaction_code": "TX-8892",
        "counterparty_name": "Grove Street Garage",
        "invoice_number": "INV-2026-0043",
        "invoice_kind": "invoice",
        "invoice_amount": 4200,
        "invoice_counterparty_name_display": "Grove Street Garage",
        "created_at": "2026-09-08T14:22:00.000Z"
      }
    ],
    "total": 2,
    "page": 1,
    "pageSize": 20,
    "hasMore": false
  }
}
```