## 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:

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

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

```bash
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"}'
```
