ATverify
API referenceValidation

Validate up to 50 VAT numbers in one request

Validate up to 50 VAT numbers in a single request. Each item is normalized and routed to the correct registry (VIES/HMRC/BFS/BRREG) independently. Per-item successes and failures coexist in the 200 response under `data.results`. Cache hits do not count against your monthly quota.

Pass `requester_vat_number` to obtain a per-item `verify_id` (VIES consultation number) for each EU result — useful for tax-audit trails. Calls with a requester always bypass the cache.

Pro plan or Business plan required.

Try it live
playground
Body
vat_numbersrequiredstring[]

Array of VAT numbers to validate. Each can include spaces, dots, or mixed case — normalized automatically. Max 50 items per request. Each item is normalized and routed to the correct registry (VIES/HMRC/BFS/BRREG) independently.

1
2
3
3 / 50

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_numbersrequiredarray

Array of VAT numbers to validate. Each can include spaces, dots, or mixed case — normalized automatically. Max 50 items per request. Each item is normalized and routed to the correct registry (VIES/HMRC/BFS/BRREG) independently.

example IE6388047V,DE811569869,FR44732829320
requester_vat_numberstring · min 4

Your own VAT number. When provided, each VIES item is looked up via an authenticated consultation and the response includes a per-item `verify_id` — the official consultation identifier accepted by tax auditors as proof of verification. These calls always bypass the cache and count toward your quota. Not applicable for CH, LI, or NO registrations (those items will have `verify_id: null`).

example DE100000001
200

Response

Per-item results

datarequiredobject
data.summaryrequiredobject
data.summary.totalrequiredinteger

Total number of items in the request (`vat_numbers.length`).

example 3
data.summary.successfulrequiredinteger

Items that returned `ok: true` (the registry answered, regardless of valid/invalid outcome).

example 2
data.summary.failedrequiredinteger

Items that returned `ok: false` (normalization failed, country unsupported, or registry unavailable).

example 1
data.resultsrequiredarray<any>

Per-item results in the same order as the input `vat_numbers` array. `results.length === total`.

metarequiredobject
meta.request_idrequiredstring

UUID v7 identifying this specific HTTP request. Include it in any support ticket so we can trace the call in our logs.

example 0190f8ea-a5b2-7000-a123-000000000000
meta.latency_msrequiredinteger

Total server-side processing time in milliseconds, from request received to response sent.

example 694
meta.cachedrequiredboolean

Whether this response was served from the 30-day cache instead of a fresh registry fetch. Cached hits do not count toward your monthly quota.

example false
meta.sourcerequiredstring

Which official registry produced this result. `vies` for EU-27 + XI, `hmrc` for GB, `bfs` for CH/LI, `brreg` for NO.

one of"vies""hmrc""bfs""brreg""bzst"
meta.source_statusrequiredstring

Upstream data source reliability. `live` = confirmed fresh registry response. `cached` = served from the 30-day cache. `degraded` = result may be unreliable (reserved for future expansion).

one of"live""cached""degraded"

Error responses

400Invalid request body / empty array
401Missing or invalid API key
402Plan does not include batch (Free + Starter)
429Monthly quota insufficient for batch
import { Vatverify } from '@vatverify/node';
const client = new Vatverify();

const result = await client.validateBatch({
    "vat_numbers": [
      "IE6388047V",
      "DE811569869",
      "FR44732829320"
    ],
    "requester_vat_number": "DE100000001"
  });
{
  "data": {
    "summary": {
      "total": 3,
      "successful": 2,
      "failed": 1
    },
    "results": [
      null
    ]
  },
  "meta": {
    "request_id": "0190f8ea-a5b2-7000-a123-000000000000",
    "latency_ms": 694,
    "cached": false,
    "source": "vies",
    "source_status": "live"
  }
}

Per-day usage rollup for a key

Returns day-level rollups keyed by (day, endpoint, country, source) for one API key across a date range (≤ 90 days). Free plan returns 402.

Validate a VAT number

Validate a VAT number against the appropriate upstream service (VIES, HMRC, BFS, or BRREG) and return the validity status, company details, and VAT metadata for the country. Input is normalized automatically — spaces, dots, and casing are handled for you ("de 811.569.869" → "DE811569869"). Results are cached for 30 days. Cached responses include `meta.cached: true`; `data.verified_at` always reflects the original registry fetch time. Pass `cache=false` to bypass the cache and force a fresh lookup from the upstream service.