API Reference

The TaxID API validates EU VAT numbers against VIES. All endpoints return JSON. The base URL is https://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 an EU VAT number against the VIES system. Results for active numbers are cached for 24 hours; invalid numbers are cached for 1 hour.

Path parameters

Parameter	Type	Description
country	string	Two-letter EU country code (e.g. `DE`, `ES`, `FR`). Case-insensitive.
vat	string	VAT number with or without country prefix. Spaces and hyphens are stripped automatically.

Example request

curl

curl https://taxid.dev/api/v1/validate/DE/DE123456789 \
  -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",
  "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 EU country code
company_name	string \| null	Registered company name from VIES, or null if withheld
company_address	string \| null	Registered address from VIES, or null if withheld
request_date	string	ISO 8601 timestamp of the VIES response
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://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