Home / VAT API / Spain

Spain VAT Validation API

Validate Spain NIF / CIF numbers via REST API. Backed by EU VIES (real-time) — returns registration status, company name, and address in a single call.

GET /api/v1/validate/ES/{vat_number} VIES-backed Sub-100ms cached Free plan available

Quick start

CURL

curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:3000/api/v1/validate/ES/ESA12345678

Single validation

Validate one Spain VAT number. Returns full company details for valid numbers.

const res = await fetch(
  'http://localhost:3000/api/v1/validate/ES/ESA12345678',
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const data = await res.json();
/*
{
  "valid": true,
  "status": "active",
  "company_name": "Example GmbH",
  "address": "Musterstraße 1, Spain",
  "country_code": "ES",
  "vat_number": "ESA12345678",
  "cached": false,
  "request_id": "req_01abc..."
}
*/

Response format

200 OK — valid number
{
  "valid": true,
  "status": "active",
  "company_name": "Example Spain Ltd",
  "address": "Musterstraße 1, Spain",
  "country_code": "ES",
  "vat_number": "ESA12345678",
  "cached": false,
  "request_id": "req_01abc..."
}
FieldTypeDescription
validbooleantrue if the number is registered and active
statusstring"active", "inactive", "not_found", or "invalid_format"
company_namestring | nullRegistered company name (where available from authority)
addressstring | nullRegistered address (where available from authority)
country_codestringISO 2-letter code — always "ES" for this endpoint
vat_numberstringThe VAT number as sent in the request
cachedbooleantrue if result served from cache (valid: 24h, invalid: 1h)
request_idstringUnique request ID for support and audit logs

Batch validation

Validate up to 25 numbers in a single POST request. Numbers are processed in parallel — ideal for onboarding flows and nightly reconciliation.

POST /api/v1/validate
curl -s -X POST http://localhost:3000/api/v1/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "numbers": [
      { "country": "ES", "vat": "ESA12345678" },
      { "country": "ES", "vat": "ESA12345679" }
    ]
  }'
Response array
[
  {
    "vat": "ESA12345678",
    "valid": true,
    "status": "active",
    "company_name": "Example Ltd",
    "country_code": "ES",
    "cached": false
  },
  {
    "vat": "ESA12345679",
    "valid": false,
    "status": "not_found",
    "country_code": "ES",
    "cached": false
  }
]

Error codes

HTTP statusMeaningAction
400Bad request — malformed VAT formatCheck the VAT format against the pattern below
401Missing or invalid API keyPass a valid Bearer token in the Authorization header
404Country not supportedCheck /vat-api for the full list of supported countries
422Validation failed — invalid formatThe number does not match the expected format
429Rate limit exceededBack off and retry after the Retry-After header value
503Upstream authority unavailableVIES/authority is temporarily down — retry with exponential backoff

Spain VAT format reference

PropertyValue
Country code (ISO)ES
Local nameNIF / CIF (Número de Identificación Fiscal / Código de Identificación Fiscal)
FormatES + letter/digit + 7 digits + letter/digit
Regex^ES[A-Z0-9][0-9]{7}[A-Z0-9]$
ExampleESA12345678
Standard rate21%
Validation sourceEU VIES (real-time)
VIES supportedYes

Spain has three VAT identifier types: CIF for companies (letter + 7 digits + letter), NIF for individuals (8 digits + letter), and NIE for foreign nationals (X/Y/Z + 7 digits + letter). All are validated through VIES as Spanish VAT numbers.

Frequently asked questions

What does the TaxID API return for a Spain VAT validation?

For a valid Spain VAT number the API returns: `valid: true`, `status: "active"`, plus `company_name` and `address` where available from EU VIES (real-time). For invalid numbers it returns `valid: false` with a reason code. All fields are documented in the API reference.

How fast is the Spain VAT validation API?

Cached results (valid numbers are cached 24h, invalid 1h) respond in under 10ms. Uncached requests that require a live lookup via EU VIES (real-time) typically complete in 100–400ms. The `cached` field in the response tells you whether the result came from cache.

What is the Spain VAT number format?

Spain VAT numbers (NIF / CIF (Número de Identificación Fiscal / Código de Identificación Fiscal)) follow the pattern: ES + letter/digit + 7 digits + letter/digit. A valid example is `ESA12345678`. The TaxID API validates the format locally before making any live request, so malformed numbers fail instantly without consuming your quota.

Can I validate multiple Spain VAT numbers in one request?

Yes. The batch endpoint (POST /api/v1/validate) accepts up to 25 VAT numbers in a single request, processed in parallel. This is ideal for bulk onboarding flows, nightly reconciliation jobs, or importing customer lists. Each item in the response array maps 1-to-1 with your input array.

Start validating Spain VAT numbers

Free plan — 100 validations/month. No credit card required.

Get free API key View API docs

Integrate with your stack:

StripeNode.jsPythonPHPAll integrations

More Spain resources:

Spain VAT validation toolSpain VAT rates

Validate VAT in other countries:

EstoniaGreeceFinlandFranceCroatiaAll countries