Home / Use cases / Custom

Validate Italian Partita IVA

Validate Italian Partita IVA numbers for B2B transactions. Includes local checksum validation (Luhn algorithm) and VIES lookup for active registration status.

Implementation steps

1. 1

   Validate 11-digit IT format

   Strip the IT prefix and any spaces, then confirm the remainder is exactly 11 numeric digits using /^[0-9]{11}$/. Additionally, check that digits 8–10 (the province code, 0-indexed) form a value between 001 and 100 inclusive or match the special codes 120, 121, or 999; province codes outside this range indicate a malformed number that should be rejected before the checksum step.

2. 2

   Run Luhn checksum locally

   Implement the Italian VAT Luhn variant: iterate over the first 10 digits; for odd positions (1,3,5,7,9, 1-indexed), add the digit directly; for even positions (2,4,6,8,10), double it and subtract 9 if the result is ≥ 10; sum all values and compute (10 - (sum mod 10)) mod 10; compare to digit 11. Reject numbers where the check digit does not match before calling GET /api/v1/validate/IT/:vatNumber, as this eliminates a significant proportion of typo-induced invalid API calls.

3. 3

   Query VIES for active status

   After passing local format and checksum checks, call GET /api/v1/validate/IT/:vatNumber. The TaxID API queries the Agenzia delle Entrate's VIES node. A status: 'active' response confirms the Partita IVA is registered for EU intra-community transactions and that reverse-charge treatment under Article 196 of the VAT Directive applies. A status: 'invalid' means the number exists in Italian records but is not currently active in VIES — the business may be newly registered, suspended, or operating only domestically.

4. 4

   Handle Agenzia delle Entrate response

   The Italian VIES node frequently returns a valid status without accompanying company_name or company_address data. Handle null values gracefully: display 'Partita IVA verified' with the validated number when company_name is null, rather than showing a blank confirmation. For invoicing, source the legal company name from an alternative Italian business register API (e.g. Registro delle Imprese via Infocamere) if required for invoice compliance under DPR 633/1972.

Code example

const res = await fetch(
  'http://localhost:3000/api/v1/validate/DE/IT12345678901',
  { 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/IT12345678901",
    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