ATverify
API referenceConfirmations

BZSt §18e qualified VAT confirmation (German legal evidence)

Issues a qualified Bestätigungsmitteilung from the German Bundeszentralamt für Steuern (BZSt) confirming a foreign EU VAT and, field-by-field, whether the supplied company details match what the foreign registry has on file. The result is stored for 10 years as tax-audit evidence under §18e UStG. Business plan only. Supports `Idempotency-Key` header (UUID) for safe retries within 24 hours.

Try it live
playground
Body

30 requests per hour per IP · demo key used automatically

Auth
Requires the Authorization: Bearer <api_key> header. Use a vtv_live_* key in production or a vtv_test_* key for deterministic magic-number responses.

Body

vat_numberrequiredstring · min 3

Foreign EU VAT number to confirm. Country prefix required.

example FR44732829320
companyrequiredobject

Company details to verify against the foreign registry. `name` is required; the rest are optional but recommended — only fields you supply are matched.

example [object Object]
requester_vat_numberstring

German VAT number authorising the confirmation. Overrides the per-key `default_requester_vat`. Must pass DE MOD-11 checksum.

example DE129273398
200

Response

Confirmation issued and stored as evidence

datarequiredobject
data.validrequiredboolean
data.qualifiedrequiredboolean

`true` only when every requested field returned A. `valid && !qualified` means BZSt returned evatr-0003 — VAT is valid, but at least one field did not match or was not returned.

data.vat_numberrequiredstring
data.requester_vat_numberrequiredstring
data.matchesrequiredobject
data.matches.namerequiredstring

A = matches, B = does not match, C = not requested (you did not supply this field), D = not provided by the foreign registry.

one of"A""B""C""D"
data.matches.streetrequiredstring

A = matches, B = does not match, C = not requested (you did not supply this field), D = not provided by the foreign registry.

one of"A""B""C""D"
data.matches.postcoderequiredstring

A = matches, B = does not match, C = not requested (you did not supply this field), D = not provided by the foreign registry.

one of"A""B""C""D"
data.matches.townrequiredstring

A = matches, B = does not match, C = not requested (you did not supply this field), D = not provided by the foreign registry.

one of"A""B""C""D"
data.companyrequiredobject
data.company.namerequiredstring | null
data.company.streetrequiredstring | null
data.company.postcoderequiredstring | null
data.company.townrequiredstring | null
data.valid_fromrequiredstring | null
data.valid_torequiredstring | null
data.confirmation_idrequiredstring

Retrievable later via `GET /v1/confirmations/{id}`. Retained 10 years.

data.confirmed_atrequiredstring
metarequiredobject
meta.sourcerequiredstring
one of"bzst"
meta.source_statusrequiredstring
one of"live"
meta.latency_msrequiredinteger
meta.request_idrequiredstring
meta.bzst_status_coderequiredstring
example evatr-0000
meta.bzst_idrequiredstring | null

BZSt's own request identifier (the `id` field of the qualified-confirmation response). Independent evidence of the upstream call alongside `request_id` and the `data.confirmation_id` UUID. Null if BZSt omitted it on this response.

example 08aba84d66448118

Error responses

400Bad request, invalid format, or BZSt rejected with a caller-fixable code
401Missing or invalid API key
402Business plan required
422Requester VAT not authorised by BZSt (evatr-0004)
429Rate limited (local burst or BZSt session limit evatr-0008)
502Network failure to BZSt
503BZSt unavailable (evatr-0011 or evatr-0013)
import { Vatverify } from '@vatverify/node';
const client = new Vatverify();

const result = await client.confirm({
    "vat_number": "FR44732829320",
    "company": {
      "name": "Airbus SAS",
      "street": "2 Rond-Point Emile Dewoitine",
      "postcode": "31700",
      "town": "Blagnac"
    },
    "requester_vat_number": "DE129273398"
  });
{
  "data": {
    "valid": true,
    "qualified": true,
    "vat_number": "…",
    "requester_vat_number": "…",
    "matches": {
      "name": "A",
      "street": "A",
      "postcode": "A",
      "town": "A"
    },
    "company": {
      "name": "…",
      "street": "…",
      "postcode": "…",
      "town": "…"
    },
    "valid_from": "…",
    "valid_to": "…",
    "confirmation_id": "9b8e1a2c-4d6f-4e0b-9b2a-1c3d5e7f9a2b",
    "confirmed_at": "…"
  },
  "meta": {
    "source": "bzst",
    "source_status": "live",
    "latency_ms": 47,
    "request_id": "9b8e1a2c-4d6f-4e0b-9b2a-1c3d5e7f9a2b",
    "bzst_status_code": "evatr-0000",
    "bzst_id": "08aba84d66448118"
  }
}

List recent audit records for the calling key

Returns the most recent audit records for the calling API key, newest first. Filterable by endpoint and date range. Cursor pagination via `meta.next_cursor` (pass it as `cursor=` on the next call).

Fetch a stored §18e confirmation by id

Returns a previously issued qualified confirmation. Scoped to the calling api_key — the same key that created the confirmation. Readable regardless of current plan (evidence retention is a contractual promise, not a plan feature).