Home / Use cases / Custom

Validate German USt-IdNr. (DE VAT numbers)

Specifically validate German Umsatzsteuer-Identifikationsnummern (USt-IdNr.) via VIES. Understand the difference between the local Steuernummer and the EU VAT number.

Implementation steps

1. 1

   Accept DE prefix with 9 digits

   Validate the format client-side with the regex /^DE[0-9]{9}$/ before calling the API. If the input matches a Steuernummer pattern (/^[0-9]{10,13}$/ without a country prefix), surface a specific message explaining the difference: 'This looks like a Steuernummer. Please enter your EU USt-IdNr. starting with DE.' This prevents unnecessary API calls for a format that VIES will always reject.

2. 2

   Validate format before VIES call

   Strip whitespace and slashes from the input, then call GET /api/v1/validate/DE/:vatNumber. The API will forward the request to the German BZSt node in VIES; response times for German lookups are typically 200–800 ms, so set a client-side timeout of at least 5 seconds and show a loading indicator to prevent users from submitting the form before the response arrives.

3. 3

   Handle German Tax Agency response times

   The BZSt VIES node is one of the more reliable EU nodes but can return service_unavailable during system maintenance windows (typically early morning CET). When this occurs, do not block the user's checkout or form submission; instead, persist a vat_pending_validation flag on the record and queue a background re-validation job that retries every 15 minutes for up to 4 hours before escalating to manual review.

4. 4

   Return company name and address if available

   The TaxID API returns company_name and company_address from the VIES response for German numbers when the BZSt node provides them. Display the company_name on screen as a confirmation step — for high-value B2B transactions, prompt the buyer to confirm 'Is this your company: [company_name]?' before proceeding. Store both fields alongside the order for your accounts-receivable team and for inclusion on reverse-charge invoices.

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