Skip to main content
POST
Validate a tax id

Autorizaciones

Authorization
string
header
requerido

API key sent as a bearer token in the Authorization header.

Cuerpo

application/json

The tax id and registered name to validate.

The tax id to validate against the census.

tax_id
string
requerido

The tax identifier to validate: a Spanish NIF/CIF/NIE or an EU VAT number. Whitespace and separators are tolerated.

Required string length: 1 - 64
Ejemplo:

"B12345678"

name
string
requerido

Name the id should be registered under. Spanish NIFs are checked against the AEAT census together with this name; VIES checks the number only.

Required string length: 1 - 200
Ejemplo:

"ACME, S.L."

country
string

ISO 3166-1 alpha-2 hint for ambiguous formats. Usually omitted: the country is detected from the id itself.

Required string length: 2
Ejemplo:

"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.

valid
boolean
requerido

Whether the id passed validation. Only trust it when definitive is also true.

Ejemplo:

true

definitive
boolean
requerido

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.

Ejemplo:

true

normalized_tax_id
string
requerido

The id after normalization (whitespace and separators removed, uppercased). Use this form when creating invoices.

Ejemplo:

"B12345678"

tax_id_type
string | null
requerido

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.

Ejemplo:

"es_nif"

tax_id_country
string | null
requerido

ISO 3166-1 alpha-2 country the id belongs to, or null when unclassified.

Ejemplo:

"ES"

error_code
string | null
requerido

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.

Ejemplo:

"not_registered_or_name_mismatch"

error_message
string | null
requerido

Human-readable English reason when valid is false, for your logs and support tooling. Derived from error_code. Null on success.

Ejemplo:

null

end_user_message
string | null
requerido

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.

Ejemplo:

null