# Tax IDs

Structured fiscal identifiers and their registry-verification status.

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`

Type: `string`

Opaque identifier for a Tax ID.

#### `object`

Type: `string`

String identifying this as a Tax ID object. Always `tax_id`.

#### `live`

Type: `boolean`

True when the object belongs to the live environment; false for test data.

#### `country`

Type: `string`

ISO 3166-1 alpha-2 country associated with the tax ID. It must be compatible with the selected tax ID type.

#### `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`

Type: `string`

The normalized fiscal identifier value.

#### `owner`

Type: `object`

The account or customer that owns the Tax ID.

##### `owner.type`

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.

##### `owner.id`

Type: `string`

Account or customer ID, according to `type`.


#### `verification`

Type: `object or null`

The latest registry verification, or null when verification is unavailable.

##### `verification.status`

Type: `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.

##### `verification.valid`

Type: `boolean or null`

The registry result, or null while pending or when verification failed.

##### `verification.completed_at`

Type: `string or null`

When the verification attempt completed or failed, or null while it is pending.



### Example

```json
{
  "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`

Type: `string` — required

The opaque ID of the Tax ID to retrieve.


### Responses

- `200` — [A Tax ID object.](#the-tax-id-object) Formats: JSON.

### Example request

```bash
curl --request GET \
  'https://api.fiscalrail.com/v1/tax_ids/example' \
  --header "Authorization: Bearer ak_test_..."
```

### Example response — 200

```json
{
  "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"
  }
}
```