Testing
Every Live account has an isolated Test account with separate API keys, resources and events. Test accepts the same requests as Live, but it does not contact external tax authorities. Use the values below to make asynchronous results deterministic without adding test-only parameters to your integration.
Test values have special behavior only in a Test account. Do not use them in Live: FiscalRail treats them as ordinary identifiers there and external registries may reject them.
Test Tax IDs
Tax IDs have two distinct failure points:
| What you send | API result | Tax ID verification | Event |
|---|---|---|---|
| Invalid local format | Customer request returns 422 invalid_customer |
No Tax ID or verification is created | None |
| Valid format and valid registry sentinel | Customer request returns 201 |
Moves from pending to completed with valid: true |
tax_id.verification.completed |
| Valid format and invalid registry sentinel | Customer request returns 201 |
Moves from pending to completed with valid: false |
tax_id.verification.completed |
An invalid registry result is not an operational failure. tax_id.verification.failed is reserved for a registry request that cannot be completed after retries.
EU VAT (eu_vat)
For every supported EU country other than Spain, combine the VIES prefix with one of these suffixes:
| Outcome | Value |
|---|---|
Valid format; VIES valid: true |
<prefix>000000000 |
Valid format; VIES valid: false |
<prefix>000000001 |
| Rejected immediately for invalid format | <prefix>! |
Usually the prefix is the same as country: for example, use country: "PT" with PT000000000 or PT000000001. Greece is the exception: use country: "GR" with the EL prefix, such as EL000000001.
Spain applies NIF checksum rules before VIES verification, so use the values in Testing the Spain regime.
Local identifiers (local)
Local identifiers are never checked against a registry. In any country, TEST-VALID passes the basic format check and INVALID VALUE! is rejected immediately. There is no valid-versus-invalid registry sentinel for this type.
Exercise webhooks
Create the customer in your Test account, retain the returned Tax ID ID, and subscribe a Test event destination to tax_id.verification.completed. Verification is asynchronous: the create response normally contains verification.status: "pending"; retrieve /v1/tax_ids/{id} or consume the event to observe the terminal value.
Tax-regime-specific validation and downstream outcomes live in the relevant testing guide:
- Testing the Spain regime: Spanish NIFs, synchronous invoice validation, VERI*FACTU outcomes and their webhooks.
See Receiving events with webhooks for signature verification, retries and deduplication.