VAT API Documentation - VatDB | API Reference & Guides

Getting Started

Quick Start
Authentication

API Reference

Overview
Validate VAT
Check VAT
Normalize VAT
Get Audit
Error Handling

Quick Start

Get up and running with our VAT API in under 5 minutes. This guide will walk you through your first EU VAT validation.

1. Get your API Key

Create account

2. Authentication

Include your API key in the X-API-Key header of every request:

X-API-Key: YOUR_API_KEY_HERE

3. Make Your First Request

Validate a VAT number with a simple POST request:

curl -X POST https://api.vatdb.com/v1/vat/validate \
  -H "X-API-Key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"vat_number": "LU20260743"}'

API Endpoints

The VatDB API provides three core endpoints for working with EU VAT numbers:

POST /v1/vat/validate

Live validation against official datasources. Use this when you need to verify a VAT number is currently registered and active.

POST /v1/vat/check

Offline format and checksum validation. Validates the VAT number structure and checksum without actually checking if it is active or registered. Use this for quick non-critical use cases or when full validation is temporarily not available.

POST /v1/vat/normalize

Cleans and normalizes VAT number input. Removes spaces, dots, dashes and converts to uppercase. This is a formatting utility only: it performs no format checks, no checksum checks, and no VIES lookup. Use this to standardize user input before checking or validating.

Validate VAT Number

POST /v1/vat/validate

Validates a VAT number against the EU VIES database. Returns company_name and company_address when available.

Request Body

Parameter	Type	Description
`vat_number` required	string	The VAT number to validate (including country code)
`requester_vat_number` optional	string \| null	Your own VAT number. When provided, a consultation identifier that can serve as proof of validation is returned.

Request Example

{
  "vat_number": "LU20260743",
  "requester_vat_number": "DE123456789"
}

curl -X POST https://api.vatdb.com/v1/vat/validate \
  -H "X-API-Key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"vat_number": "LU20260743", "requester_vat_number": "DE123456789"}'

import requests

response = requests.post(
    "https://api.vatdb.com/v1/vat/validate",
    headers={"X-API-Key": "YOUR_API_KEY_HERE"},
    json={"vat_number": "LU20260743", "requester_vat_number": "DE123456789"}
)
print(response.json())

Response

{
  "valid": true,
  "format_valid": true,
  "vat_number": "LU20260743",
  "company_name": "AMAZON EUROPE CORE S.A R.L.",
  "company_address": "38, AVENUE JOHN F. KENNEDY\nL-1855  LUXEMBOURG",
  "consultation_number": "WAPIAAAAX5F2pGVa",
  "audit_id": "461c8210-5699-4093-9329-d23be3fc04f2"
}

Response Fields

Field	Type	Description
`valid`	boolean	Whether the VAT number is registered in VIES
`format_valid`	boolean	Whether the VAT number passes offline format/checksum rules
`vat_number`	string	Normalized VAT number including country code prefix
`company_name`	string \| null	Company name (if available)
`company_address`	string \| null	Company address (if available)
`consultation_number`	string \| null	Only present when `requester_vat_number` is provided. A unique consultation number that serves as proof of validation.
`audit_id`	string	Unique identifier for this API request. Use with `GET /v1/audits/{audit_id}` to retrieve the full request/response.

Check VAT Number

POST /v1/vat/check

Performs offline format and checksum validation. This does not query databases, it only validates the VAT number structure.

Request Body

Parameter	Type	Description
`vat_number` required	string	The VAT number to check (including country code)

Request Example

{
  "vat_number": "LU20260743"
}

curl -X POST https://api.vatdb.com/v1/vat/check \
  -H "X-API-Key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"vat_number": "LU20260743"}'

import requests

response = requests.post(
    "https://api.vatdb.com/v1/vat/check",
    headers={"X-API-Key": "YOUR_API_KEY_HERE"},
    json={"vat_number": "LU20260743"}
)
print(response.json())

Response

{
  "vat_number": "LU20260743",
  "format_valid": true,
  "audit_id": "01b07d60-4563-45d8-bbe1-7c6395979ed9"
}

Response Fields

Field	Type	Description
`vat_number`	string	Normalized VAT number including country code prefix
`format_valid`	boolean	Whether the VAT number passes offline format/checksum rules
`audit_id`	string	Unique identifier for this API request

Normalize VAT Number

POST /v1/vat/normalize

Normalizes a VAT number by removing spaces, dots, dashes, and converting to uppercase. This endpoint is a formatting utility only and performs no validation checks (including no checksum validation and no VIES lookup).

Request Body

Parameter	Type	Description
`vat_number` required	string	The VAT number to normalize

Request Example

{
  "vat_number": "LU 2026 0743"
}

curl -X POST https://api.vatdb.com/v1/vat/normalize \
  -H "X-API-Key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"vat_number": "LU 2026 0743"}'

import requests

response = requests.post(
    "https://api.vatdb.com/v1/vat/normalize",
    headers={"X-API-Key": "YOUR_API_KEY_HERE"},
    json={"vat_number": "LU 2026 0743"}
)
print(response.json())

Response

{
  "vat_number": "LU20260743",
  "audit_id": "1fbb9599-b40d-4ebe-bd58-50fb6b94bcfa"
}

Get Audit Record

GET /v1/audits/{audit_id}

Retrieve a previous API request by its audit ID. Every successful VAT API call returns an audit_id which can be used to retrieve the full request and response data. Audit record timestamps are generated by VatDB on the server and returned in UTC.

Path Parameters

Parameter	Type	Description
`audit_id` required	string	The audit ID returned from a previous VAT API call

Request Example

curl -X GET https://api.vatdb.com/v1/audits/d204420d-1c0a-4a43-923f-cf3491d36f5e \
  -H "X-API-Key: YOUR_API_KEY_HERE"

import requests

response = requests.get(
    "https://api.vatdb.com/v1/audits/d204420d-1c0a-4a43-923f-cf3491d36f5e",
    headers={"X-API-Key": "YOUR_API_KEY_HERE"}
)
print(response.json())

Response

{
  "id": "d204420d-1c0a-4a43-923f-cf3491d36f5e",
  "timestamp": "2024-01-15T10:30:00Z",
  "endpoint": "/v1/vat/validate",
  "request": {
    "vat_number": "LU20260743"
  },
  "response": {
    "valid": true,
    "format_valid": true,
    "vat_number": "LU20260743",
    "company_name": "AMAZON EUROPE CORE S.A R.L.",
    "company_address": "38, AVENUE JOHN F. KENNEDY...",
    "audit_id": "d204420d-1c0a-4a43-923f-cf3491d36f5e"
  }
}

Response Fields

Field	Type	Description
`id`	string	The unique audit identifier
`timestamp`	string	Server-generated ISO 8601 UTC timestamp (for example, with a `Z` suffix) for when VatDB recorded the request
`endpoint`	string	The API endpoint that was called
`request`	object	The original request body
`response`	object	The original response body

Error Handling

VatDB uses conventional HTTP response codes to indicate success or failure of an API request.

HTTP Status Codes

Code	Description
`200`	Success
`401`	API key not provided or not valid
`402`	Subscription or trial period expired
`403`	VAT number is blocked
`404`	Requested resource was not found (for example URL or audit record)
`405`	Request method not allowed for this URL
`422`	Invalid request or invalid requester VAT
`429`	Request limit exceeded
`500`	Internal server error
`503`	VAT validation service unavailable

Error Response

When an error occurs, the response includes a structured error object with code, message, and details.

{
  "error": {
    "code": "SOURCE_UNAVAILABLE",
    "message": "VAT validation service unavailable",
    "details": {}
  }
}

Error Codes

Error Code	Description
`VAT_BLOCKED`	The VAT number is blocked by VIES
`INVALID_REQUEST`	Invalid request format or missing fields
`MISSING_API_KEY`	API key header is missing
`INVALID_API_KEY`	API key is invalid
`INVALID_REQUESTER_VAT`	The requester VAT number is invalid
`REQUEST_LIMITED`	Request limit exceeded
`NOT_FOUND`	Requested resource was not found
`METHOD_NOT_ALLOWED`	Request method not allowed for this URL
`INTERNAL_SERVER_ERROR`	An unexpected error occurred
`SOURCE_UNAVAILABLE`	The VIES or country service is temporarily unavailable