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 (defaultfalse)method(string): Service to ask; defaultviesfor a simple,bzstfor a qualified check (German VAT IDs:vies, simple). VIES offers no qualified check:400(one ofvies,bzst)qualified(boolean): Qualified BZSt confirmation: also send company name, street, postal code and city of the main postal address (defaultfalse)
Example:
{
"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 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)
Example 200 answer:
{
"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
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}'