One call at checkout. One to prove it later.

Create keys in the dashboard. A key is shown once and stored only as a SHA-256 digest, so a lost key is replaced rather than recovered.

Authorization: Bearer vp_live_XXXXXXXXXXXXXXXXXXXXXXXX

• POST/api/v1/verify

  Check a VAT number. The checkout call.

  Synchronous. Returns a decision, not just a verdict. Counts against the quota only when a live consultation is made.

• GET/api/v1/checks

  The audit archive, newest first.

  Cursor paginated with ?limit= (max 100) and ?cursor=. Filter with ?status= and ?vatNumber=.

• GET/api/v1/checks/{id}

  One check, with its receipt re-verified on read.

  Verification is recomputed from the stored facts, never read from a column — a stored 'valid' flag would defeat the point.

• GET/api/v1/audit

  Verify the whole receipt chain.

  Walks the chain oldest first and reports the index it broke at, if any. Free; it does not count against the quota.

• GET/api/v1/status

  Per-member-state VIES availability.

  Useful for explaining an UNAVAILABLE answer, and for a status page.

curl -X POST https://viesproof.altixcode.com/api/v1/verify \
  -H "Authorization: Bearer vp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "vatNumber": "DE143454214",
    "clientReference": "order_9001",
    "trader": { "name": "Example GmbH", "city": "Berlin" }
  }'

Three answers, three decisions. The mapping for UNAVAILABLE depends on your organisation’s policy, which is why the decision is computed here rather than left to each caller to re-derive.

National tax systems go down routinely. Every reason below produces UNAVAILABLE — never INVALID, because treating an outage as a negative verdict blocks legitimate customers for reasons that have nothing to do with them.

• MS_UNAVAILABLE

  That member state's own system is down.

• MS_MAX_CONCURRENT_REQ

  That member state is rate-limiting.

• SERVICE_UNAVAILABLE

  VIES itself is down.

• GLOBAL_MAX_CONCURRENT_REQ

  VIES is rate-limiting globally.

• TIMEOUT

  VIES did not respond inside the timeout.

• IP_BLOCKED / VAT_BLOCKED

  VIES has blocked the request.

An unknown fault is also UNAVAILABLE. We do not guess: a fault code we have not classified could mean anything, and the one interpretation that is certainly wrong is “this number is invalid”.

Every consultation is appended to a per-organisation hash chain. Each receipt commits to the previous receipt’s digest, so an entry cannot be edited, removed or reordered without breaking verification from that point on. The digest is HMAC-signed with a key held only by the server.

GET /api/v1/audit

{
  "verified": false,
  "checked": 412,
  "brokenAt": 412,
  "reason": "digest_mismatch",
  "chainLength": 1204
}

brokenAt is the index of the first entry that failed. An auditor needs to know which record was altered, not merely that something was.

Syntax is checked locally before any call to VIES, so a malformed number costs nothing and produces a message that says what the right shape is. Great Britain is absent: it left the EU VAT area. Northern Ireland remains, as XI.

• AT
• BE
• BG
• CY
• CZ
• DE
• DK
• EE
• EL
• ES
• FI
• FR
• HR
• HU
• IE
• IT
• LT
• LU
• LV
• MT
• NL
• PL
• PT
• RO
• SE
• SI
• SK
• XI