Home / Use cases / Python

EU VAT validation in Python / Django

Validate EU VAT numbers in Python applications using the TaxID REST API. Works with Django, FastAPI, Flask, and any HTTP-capable Python code.

Implementation steps

1. 1

   Use requests or httpx library

   Install requests for synchronous Django/Flask apps or httpx for async FastAPI applications. Call GET https://api.taxid.pro/v1/validate/{country}/{vat} with headers={'Authorization': f'Bearer {settings.TAXID_API_KEY}'} and set a timeout of 10 seconds to prevent VIES latency from blocking your request threads indefinitely.

2. 2

   Create VATValidator class

   Encapsulate the API call in a VATValidator class with a validate(country, vat_number) method that returns a typed dataclass or Pydantic BaseModel mirroring the response schema: valid (bool), status (Literal['active','invalid','service_unavailable']), company_name (str | None), company_address (str | None), cached (bool), request_id (str). This decouples your business logic from the HTTP transport layer.

3. 3

   Handle service_unavailable gracefully

   In your validator, raise a VIESUnavailableError (subclassing Exception) when status == 'service_unavailable'. Catch this in Django views with a try/except block and return a 503 response or a form error telling the user to retry. In Celery tasks, use self.retry(exc=exc, countdown=300) to schedule a re-attempt; this prevents indefinite pending states while respecting VIES recovery windows.

4. 4

   Store results in Django model

   Create a VATValidation model with fields: customer (FK), country_code (CharField), vat_number (CharField), status (CharField with choices), company_name (CharField nullable), request_id (UUIDField), validated_at (DateTimeField auto_now_add). Query this table first before calling the API to serve cached results, and invalidate cached records older than 24 hours for active numbers and 1 hour for invalid ones.

Code example

const res = await fetch(
  'http://localhost:3000/api/v1/validate/DE/DE123456789',
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const { valid, status, company_name, company_address } = await res.json();

if (valid) {
  console.log(`Valid EU business: ${company_name}`);
} else if (status === 'service_unavailable') {
  // VIES is temporarily down — retry or allow with manual check
  console.log('VIES unavailable — check back in a few minutes');
} else {
  console.log('Invalid VAT number — charge local tax rate');
}

import requests

res = requests.get(
    "http://localhost:3000/api/v1/validate/DE/DE123456789",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = res.json()

if data["valid"]:
    print(f"Valid: {data['company_name']}")
elif data["status"] == "service_unavailable":
    print("VIES temporarily unavailable")
else:
    print("Invalid VAT number")

API response

The TaxID API returns a consistent JSON response for every validation request:

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

Error handling

The API uses a consistent Stripe-style error format. Always handle service_unavailable separately — VIES has occasional downtime and you should not reject valid customers during outages.

Related use cases