Home / Use cases / Custom

Validate Spanish NIF and CIF numbers

Validate Spanish tax identifiers (NIF/CIF/NIE) through the VIES system. Understand the different formats for companies, individuals, and foreign nationals in Spain.

Implementation steps

1. 1

   Identify NIF vs CIF vs NIE format

   Run the input through three sequential regex checks: /^[ABCDEFGHJNPQRSUVW][0-9]{7}[0-9A-J]$/ for legal-entity NIFs (CIF), /^[0-9]{8}[A-Z]$/ for individual DNI/NIF, and /^[XYZ][0-9]{7}[A-Z]$/ for NIE. Only legal-entity NIFs should trigger a VIES lookup; for DNI and NIE patterns, validate the checksum locally and store the identifier for invoice rendering without calling the external API.

2. 2

   Validate checksum locally before API call

   For legal-entity NIFs, compute the control character using the AEAT's algorithm: sum odd-position and even-position digits separately (with a conversion table for letters in even positions), derive the modulo-10 remainder, and look up the expected control character. For individual NIFs/DNIs, use the modulo-23 algorithm against the fixed letter sequence 'TRWAGMYFPDXBNJZSQVHLCKE'. Reject numbers that fail the local checksum with a specific error message before consuming an API call.

3. 3

   Query VIES for active registration

   Call GET /api/v1/validate/ES/:nif for legal-entity NIFs that pass local checksum validation. The ES country code instructs TaxID to query the AEAT's VIES node. Parse the response: status: 'active' confirms the entity is VIES-registered and eligible for reverse-charge; status: 'invalid' means the NIF is not in VIES (the entity may exist but not be VAT-registered for EU transactions); status: 'service_unavailable' means the AEAT node is temporarily unreachable.

4. 4

   Return AEAT-confirmed company details

   On a valid response, store the company_name and company_address from the TaxID response in your customer record. Spanish invoicing regulations (Real Decreto 1619/2012) require B2B invoices to include the buyer's NIF and registered name; using the AEAT-confirmed company_name from VIES eliminates discrepancies that arise when buyers provide a trade name instead of their registered legal entity name.

Code example

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