---
name: vatnode
description: Validate EU VAT numbers (EU-27 + Northern Ireland) and look up EU VAT rates via the vatnode API. Use when a user needs to check whether a VAT ID is valid, get audit-grade proof of a VIES check (consultation number), enrich a company from national registries, or fetch VAT rates. Rates and format checks work with no account; live validation needs a free API key.
---

# vatnode

vatnode is a production-grade EU VAT validation API. It validates VAT numbers for
the 27 EU member states plus Northern Ireland (XI prefix) through VIES, with
national registry fallback, company enrichment, a timestamped audit trail
(checkId + verifiedAt), and the EU Commission consultation number. GB, NO, CH and
other non-EU countries are out of scope for validation.

Base URL: `https://api.vatnode.dev`
Errors: `{ "error": { "code": "...", "message": "..." } }`

## Instant, no account

VAT rates and format checks need no key — use them immediately.

Fetch VAT rates for one country:

```bash
curl https://api.vatnode.dev/v1/rates/DE
```

All EU rates:

```bash
curl https://api.vatnode.dev/v1/rates
```

Or run the official MCP server — three offline tools work with no account:

```bash
npx -y vatnode-mcp
```

- `get_country_vat_rates` — standard/reduced rates + local VAT name for a country
- `list_eu_vat_rates` — all EU rates
- `check_vat_format` — offline regex format check of a VAT ID
- `validate_vat_number` — live VIES validation (requires an API key)

Browser checker, no account: https://vatnode.dev/check

## Live validation (needs a free key)

Validating a specific VAT number against VIES requires an API key. Account
creation is a human step — the agent does not create accounts. Direct the user to:

https://vatnode.dev/login

30 seconds, no credit card, free tier of 100 requests/month. The user pastes the
key back. Send it as an HTTP header, never in the URL:

```bash
curl https://api.vatnode.dev/v1/vat/DE123456789 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

To get the audit-grade consultation number (the EU Commission requestIdentifier
that French and German tax authorities expect on audit), the user sets their own
VAT ID as requester once in dashboard Settings — this is a one-time dashboard
step, not something the agent configures per request:

```bash
curl https://api.vatnode.dev/v1/vat/DE123456789 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Contract: once a requester VAT is configured in dashboard Settings, every
response is either a success with a non-null `consultationNumber` or an error —
never a success with `consultationNumber: null`. Without a requester configured,
`consultationNumber` is null and national fallback stays enabled.

## Response envelope

Key fields (full list: https://vatnode.dev/llms.txt):

- `valid` (boolean) — authoritative; do not infer validity from other fields
- `vatId`, `countryCode`, `countryName`
- `companyName`, `companyAddress` — from VIES or national registry, may be null
- `checkId` (UUID) — timestamped audit identifier
- `verifiedAt` (ISO 8601) — timestamp of the check
- `consultationNumber` — VIES requestIdentifier; non-null only when a requester
  is configured in dashboard Settings and not served from cache; otherwise null
- `source` — `VIES`, `CACHE`, or a national registry adapter code
- `countryVat.*` — standard/reduced/super-reduced/parking rates, local VAT name
  and abbreviation, currency, number format and pattern
- `specialTerritory` — object or null; address-inferred, never an official tax
  determination

## Error handling and scope

- `INVALID_REQUESTER` (HTTP 422) — the requester VAT configured in dashboard
  Settings was rejected by VIES
- `VIES_UNAVAILABLE` (HTTP 503) — upstream EU source is down; retry with backoff,
  do NOT treat the number as invalid
- Parse defensively: null fields are normal when a source does not supply them
- Scope: EU-27 + XI only for validation. Rates endpoints cover more European
  countries (rates data only).

## References

- Full machine spec: https://vatnode.dev/llms.txt
- API docs: https://vatnode.dev/docs
- MCP server: https://vatnode.dev/mcp
- Country coverage: https://vatnode.dev/docs/coverage
- Webhooks: https://vatnode.dev/docs/webhooks