ConnectCloud Developers

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 companyName and city (plus optionally street and zip) 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 is CHECK_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 is TECHNICAL_ERROR or CHECK_NOT_POSSIBLE.
  • Swiss UIDs (CHE + 9 digits, optionally MWST/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 (with companyName). (max length 128)
  • companyName (string): For a qualified BZSt confirmation (with city). (max length 255)
  • country (string): Country code used when vatId has 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): field names the first invalid field, details.fields every 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; code says 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 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 label of status.
  • 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: A matches, B does not match, C not requested, D not provided by the member state. (one of A, B, C, D)
  • companyNameMatch (BzstMatch): Result of a qualified comparison: A matches, B does not match, C not requested, D not provided by the member state. (one of A, B, C, D)
  • message (string): German explanation.
  • officialRequestId (string): Request ID of VIES or the BZSt for your records.
  • statusCode (string): Detail code (for example FORMAT_ERROR, FORMALLY_VALID, CHECK_NOT_POSSIBLE or a VIES or BZSt status code).
  • streetMatch (BzstMatch): Result of a qualified comparison: A matches, B does not match, C not requested, D not provided by the member state. (one of A, 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: A matches, B does not match, C not requested, D not provided by the member state. (one of A, 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"}'

View as Markdown · Interactive reference · OpenAPI