## List the VAT check history of an address (tenant:masterdata:read)

`GET /api/masterdata/addresses/{id}/vat-checks`

Module: Master data · operationId: `listAddressVatChecks` · Tag: VAT checks · Auth: access token (`Authorization: Bearer <accessToken>`)

Newest first. `limit` above 200 or below 1 is rejected with `400`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer |  | (default `50`; max 200) |
| `offset` | query | integer |  | Entries to skip; a negative or non-numeric value is `400 invalid` (default `0`) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** One page of checks (`application/json`)
- **400** Malformed body or query parameter (`application/json`)
- **401** Missing, invalid or expired token (empty body)
- **403** The token lacks the permission or carries no tenant (`application/json`)
- **404** Not found in the caller's tenant (or merged, see `code`) (`application/json`)

Fields of the 200 answer:

- `items` (array of VatCheck, required): Checks, newest first
  - `cached` (boolean, required): The answer came from the 24 h cache (no call to VIES or BZSt)
  - `checkedAt` (string (date-time), required): Time of the check
  - `checkedBy` (string, required): Who ran the check (subject of the token)
  - `id` (string (uuid), required): Id of the protocol entry
  - `method` (string, required): Service that answered (one of `VIES`, `BZST`)
  - `ownVatId` (string, required): The tenant's VAT ID used for the request (may be empty for VIES)
  - `qualified` (boolean, required): Qualified check (name and postal address sent)
  - `status` (VatCheckStatus, required): `OFFICIALLY_CONFIRMED` (valid), `PARTIALLY_CONFIRMED` (valid, some qualified data differs), `OFFICIALLY_NOT_CONFIRMED` (invalid), `FORMALLY_VALID_NO_OFFICIAL_CHECK` (German VAT ID in a qualified BZSt check: valid format only, BZSt does not confirm German IDs), `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`, `NOT_CHECKED`. (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`, `NOT_CHECKED`)
  - `statusDisplay` (string, required): German display text
  - `vatId` (string, required): Checked VAT ID
  - `addressId` (string (uuid)): Absent for checks of a service without address
  - `cityMatch` (VatMatch): Qualified result per field: A match, B mismatch, C not queried, D not provided by the member state (one of `A`, `B`, `C`, `D`)
  - `companyNameMatch` (VatMatch): Qualified result per field: A match, B mismatch, C not queried, D not provided by the member state (one of `A`, `B`, `C`, `D`)
  - `officialRequestId` (string): Request id of BZSt or consultation number of VIES (evidence)
  - `retryAfter` (string (date-time)): Suggested time for a new attempt when `serviceUnavailable`
  - `serviceUnavailable` (boolean): VIES
  - `sourceCheckId` (string (uuid)): The check whose cached result this entry repeats
  - `statusCode` (string): Status code of the service: BZSt `evatr-*`, VIES `VIES_VALID`, `VIES_INVALID` or its error code (e.g. `MS_UNAVAILABLE`), `TECHNICAL_ERROR` for a failed connection
  - `statusMessage` (string): Message of the service
  - `streetMatch` (VatMatch): Qualified result per field: A match, B mismatch, C not queried, D not provided by the member state (one of `A`, `B`, `C`, `D`)
  - `validFrom` (string (date)): Validity start reported by the service (YYYY-MM-DD)
  - `validTill` (string (date)): Validity end reported by the service (YYYY-MM-DD)
  - `zipMatch` (VatMatch): Qualified result per field: A match, B mismatch, C not queried, D not provided by the member state (one of `A`, `B`, `C`, `D`)
- `total` (integer, required): Number of checks of the address

Example 200 answer:

```json
{
  "items": [
    {
      "addressId": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
      "cached": false,
      "checkedAt": "2026-11-03T09:14:22Z",
      "checkedBy": "christina.adler@muster-it.example",
      "id": "1f3b5d7f-9a1c-4e3b-8d5f-7a9c1e3b5d7f",
      "method": "VIES",
      "officialRequestId": "WAPIAAAAZ3hT2k9Q",
      "ownVatId": "DE999000111",
      "qualified": false,
      "status": "OFFICIALLY_CONFIRMED",
      "statusCode": "VALID",
      "statusDisplay": "Gültig",
      "statusMessage": "Die USt-IdNr. ist laut VIES gültig.",
      "vatId": "DE811234567"
    }
  ],
  "total": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/masterdata/addresses/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4/vat-checks' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
