# Get match

Get one match by UUID.

Returns the match with joined transaction and invoice fields, including invoice dates and settlement amounts.

Matches have no business code, and the Invunion UI does not show the match UUID. Identify a match with invoice number and transaction code: List matches with invoiceId and transactionId, or read matches[].id on Get invoice / Get transaction. Create match and match webhooks also return id. Use this endpoint only after you already have that UUID.

## See also

- [Matches](https://www.invunion.com/knowledge-base/api/matches/). Which call to use for each change.
- [List matches](https://www.invunion.com/knowledge-base/api/list-matches/) (`GET /api/v1/matches`). Find the UUID by invoice number and transaction code.
- [Get invoice](https://www.invunion.com/knowledge-base/api/get-invoice/) (`GET /api/v1/invoices/:code`). Live matches nested on the invoice, including id.
- [Get transaction](https://www.invunion.com/knowledge-base/api/get-transaction/) (`GET /api/v1/transactions/:code`). Live matches nested on the transaction, including id.

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

## Path parameters

| Name | Type | Required | Description | Allowed values | Example |
| --- | --- | --- | --- | --- | --- |
| `id` | string, no maximum | required | Match UUID. |  | `1c9e6679-7425-40de-944b-e07fc1f90ae7` |



## 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. |
| `Match not found` | `404` | No match with this UUID exists in the authenticated tenant. |
| `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/1c9e6679-7425-40de-944b-e07fc1f90ae7 \
  --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/1c9e6679-7425-40de-944b-e07fc1f90ae7"
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/1c9e6679-7425-40de-944b-e07fc1f90ae7")
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/1c9e6679-7425-40de-944b-e07fc1f90ae7", {
  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/1c9e6679-7425-40de-944b-e07fc1f90ae7", 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/1c9e6679-7425-40de-944b-e07fc1f90ae7", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer uk_live_YOUR_API_KEY"
  },
});
console.log(await response.json());
```

## Success (200)

```json
{
  "success": true,
  "data": {
    "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",
    "invoice_date": "2026-09-01",
    "due_date": "2026-10-01",
    "invoice_settled": 1000,
    "invoice_open": 11000,
    "invoice_status": "partial"
  }
}
```