Test Mode

Test API keys let you build and test your integration with deterministic, offline responses — no VIES calls, no quota usage, no database writes.

Your Test Key

Every account has exactly one test key. It is created automatically when you sign up and included in your welcome email. You can always find it (and regenerate it) in Dashboard > API Keys.

Test keys start with vat_test_, while live keys start with vat_live_. The API distinguishes them by prefix — everything else about the request is identical.

How It Works

When the API receives a request authenticated with a vat_test_ key, it short-circuits immediately and returns a fixture response. Specifically:

• Format validation is skipped — only the XX prefix matters
• No VIES or national fallback call is made
• Nothing is written to the database
• Your monthly quota counter is not incremented
• IP-based rate limiting is bypassed (same as live keys)
• consultationNumber is always null

The response is structurally identical to a live response — all fields including countryVat are fully populated — so your parsing and display code can be tested end-to-end.

XX Fixture VAT Numbers

Test mode only accepts VAT numbers starting with XX — a reserved prefix that can never match a real company. Any other VAT number returns a 400 INVALID_FORMAT error with a message explaining that test mode requires XX numbers.

Five specific numbers trigger distinct scenarios. Every other XX* number falls back to the default invalid result.

Example Requests

Valid VAT with full details

curl https://api.vatnode.dev/v1/vat/XX0000001 \
  -H "Authorization: Bearer vat_test_your_test_key"

{
  "valid": true,
  "vatId": "XX0000001",
  "countryCode": "XX",
  "countryName": "Test Country",
  "companyName": "Test Company Ltd",
  "companyAddress": "1 Test Street, Test City, TC1 0AA",
  "companyRegistrationDate": null,
  "companyForm": null,
  "industryDescription": null,
  "registryCode": null,
  "registryCodeName": null,
  "consultationNumber": null,
  "verifiedAt": "2026-04-01T10:00:00.000Z",
  "checkId": "019d2a89-a5d9-7b97-b710-57b84604de2b",
  "countryVat": {
    "vatName": "Value Added Tax",
    "vatAbbr": "VAT",
    "currency": "EUR",
    "standardRate": 10,
    "reducedRates": [9, 8, 7],
    "superReducedRate": 6,
    "parkingRate": 5,
    "vatNumberFormat": "XX + 7 digits",
    "vatNumberPattern": "^XX\\d{7}$",
    "countryVatUpdatedAt": "2026-03-31"
  }
}

Invalid VAT number

curl https://api.vatnode.dev/v1/vat/XX0000003 \
  -H "Authorization: Bearer vat_test_your_test_key"

{
  "valid": false,
  "vatId": "XX0000003",
  "countryCode": "XX",
  "countryName": "Test Country",
  "companyName": null,
  "companyAddress": null,
  "companyRegistrationDate": null,
  "companyForm": null,
  "industryDescription": null,
  "registryCode": null,
  "registryCodeName": null,
  "consultationNumber": null,
  "verifiedAt": "2026-04-01T10:00:00.000Z",
  "checkId": "019d2a89-a5d9-7b97-b710-57b84604de2b",
  "countryVat": { ... }
}

VIES unavailable error

curl https://api.vatnode.dev/v1/vat/XX0000004 \
  -H "Authorization: Bearer vat_test_your_test_key"

{
  "error": {
    "code": "VIES_UNAVAILABLE",
    "message": "VIES service is temporarily unavailable",
    "requestId": "req_abc123"
  }
}

Non-XX number in test mode

Sending a real or made-up VAT number with a test key returns a 400 immediately:

{
  "error": {
    "code": "INVALID_FORMAT",
    "message": "Test mode only accepts XX VAT numbers (e.g. XX0000001). Use your live key for real VAT IDs.",
    "requestId": "req_abc123"
  }
}

Regenerating Your Test Key

If you need to rotate the key (e.g. it was accidentally committed), go to Dashboard > API Keys and click Regenerate in the Test Key section. The old key is invalidated immediately.

You can also call the API directly:

curl -X POST https://api.vatnode.dev/v1/me/test-key/regenerate \
  -H "Cookie: better-auth.session_token=..."

Test vs Live — Summary

Next Steps

• See Authentication for API key management and rate limits
• Read VAT Validation for the full response schema and live behaviour
• Handle Errors including the upstream errors you can simulate with XX0000004 and XX0000005