GET /vies/{country}/{vat}

GET /vies/{country}/{vat}

Validates a VAT number against the European Commission’s VIES service. Returns whether the number is currently registered, plus the trader name and address VIES has on file (subject to that Member State’s disclosure policy).

Parameters

Name	Where	Example	Notes
country	path	DE, FR, EL	ISO 3166-1 alpha-2. Greek is accepted as either GR (ISO) or EL (VIES native); the response echoes the spelling you used.
vat	path	123456789	The VAT number without the country prefix. Length varies by country (4 to 12 digits).

Response

{
  "countryCode": "DE",
  "vatNumber": "123456789",
  "requestDate": "2026-05-27+02:00",
  "valid": true,
  "name": "Acme GmbH",
  "address": "Hauptstraße 1"
}

Field meanings

• countryCode — echoed back as you spelt it. Send GR, get GR; send EL, get EL. Internally Stawka normalises both to EL (the VIES wire form) for the upstream call.
• vatNumber — echoed back from the path. No reformatting.
• requestDate — VIES’s own timestamp for the validation, including timezone offset.
• valid — true or false. Only true means the number is registered right now. false means VIES looked it up and the number is not on file.
• name — trader name. null if VIES omits it (some Member States don’t disclose) or if VIES returned the literal ---.
• address — same semantics as name.

Validity is point-in-time

VIES returns a snapshot of what the Member State’s registry shows when the request lands. A number that’s valid today may be invalid tomorrow, and vice versa. Persist the requestDate if you need a defensible audit trail of when you checked.

Cache behaviour

Cache-Control: private, max-age=300–3600. The exact value depends on the upstream’s response signals. Repeated calls for the same (country, vat) pair hit our cache and do not consume your rate-limit or quota.

Errors

Status	Body	Cause
422	{"error": "INVALID_INPUT"}	VIES rejected the country or VAT number format. Fix the input.
503	{"error": "MS_UNAVAILABLE"}	The specific Member State registry is down. Retry later; this is intermittent on VIES’s side.
503	{"error": "SERVICE_UNAVAILABLE"}	VIES itself is degraded.
503	{"error": "TIMEOUT"}	VIES exceeded our hard timeout.
502	{"error": "..."}	Anything else (parse error, network failure, unknown upstream code). Please open an issue.
401	{"error": "INVALID_KEY"}	Missing or invalid bearer token.
429	{"error": "RATE_LIMITED"} or {"error": "QUOTA_EXCEEDED"}	See rate limits.

Greek country codes (GR vs EL)

VIES uses EL (the ISO 639 code for Greek, not the ISO 3166 code for Greece) for Greek VAT numbers. ISO 3166 says Greece is GR. Stawka accepts both:

curl https://api.stawka.eu/vies/GR/123456789  -H "Authorization: Bearer ..."
curl https://api.stawka.eu/vies/EL/123456789  -H "Authorization: Bearer ..."

Both validate the same upstream number; the response’s countryCode field echoes whichever you passed. Pick whichever your downstream systems expect — there is no “right” choice between ISO 3166 and the VIES native form.