## Check the VAT ID of an address (tenant:masterdata:write)

`POST /api/masterdata/addresses/{id}/vat-check`

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

Checks the address's `vatId` and stores the result as a protocol entry; the address gets
`vatCheckStatus` and `vatCheckedAt` (its version is not bumped). A simple check asks VIES (EU
Commission; also German VAT IDs; with the tenant's own VAT ID from the company profile as
requester when set, so VIES returns a consultation number). A qualified check asks the BZSt
eVatR service (needs the own VAT ID) and also sends company name, street, postal code and city of
the main postal address; it returns a match result per field. BZSt checks German VAT IDs only
formally, so a qualified check of a German VAT ID without `method` is a simple VIES check
(`qualified: false`). Greek VAT IDs are checked with the prefix `EL` (`GR` is accepted). The body
may be empty (simple check).

A conclusive result (not `TECHNICAL_ERROR` or `CHECK_NOT_POSSIBLE`) answers the same request
(VAT IDs, method and, when qualified, the sent name and address) of the tenant for 24 hours
without calling VIES or BZSt (`cached: true`); `force: true` skips the cache. A cached result
for another address is stored as its own protocol entry with `sourceCheckId` and the source's
`checkedAt`. The address shows the newest check; an inconclusive one never replaces a conclusive
status, and changing the address's VAT ID clears it. A call to VIES or BZSt that outlasts the
request is still finished and stored (up to 45 s); concurrent identical checks of an address
share one call. Technical failures are stored and returned as status `TECHNICAL_ERROR` with `200`; when the service or
the member state is unavailable (e.g. a maintenance window) `serviceUnavailable` is `true` and
`retryAfter` suggests when to try again. `503` (`vat_check_unavailable`) when the check is
switched off. Emits `masterdata.address.vat_checked`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json`

- `force` (boolean): Skip the 24 h cache and ask the service again (default `false`)
- `method` (string): Service to ask; default `vies` for a simple, `bzst` for a qualified check (German VAT IDs: `vies`, simple). VIES offers no qualified check: `400` (one of `vies`, `bzst`)
- `qualified` (boolean): Qualified BZSt confirmation: also send company name, street, postal code and city of the main postal address (default `false`)

Example:

```json
{
  "force": true,
  "qualified": true
}
```

### Responses

- **200** The stored check (`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`)
- **503** The VAT check is switched off (`application/json`)

Fields of the 200 answer:

- `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`)

Example 200 answer:

```json
{
  "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"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/masterdata/addresses/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4/vat-check' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"force":true,"qualified":true}'
```
