Home / Use cases / Custom

Bulk VAT number validation via CSV import

Validate hundreds of EU VAT numbers in batch using parallel API requests. Ideal for CRM data cleansing, supplier audits, and initial data migrations.

Implementation steps

1. 1

   Parse CSV with VAT numbers

   Use a CSV library (csv-parse in Node.js, Python's built-in csv module, or League\Csv in PHP) to stream-parse the input file row by row rather than loading the entire file into memory. Extract the country_code and vat_number columns; if the CSV does not have separate columns, use a regex to split the two-letter country prefix from the numeric portion (e.g. /^([A-Z]{2})(.+)$/) before calling the API.

2. 2

   Validate in parallel (max 10 concurrent)

   Use a concurrency-limited executor: in Node.js, p-limit(10) wrapped around Promise.allSettled is idiomatic; in Python, asyncio.Semaphore(10) with asyncio.gather achieves the same effect. Limit to 10 concurrent requests to stay within API rate limits and to avoid overwhelming VIES member-state nodes, which are known to become unresponsive under high request volumes.

3. 3

   Collect results with rate limit awareness

   On each API response, inspect the HTTP status code: a 429 means you've exceeded the rate limit — back off exponentially (e.g. 1s, 2s, 4s) and retry the failed row. For status: 'service_unavailable' in the response body, log the row as 'pending' and add it to a retry queue rather than marking it as invalid, since the VIES node may recover within minutes. Store valid, invalid, and pending counts in a running summary to report at job completion.

4. 4

   Export enriched CSV with status + company name

   Write the output CSV with the original columns plus: vat_status (active/invalid/service_unavailable), company_name, company_address, request_id, and validated_at. Include request_id so downstream users can reference the specific TaxID lookup that produced the result — this is valuable for audit purposes when a customer disputes their validation outcome.

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