ConnectCloud Developers

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:

{
  "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:

{
  "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}'

View as Markdown · Interactive reference · OpenAPI