API Reference

The TaxID API validates EU VAT numbers against VIES. All endpoints return JSON. The base URL is https://www.taxid.dev/api/v1.

Authentication

All requests to /validate require an API key passed as a Bearer token in the Authorization header. Get your key from the dashboard.

Authorization header

Authorization: Bearer vat_xxxxxxxxxxxxxxxxxxxx

GET/api/v1/validate/{country}/{vat}

Validates a VAT or tax ID number against the official authority for that country. EU numbers (DE, FR, ES…) are validated via VIES. UK numbers (GB) are validated via HMRC. Results for active numbers are cached for 24 hours; invalid numbers for 1 hour.

Path parameters

Parameter	Type	Description
country	string	Two-letter country code. EU member states (e.g. `DE`, `ES`, `FR`) plus `GB` (United Kingdom, via HMRC) and `CH` (Switzerland, via BFS UID register) and `NO` (Norway, via Brønnøysundregistrene) and `AU` (Australia, via ABR — requires `ABR_GUID`). Case-insensitive.
vat	string	VAT number with or without country prefix. Spaces and hyphens are stripped automatically.

Example requests

curl — EU (VIES)

curl https://www.taxid.dev/api/v1/validate/DE/DE123456789 \
  -H "Authorization: Bearer vat_xxxxxxxxxxxxxxxxxxxx"

curl — United Kingdom (HMRC)

curl https://www.taxid.dev/api/v1/validate/GB/GB123456782 \
  -H "Authorization: Bearer vat_xxxxxxxxxxxxxxxxxxxx"

curl — Switzerland (BFS UID)

curl https://www.taxid.dev/api/v1/validate/CH/CHE-109.322.551 \
  -H "Authorization: Bearer vat_xxxxxxxxxxxxxxxxxxxx"

curl — Norway (Brønnøysundregistrene)

curl https://www.taxid.dev/api/v1/validate/NO/923609016 \
  -H "Authorization: Bearer vat_xxxxxxxxxxxxxxxxxxxx"

curl — Australia (ABR)

curl https://www.taxid.dev/api/v1/validate/AU/48123123124 \
  -H "Authorization: Bearer vat_xxxxxxxxxxxxxxxxxxxx"

Response

200 OKactive

{
  "valid": true,
  "status": "active",
  "vat_number": "123456789",
  "country_code": "DE",
  "company_name": "Example GmbH",
  "company_address": "Musterstraße 1, 10115 Berlin",
  "request_date": "2026-05-11T10:00:00.000Z",
  "source": "VIES",
  "cached": false,
  "request_id": "req_01j9x..."
}

Response fields

Field	Type	Description
valid	boolean	true if the VAT number is active and registered
status	string	active \| invalid \| service_unavailable
vat_number	string	The VAT number without country prefix
country_code	string	Two-letter country code
company_name	string \| null	Registered company name, or null if withheld by the authority
company_address	string \| null	Registered address, or null if withheld by the authority
request_date	string	ISO 8601 timestamp of the authority response
source	string	Authority: VIES (EU), HMRC (GB), BFS (CH), Brønnøysundregistrene (NO), or ABR (AU)
vat_registered	boolean?	CH/NO/AU: whether the company is registered for VAT (MWST/MVA/GST). Absent for EU and GB.
cached	boolean	true if the response was served from cache
request_id	string	Unique request identifier for support

Error handling

Always handle service_unavailable separately. VIES has occasional downtime — do not reject a valid customer because VIES is temporarily unreachable.

active

VAT is valid and the business is registered in VIES

invalid

VAT format is wrong or the number is not registered

service_unavailable

VIES or the national tax authority is temporarily down — retry later

HTTP error codes

HTTP status	Error code	Meaning
401	unauthorized	Missing or invalid API key
429	rate_limit_exceeded	Monthly quota exhausted — upgrade your plan
400	invalid_country	Country code is not a valid EU member state
400	invalid_request	Malformed request
503	service_unavailable	VIES is temporarily unreachable

GET/api/v1/rates/{country}No auth required

Returns the current VAT rates for an EU country. Publicly accessible — no API key needed. Responses are cached for 24 hours.

curl

curl https://www.taxid.dev/api/v1/rates/DE

200 OK

{
  "country_code": "DE",
  "country_name": "Germany",
  "currency": "EUR",
  "standard_rate": 19,
  "reduced_rates": [7],
  "super_reduced_rate": null
}

GET/api/v1/healthNo auth required

Returns the current health status of the API and its dependencies.

200 OK

{ "status": "ok" }

Code examples

Node.js

const res = await fetch(
  'https://taxid.dev/api/v1/validate/DE/DE123456789',
  { headers: { 'Authorization': 'Bearer vat_xxxx' } }
);
const { valid, status, company_name } = await res.json();

if (valid) {
  console.log('Valid EU business:', company_name);
} else if (status === 'service_unavailable') {
  // VIES is down — do not hard-fail the user
} else {
  console.log('Invalid VAT number');
}

Python

import requests

res = requests.get(
    "https://taxid.dev/api/v1/validate/DE/DE123456789",
    headers={"Authorization": "Bearer vat_xxxx"},
)
data = res.json()

if data["valid"]:
    print("Valid:", data["company_name"])
elif data["status"] == "service_unavailable":
    pass  # VIES is down — do not hard-fail
else:
    print("Invalid VAT number")

PHP

$ch = curl_init('https://taxid.dev/api/v1/validate/DE/DE123456789');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer vat_xxxx']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($data['valid']) {
    echo "Valid: " . $data['company_name'];
} elseif ($data['status'] === 'service_unavailable') {
    // VIES is down — do not hard-fail
} else {
    echo "Invalid VAT number";
}

Rate limits

Limits are enforced per calendar month. When you exceed your plan limit, the API returns a 429 rate_limit_exceeded error.

Plan	Validations/month
Free	100
Starter	1,000
Growth	10,000
Business	100,000
Scale	1,000,000

Ready to integrate?

Get your free API key and start validating EU VAT numbers today.

Get free API key