EU VAT Number Validation (VIES Registry)

{
  "type": "object",
  "required": [
    "vat_number"
  ],
  "properties": {
    "vat_number": {
      "type": "string",
      "description": "EU VAT number including country prefix (e.g. SE556703748501)"
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "valid": {
      "type": "boolean",
      "description": "Whether VIES currently reports this VAT number as valid."
    },
    "cache_hit": {
      "type": "boolean",
      "description": "Present only when this exact lookup was served from cache rather than a fresh VIES call -- observed on the cached-hit fixture and absent on the fresh-lookup fixture, so treat it as optional, not guaranteed present on every response."
    },
    "cached_at": {
      "type": "string",
      "description": "ISO 8601 timestamp of when the cached result was originally fetched. Present only alongside `cache_hit`; absent on a fresh lookup."
    },
    "vat_number": {
      "type": "string",
      "description": "The VAT number exactly as submitted, echoed back."
    },
    "company_name": {
      "type": "string",
      "description": "The registered company name on file with VIES. Observed as an empty string on a VAT number VIES rejects as invalid."
    },
    "country_code": {
      "type": "string",
      "description": "Two-letter EU country code parsed from the submitted VAT number."
    },
    "request_date": {
      "type": "string",
      "description": "The date VIES processed this request, with UTC offset (e.g. '2026-09-19+02:00')."
    },
    "cache_age_hours": {
      "type": "number",
      "description": "How many hours old the cached result is. Present only alongside `cache_hit`, on the same cache-backed responses; absent on a fresh lookup."
    },
    "company_address": {
      "type": "string",
      "description": "The registered company address on file with VIES, as a single multi-line string. Observed as an empty string on a VAT number VIES rejects as invalid."
    }
  },
  "description": "The VAT validation result, as returned at routing.responseResultPath ($.output).",
  "additionalProperties": true
}