Validate a tax id
Checks a Spanish NIF/CIF/NIE against the AEAT census (id and name together) or an EU VAT number against VIES, exactly as invoice creation does just-in-time. Use it in checkout or onboarding forms to catch bad recipient data before issuing. Validation failures are outcomes, not errors: the endpoint answers 200 with valid: false. Rate limited per API key.
Autorizaciones
API key sent as a bearer token in the Authorization header.
Cuerpo
The tax id and registered name to validate.
The tax id to validate against the census.
The tax identifier to validate: a Spanish NIF/CIF/NIE or an EU VAT number. Whitespace and separators are tolerated.
1 - 64"B12345678"
Name the id should be registered under. Spanish NIFs are checked against the AEAT census together with this name; VIES checks the number only.
1 - 200"ACME, S.L."
ISO 3166-1 alpha-2 hint for ambiguous formats. Usually omitted: the country is detected from the id itself.
2"ES"
Respuesta
The validation outcome.
Outcome of a census validation. Validation failures are outcomes, not errors: the endpoint answers 200 with valid: false rather than a 4xx.
Whether the id passed validation. Only trust it when definitive is also true.
true
Whether the answer is final. False means the id could not be conclusively checked (unrecognized format, or the census service is temporarily unavailable) — treat it as "unknown", not as invalid.
true
The id after normalization (whitespace and separators removed, uppercased). Use this form when creating invoices.
"B12345678"
The kind the id was classified as, or null when the format was not recognized. This is an extensible enum: new values may be added in the future, so clients must tolerate values not listed here. Known values: es_nif, eu_vat.
"es_nif"
ISO 3166-1 alpha-2 country the id belongs to, or null when unclassified.
"ES"
Stable, machine-readable reason validation failed, or null on success. Branch on this instead of parsing prose. This is an extensible enum: new values may be added in the future, so clients must tolerate values not listed here. Known values: unrecognized_format, invalid_format, not_registered_or_name_mismatch, vies_invalid, census_unavailable.
"not_registered_or_name_mismatch"
Human-readable English reason when valid is false, for your logs and support tooling. Derived from error_code. Null on success.
null
Reason safe to show the end user (a shopper at checkout), in Spanish today. Null on success. Its language may become request-controlled in future without this field being renamed.
null