Check a VAT identification number (tenant:crm:write)
POST /api/crm/v1/vat/validate
Module: CRM · operationId: validateVatId · Tag: Verification · Auth: access token (Authorization: Bearer <accessToken>)
The ID is cleaned (spaces, dots, dashes) and prefixed with country when it lacks a
country code (GR becomes EL). Then:
- EU IDs, German ones included, are checked officially through the masterdata module: a
simple check asks EU VIES. With
companyNameandcity(plus optionallystreetandzip) it is a qualified confirmation by the BZSt, which also compares the company data (isQualified); it needs the tenant's own VAT ID in the company profile, without it the answer isCHECK_NOT_POSSIBLE. The BZSt does not confirm German IDs, so German IDs always get the simple VIES check (isQualified: false), also with company data. The same check of the tenant is answered from a 24-hour cache (conclusive results only), so repeating it does not query VIES or BZSt again. When VIES, BZSt or the member state cannot be reached, the result isTECHNICAL_ERRORorCHECK_NOT_POSSIBLE. - Swiss UIDs (
CHE+ 9 digits, optionallyMWST/TVA/IVA) get a format check only. - Other countries return
CHECK_NOT_POSSIBLE.
A result is 200; check valid and status. An ID shorter than four characters or a
request the check rejects returns 400; a check the tenant switched off in the CRM settings
(vatCheckEnabled: false) 409 with code: vat_check_disabled; an unreachable or
switched-off official check 502. It needs tenant:crm:write: every check queries VIES or
BZSt and is logged in masterdata. With leadId the lead must exist in the tenant (404) and the
result is stored on it (vatId, vatStatus, vatCheckedAt); an anonymised lead is read-only (409, lead_anonymized).
Request body
application/json (required)
vatId(string, required): VAT ID with or without country code. (max length 32)city(string): For a qualified BZSt confirmation (withcompanyName). (max length 128)companyName(string): For a qualified BZSt confirmation (withcity). (max length 255)country(string): Country code used whenvatIdhas none. (max length 32)leadId(string (uuid)): Stores the result on this lead of the tenant (vatId,vatStatus,vatCheckedAt).street(string): Street for a qualified BZSt confirmation. (max length 255)zip(string): Postal code for a qualified BZSt confirmation. (max length 16)
Example:
{
"leadId": "5b7d9f1a-3c5e-4a7b-9d1f-3a5c7e9b1d3f",
"vatId": "DE999000231"
}
Responses
- 200 Check result (
application/json) - 400 Invalid input (
invalid):fieldnames the first invalid field,details.fieldsevery one (JSON paths for bodies, parameter names for the query). Some refusals have their own code (invalid_sort,invalid_stages,invalid_custom_fields,convert_target_required,invalid_csv, …). (application/json) - 401 Missing, invalid or expired token (no body).
- 403 The token lacks the permission (
insufficient permissions) or has no active tenant. (application/json) - 404 The record does not exist in the token's tenant. (
application/json) - 409 The state of the record (or the tenant's settings) does not allow the request;
codesays why. (application/json) - 500 Unexpected error; details are only logged. (
application/json) - 502 An upstream service (masterdata, VAT check) failed, is switched off or is not configured. (
application/json)
Fields of the 200 answer:
countryCode(string, required): Country code of the VAT ID.isQualified(boolean, required): Company data was compared by the BZSt.status(string, required): Result of the check (the status of the masterdata VAT check). (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 label ofstatus.valid(boolean, required): The VAT ID is valid.vatId(string, required): The normalised ID that was checked.checkedAt(string (date-time)): Time of the check (RFC 3339).cityMatch(BzstMatch): Result of a qualified comparison:Amatches,Bdoes not match,Cnot requested,Dnot provided by the member state. (one ofA,B,C,D)companyNameMatch(BzstMatch): Result of a qualified comparison:Amatches,Bdoes not match,Cnot requested,Dnot provided by the member state. (one ofA,B,C,D)message(string): German explanation.officialRequestId(string): Request ID of VIES or the BZSt for your records.statusCode(string): Detail code (for exampleFORMAT_ERROR,FORMALLY_VALID,CHECK_NOT_POSSIBLEor a VIES or BZSt status code).streetMatch(BzstMatch): Result of a qualified comparison:Amatches,Bdoes not match,Cnot requested,Dnot provided by the member state. (one ofA,B,C,D)validFrom(string (date)): Validity start reported by the BZSt.validTill(string (date)): Validity end reported by the BZSt.zipMatch(BzstMatch): Result of a qualified comparison:Amatches,Bdoes not match,Cnot requested,Dnot provided by the member state. (one ofA,B,C,D)
Example 200 answer:
{
"checkedAt": "2026-10-28T10:02:14Z",
"countryCode": "DE",
"isQualified": false,
"message": "Die USt-IdNr. ist laut VIES gültig.",
"officialRequestId": "WAPIAAAAZ2fK1x9Q",
"status": "OFFICIALLY_CONFIRMED",
"statusCode": "VALID",
"statusDisplay": "Gültig",
"valid": true,
"vatId": "DE999000231"
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/crm/v1/vat/validate' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"leadId":"5b7d9f1a-3c5e-4a7b-9d1f-3a5c7e9b1d3f","vatId":"DE999000231"}'