ConnectCloud Developers

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:

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

View as Markdown · Interactive reference · OpenAPI