API referenceConfirmations

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).

Try it live

playground

Path

idrequiredstring

The playground demo key has its own tenant. Expect 404 unless the id belongs to the demo account.

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.

Path parameters

idrequiredstring

200

Response

Confirmation record

datarequiredobject

data.idrequiredstring

data.request_idrequiredstring

data.requester_vatrequiredstring

data.queried_vatrequiredstring

data.bzst_status_coderequiredstring

data.bzst_idrequiredstring | null

data.validrequiredboolean

data.qualifiedrequiredboolean

data.matchesrequiredobject

data.matches.namerequiredstring | null

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 | null

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 | null

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 | null

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.resultrequiredobject

data.result.namerequiredstring | null

data.result.streetrequiredstring | null

data.result.postcoderequiredstring | null

data.result.townrequiredstring | null

data.valid_fromrequiredstring | null

data.valid_torequiredstring | null

data.created_atrequiredstring

metarequiredobject

meta.request_idrequiredstring

Error responses

401Missing or invalid API key

404Confirmation not found or belongs to a different key

import { Vatverify } from '@vatverify/node';
const client = new Vatverify();

const result = await client.getConfirmation();

{
  "data": {
    "id": "9b8e1a2c-4d6f-4e0b-9b2a-1c3d5e7f9a2b",
    "request_id": "9b8e1a2c-4d6f-4e0b-9b2a-1c3d5e7f9a2b",
    "requester_vat": "…",
    "queried_vat": "…",
    "bzst_status_code": "…",
    "bzst_id": "…",
    "valid": true,
    "qualified": true,
    "matches": {
      "name": "A",
      "street": "A",
      "postcode": "A",
      "town": "A"
    },
    "result": {
      "name": "…",
      "street": "…",
      "postcode": "…",
      "town": "…"
    },
    "valid_from": "…",
    "valid_to": "…",
    "created_at": "…"
  },
  "meta": {
    "request_id": "9b8e1a2c-4d6f-4e0b-9b2a-1c3d5e7f9a2b",
    "latency_ms": 47
  }
}

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.

Liveness probe

Returns { ok: true } when the server is up. No authentication required.