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 firstcached(boolean, required): The answer came from the 24 h cache (no call to VIES or BZSt)checkedAt(string (date-time), required): Time of the checkcheckedBy(string, required): Who ran the check (subject of the token)id(string (uuid), required): Id of the protocol entrymethod(string, required): Service that answered (one ofVIES,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 ofOFFICIALLY_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 textvatId(string, required): Checked VAT IDaddressId(string (uuid)): Absent for checks of a service without addresscityMatch(VatMatch): Qualified result per field: A match, B mismatch, C not queried, D not provided by the member state (one ofA,B,C,D)companyNameMatch(VatMatch): Qualified result per field: A match, B mismatch, C not queried, D not provided by the member state (one ofA,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 whenserviceUnavailableserviceUnavailable(boolean): VIESsourceCheckId(string (uuid)): The check whose cached result this entry repeatsstatusCode(string): Status code of the service: BZStevatr-*, VIESVIES_VALID,VIES_INVALIDor its error code (e.g.MS_UNAVAILABLE),TECHNICAL_ERRORfor a failed connectionstatusMessage(string): Message of the servicestreetMatch(VatMatch): Qualified result per field: A match, B mismatch, C not queried, D not provided by the member state (one ofA,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 ofA,B,C,D)
total(integer, required): Number of checks of the address
Example 200 answer:
{
"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
curl -X GET 'https://api.mbcom.cloud/api/masterdata/addresses/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4/vat-checks' \
-H "Authorization: Bearer $ACCESS_TOKEN"