VatSignal Docs

Use VatSignal to validate EU VAT numbers through VIES, manage fallback behavior during upstream outages, and store validation receipts for audit evidence.

Quick start

Validate a VAT number with a single POST request:

bash

curl -X POST https://vatsignal.com/v1/vat/validate \
  -H "Authorization: Bearer vs_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{"vat_number": "DE123456789", "reference": "checkout_1001"}'

Get API key

Authentication

http

Authorization: Bearer vs_test_your_key

Use a sandbox key for testing and a live key for real VIES validation. Keep live keys server-side and never expose them in browser JavaScript.

Validate a VAT number

POST /v1/vat/validate — Validate a single EU VAT number. Response includes receipt_url for the audit PDF.

json

{
  "request_id": "val_8f42c9",
  "vat_number": "DE123456789",
  "valid": true,
  "source": "VIES",
  "source_status": "live",
  "fallback_used": false,
  "action": "accept",
  "checked_at": "2026-06-11T19:01:17Z",
  "receipt_url": "/v1/validations/val_8f42c9/receipt.pdf"
}

Checkout preflight

POST /v1/b2b/checkout-preflight — B2B checkout decision endpoint with recommended action.

bash

curl -X POST https://vatsignal.com/v1/b2b/checkout-preflight \
  -H "Authorization: Bearer vs_test_your_key" \
  -d '{
    "seller_country": "ES",
    "buyer_country": "DE",
    "buyer_vat_number": "DE123456789",
    "policy": { "on_vies_unavailable": "allow_with_review" }
  }'

Response fields

Field	Description
`request_id`	Unique ID for the validation request.
`valid`	Boolean validation result when a live or cached result is available.
`source`	Upstream source used, usually VIES.
`source_status`	live, cached, unavailable, or error.
`fallback_used`	Whether a cached/fallback result was used.
`action`	Recommended checkout action: accept, reject, or review.
`checked_at`	Timestamp of the validation check.
`receipt_url`	URL to download the audit receipt PDF.

Fallback behavior

VatSignal separates three different situations:

The VAT number is valid.
The VAT number is invalid.
The upstream validation source is unavailable.

This distinction matters for checkout. An unavailable source should not be treated as the same thing as an invalid VAT number.

Source status values

live — Validated directly against the upstream source.
cached — Returned from a previous successful validation within the cache window.
unavailable — Live validation could not be completed and no usable cached record was available.
error — Request failed due to input, authentication, quota, or system error.

Recommended checkout actions

accept — Proceed with checkout.
reject — Block VAT-based approval or ask the customer to correct the VAT number.
review — Allow the order/signup but mark for manual review.

Receipts

Every validation can produce a receipt with request ID, timestamp, VAT number, source status, result, and consultation reference when available.

bash

curl -L https://vatsignal.com/v1/validations/val_abc123/receipt.pdf \
  -H "Authorization: Bearer vs_test_your_key" \
  -o vatsignal-receipt.pdf

Batch validation

Submit a list of VAT numbers for asynchronous validation. Poll batch status or download results as CSV.

bash

curl -X POST https://vatsignal.com/v1/vat/batch \
  -H "Authorization: Bearer vs_test_your_key" \
  -d '{"vat_numbers": ["DE123456789", "FR12345678901"]}'

Webhooks

Receive validation results, batch completion events, and source status notifications in your application.

Events: validation.completed, batch.completed, source.degraded, source.recovered

Error codes

Code	Meaning	Recommended action
`invalid_vat_format`	VAT number format is invalid	Ask user to correct it
`unauthorized`	API key missing or invalid	Check authentication
`quota_exceeded`	Account usage limit reached	Upgrade or add credits
`source_unavailable`	VIES or country service unavailable	Use fallback/review logic
`validation_timeout`	Upstream validation timed out	Retry or use fallback
`internal_error`	VatSignal server error	Retry later

Sandbox vs live

Sandbox keys (vs_test_) return mock validation responses and do not query VIES.

Live keys (vs_live_) query real VAT sources and count toward your plan quota. Keep live keys server-side.

API reference

Interactive OpenAPI reference for all VatSignal endpoints.

Open API Reference

Live sandbox

Uses the API key stored in this browser after you log in and create one in Dashboard. Test numbers: DE123456789 (valid), DE000000000 (invalid).

VAT number