Documentation
Browse documentation

Tax IDs

Structured fiscal identifiers and their registry-verification status.
View as Markdown

A tax ID combines an issuing country, a normalized identifier type and its value. Tax IDs are created only as part of an account or customer. They receive their own stable ID and can be retrieved separately, but cannot be created, updated or deleted directly through the API.

Replacing a customer's nested tax ID creates a new Tax ID resource and deletes the previous one. Previously issued invoices retain their immutable snapshot.

The Tax ID object

Properties
id string
Opaque identifier for a Tax ID.
object string
String identifying this as a Tax ID object. Always tax_id.
live boolean
True when the object belongs to the live environment; false for test data.
country string
ISO 3166-1 alpha-2 country associated with the tax ID. It must be compatible with the selected tax ID type.
type enum
FiscalRail's normalized fiscal identifier type.
Possible values
es_nif A Spanish NIF, including DNI and NIE identifiers for individuals and NIF identifiers for legal entities.
eu_vat A VAT identifier issued by an EU member state and checked for intra-EU registration.
local A domestic fiscal identifier that FiscalRail validates locally without querying a registry.
value string
The normalized fiscal identifier value.
owner object
The account or customer that owns the Tax ID.
Show child propertiesHide child properties
type enum
The kind of resource that owns the Tax ID.
Possible values
account The FiscalRail account whose legal entity uses this Tax ID.
customer The customer associated with this Tax ID.
id string
Account or customer ID, according to type.
verification object or null
The latest registry verification, or null when verification is unavailable.
Show child propertiesHide child properties
status enum
The current state of the latest registry-verification attempt.
Possible values
pending The registry check is queued, running or waiting to be retried.
completed The registry returned a result; inspect valid for the outcome.
failed FiscalRail could not complete the registry query; this is not evidence that the Tax ID is invalid.
valid boolean or null
The registry result, or null while pending or when verification failed.
completed_at string or null
When the verification attempt completed or failed, or null while it is pending.
Tax ID object 
{
  "id": "tax_id_14Vxtqg6oXpAY5WdWoq4wW",
  "object": "tax_id",
  "live": true,
  "country": "ES",
  "type": "es_nif",
  "value": "B87654323",
  "owner": {
    "type": "customer",
    "id": "cus_14Vxtqg6oXpAY5WdWoq4wW"
  },
  "verification": {
    "status": "completed",
    "valid": true,
    "completed_at": "2026-08-09T10:24:00Z"
  }
}

Tax ID types

The country is the jurisdiction that issued the identifier; it does not have to match the owner's address country. Selecting a country restricts the available types.

Type Allowed countries Local validation Registry verification
es_nif ES DNI, NIE and entity-prefix/control-character rules Automatically checked against the AEAT census
eu_vat EU member states Country prefix and basic format; Spanish values also validate the underlying NIF Automatically checked against VIES
local Any country Basic identifier format Not available

For Greece, send country: "GR" while the VAT value begins with EL. A structurally valid EU VAT number is not necessarily registered for intra-EU trade.

Spanish VERI*FACTU records project eu_vat as NIF-IVA (IDType=02) and local as an official identifier issued by the customer's country (IDType=04). Passport, residence-certificate and other-evidence identifiers are not accepted until FiscalRail exposes those types explicitly.

Tax ID verification

FiscalRail starts registry verification automatically when an es_nif or eu_vat Tax ID is created. The check runs asynchronously against the AEAT census for es_nif and VIES for eu_vat. Local Tax IDs are not checked against a registry.

The verification starts as pending and finishes as completed or failed, as described in the verification.status property above. A completed verification has a boolean valid result. For AEAT, valid: false includes identifiers that are missing, inactive, revoked or do not match the owner's name. Transport failures are retried five times with polynomial backoff before the verification becomes failed.

Verification emits the following events:

tax_id.verification.completed

Emitted when a registry check finishes with either a valid or invalid result.

tax_id.verification.failed

Emitted when FiscalRail cannot complete the registry query.

Verification requirements depend on the account's tax regime. In regimes that require a valid Tax ID, a completed verification with valid: false can prevent invoice issuance. A failed result means the registry check did not complete; it is not evidence that the Tax ID is invalid.

Retrieve a Tax ID

GET/v1/tax_ids/{id}

Returns a Tax ID by its opaque ID, including its owner and latest registry-verification status.

Path parameters
id string required
The opaque ID of the Tax ID to retrieve.
Responses

200 A Tax ID object. JSON

Example request
curl --request GET \
  'https://api.fiscalrail.com/v1/tax_ids/example' \
  --header "Authorization: Bearer ak_test_..."
Example response — 200 
{
  "id": "tax_id_14Vxtqg6oXpAY5WdWoq4wW",
  "object": "tax_id",
  "live": true,
  "country": "ES",
  "type": "es_nif",
  "value": "B87654323",
  "owner": {
    "type": "customer",
    "id": "cus_14Vxtqg6oXpAY5WdWoq4wW"
  },
  "verification": {
    "status": "completed",
    "valid": true,
    "completed_at": "2026-08-09T10:24:00Z"
  }
}