openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "vatverify API",
    "version": "1.0.0",
    "description": "VAT validation across 32 countries. Real checksums, 30-day caching, tax-rules engine."
  },
  "servers": [
    {
      "url": "https://api.vatverify.dev",
      "description": "Production"
    },
    {
      "url": "http://localhost:3000",
      "description": "Local development"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        },
        "required": [
          "ok"
        ],
        "additionalProperties": false,
        "example": {
          "ok": true
        }
      },
      "CountryVat": {
        "type": [
          "object",
          "null"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Official local name of the tax (e.g. \"Arvonlisävero\", \"Mehrwertsteuer\", \"TVA\").",
            "example": "Value Added Tax"
          },
          "abbreviation": {
            "type": "string",
            "description": "Short abbreviation used in invoices and official docs (e.g. \"VAT\", \"MwSt\", \"TVA\", \"IVA\").",
            "example": "VAT"
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 currency code used when invoicing in this country.",
            "example": "EUR"
          },
          "standard_rate": {
            "type": "number",
            "description": "Standard VAT rate applied to most goods and services, in percent.",
            "example": 23
          },
          "reduced_rates": {
            "type": "array",
            "items": {
              "type": "number"
            },
            "description": "Reduced VAT rates applied to specific categories (food, medicine, books, etc). Empty array when the country has no reduced rate.",
            "example": [
              9,
              13.5
            ]
          },
          "super_reduced_rate": {
            "type": [
              "number",
              "null"
            ],
            "description": "Super-reduced rate for essential items, where applicable (currently CY, ES, FR, IT, LU, PT). Null for countries that do not use one.",
            "example": 4.8
          },
          "parking_rate": {
            "type": [
              "number",
              "null"
            ],
            "description": "Transitional \"parking\" rate for items that previously qualified for a reduced rate. Null for most countries.",
            "example": 13.5
          },
          "number_format": {
            "type": "string",
            "description": "Human-readable description of the VAT number format for this country.",
            "example": "IE + 7 digits + 1-2 letters"
          },
          "number_pattern": {
            "type": "string",
            "description": "Regex pattern for client-side format validation before hitting the API. Matches the normalized (uppercased, stripped) VAT string.",
            "example": "^IE\\d{7}[A-Z]{1,2}$"
          },
          "updated_at": {
            "type": "string",
            "description": "ISO date when the VAT metadata for this country was last reviewed.",
            "example": "2026-04-01"
          }
        },
        "required": [
          "name",
          "abbreviation",
          "currency",
          "standard_rate",
          "reduced_rates",
          "super_reduced_rate",
          "parking_rate",
          "number_format",
          "number_pattern",
          "updated_at"
        ],
        "description": "VAT metadata for this country (rates, currency, number format). Null when we have no data for the country (currently XI, LI)."
      },
      "Company": {
        "type": [
          "object",
          "null"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Registered legal name of the company as reported by the upstream registry.",
            "example": "GOOGLE IRELAND LIMITED"
          },
          "address": {
            "type": "string",
            "description": "Registered address of the company. Absent when the registry does not publish an address (e.g. Germany).",
            "example": "3RD FLOOR GORDON HOUSE, BARROW STREET, DUBLIN 4"
          }
        },
        "required": [
          "name"
        ],
        "description": "Company details returned by the upstream registry. Null when `valid: false` or when the registry does not publish company info (e.g. Germany)."
      },
      "ValidateData": {
        "type": "object",
        "properties": {
          "valid": {
            "type": "boolean",
            "description": "Whether the VAT number is registered and active according to the upstream registry.",
            "example": true
          },
          "vat_number": {
            "type": "string",
            "description": "The normalized VAT number — uppercased, stripped of spaces/dots/dashes, with country prefix.",
            "example": "IE6388047V"
          },
          "country": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "pattern": "^[A-Za-z]{2}$",
                "description": "Two-letter ISO-3166 country code extracted from the VAT prefix.",
                "example": "IE"
              },
              "name": {
                "type": "string",
                "description": "Full English country name.",
                "example": "Ireland"
              },
              "vat": {
                "$ref": "#/components/schemas/CountryVat"
              }
            },
            "required": [
              "code",
              "name",
              "vat"
            ],
            "description": "Country derived from the VAT prefix, with VAT metadata useful for invoicing and client-side validation."
          },
          "company": {
            "$ref": "#/components/schemas/Company"
          },
          "verify_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Official verification identifier emitted by the upstream registry (VIES consultation number / HMRC check reference). Populated when `requester_vat_number` is provided and the source supports it; null otherwise. Tax auditors accept this as proof of a valid query.",
            "example": "WAPIAAAAA1BBB2"
          },
          "verified_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp of when the VAT number was fetched from the registry. For cached responses this is the original fetch time, not the current request time.",
            "example": "2026-04-14T15:42:03.451Z"
          }
        },
        "required": [
          "valid",
          "vat_number",
          "country",
          "company",
          "verify_id",
          "verified_at"
        ]
      },
      "Meta": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string",
            "description": "UUID v7 identifying this specific HTTP request. Include it in any support ticket so we can trace the call in our logs.",
            "example": "0190f8ea-a5b2-7000-a123-000000000000"
          },
          "latency_ms": {
            "type": "integer",
            "minimum": 0,
            "description": "Total server-side processing time in milliseconds, from request received to response sent.",
            "example": 694
          },
          "cached": {
            "type": "boolean",
            "description": "Whether this response was served from the 30-day cache instead of a fresh registry fetch. Cached hits do not count toward your monthly quota.",
            "example": false
          },
          "source": {
            "type": "string",
            "enum": [
              "vies",
              "hmrc",
              "bfs",
              "brreg"
            ],
            "description": "Which official registry produced this result. `vies` for EU-27 + XI, `hmrc` for GB, `bfs` for CH/LI, `brreg` for NO.",
            "example": "vies"
          },
          "source_status": {
            "type": "string",
            "enum": [
              "live",
              "cached",
              "degraded"
            ],
            "description": "Upstream data source reliability. `live` = confirmed fresh registry response. `cached` = served from the 30-day cache. `degraded` = result may be unreliable (reserved for future expansion).",
            "example": "live"
          }
        },
        "required": [
          "request_id",
          "latency_ms",
          "cached",
          "source",
          "source_status"
        ]
      },
      "ValidateResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/ValidateData"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "ErrorMeta": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string"
          },
          "latency_ms": {
            "type": "integer",
            "minimum": 0
          }
        },
        "required": [
          "request_id",
          "latency_ms"
        ]
      },
      "ErrorEnvelope": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "plan_required",
                  "invalid_format",
                  "country_unsupported",
                  "country_unknown",
                  "batch_too_large",
                  "webhook_limit_reached",
                  "seller_country_unsupported",
                  "b2c_not_supported",
                  "buyer_vat_not_registered",
                  "not_found",
                  "rate_limited",
                  "registry_unavailable"
                ],
                "example": "invalid_format"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ]
          },
          "meta": {
            "$ref": "#/components/schemas/ErrorMeta"
          }
        },
        "required": [
          "error",
          "meta"
        ],
        "additionalProperties": false
      },
      "DecideData": {
        "type": "object",
        "properties": {
          "charge_vat": {
            "type": "boolean",
            "description": "Whether the seller should charge VAT to the buyer on this transaction.",
            "example": false
          },
          "rate": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "VAT rate to charge, in percent. Zero when the mechanism is `reverse_charge` or `zero_rated`.",
            "example": 0
          },
          "mechanism": {
            "type": "string",
            "enum": [
              "standard",
              "reverse_charge",
              "zero_rated",
              "out_of_scope"
            ],
            "description": "VAT mechanism that applies. `standard` = seller charges VAT at the applicable rate. `reverse_charge` = buyer accounts for VAT (EU cross-border B2B, Article 196). `zero_rated` = 0% rate applies. `out_of_scope` = transaction falls outside VAT scope.",
            "example": "reverse_charge"
          },
          "legal_basis": {
            "type": "string",
            "description": "Legal article or rule that justifies the mechanism. Cite this on the invoice when required by local tax authorities.",
            "example": "EU VAT Directive Article 196"
          },
          "explanation": {
            "type": "string",
            "description": "Plain-English explanation of why this mechanism applies. Safe to surface in your app as a tooltip or help text.",
            "example": "Your customer provided a valid French VAT number, so this is an EU cross-border B2B supply. The reverse-charge mechanism applies — you do not charge VAT, and the buyer self-accounts."
          },
          "invoice_note": {
            "type": "string",
            "description": "Text to print on the invoice when the mechanism requires it (e.g. reverse-charge notice). Empty string when no note is needed.",
            "example": "Reverse charge — VAT to be accounted for by the recipient"
          },
          "disclaimer": {
            "type": "string",
            "description": "Standard disclaimer. This endpoint applies deterministic tax rules — always confirm with a qualified tax adviser for your specific situation.",
            "example": "This is guidance, not legal advice. Confirm with a qualified tax adviser for your specific situation."
          },
          "buyer_vat": {
            "type": "object",
            "properties": {
              "valid": {
                "type": "boolean",
                "description": "Whether the buyer VAT number is registered and active according to the upstream registry.",
                "example": true
              },
              "country": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string",
                    "pattern": "^[A-Za-z]{2}$",
                    "example": "FR"
                  },
                  "name": {
                    "type": "string",
                    "example": "France"
                  }
                },
                "required": [
                  "code",
                  "name"
                ],
                "description": "Buyer country derived from the VAT prefix. Absent when the VAT is malformed."
              }
            },
            "required": [
              "valid"
            ],
            "description": "Summary of the buyer VAT validation performed as part of the decide call."
          },
          "decided_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp of when this decision was computed server-side.",
            "example": "2026-04-14T15:42:03.451Z"
          }
        },
        "required": [
          "charge_vat",
          "rate",
          "mechanism",
          "legal_basis",
          "explanation",
          "invoice_note",
          "disclaimer",
          "decided_at"
        ]
      },
      "DecideSourceEntry": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "seller",
              "buyer"
            ],
            "description": "Whether this entry describes the seller or buyer VAT lookup.",
            "example": "buyer"
          },
          "source": {
            "type": "string",
            "enum": [
              "vies",
              "hmrc",
              "bfs",
              "brreg"
            ],
            "description": "Which registry was used for this lookup.",
            "example": "vies"
          },
          "source_status": {
            "type": "string",
            "enum": [
              "live",
              "cached",
              "degraded"
            ],
            "description": "Upstream data source reliability. `live` = confirmed fresh registry response. `cached` = served from the 30-day cache. `degraded` = result may be unreliable (reserved for future expansion).",
            "example": "live"
          },
          "cached": {
            "type": "boolean",
            "description": "Whether this result was served from cache.",
            "example": false
          },
          "cached_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "ISO 8601 timestamp of when the value was originally fetched and cached. Null for live results.",
            "example": null
          },
          "stale_seconds": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "description": "Age of the cached value in seconds. Null for live results.",
            "example": null
          }
        },
        "required": [
          "role",
          "source",
          "source_status",
          "cached",
          "cached_at",
          "stale_seconds"
        ]
      },
      "DecideMeta": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string",
            "description": "UUID v7 identifying this specific HTTP request.",
            "example": "0190f8ea-a5b2-7000-a123-000000000000"
          },
          "latency_ms": {
            "type": "integer",
            "minimum": 0,
            "description": "Total server-side processing time in milliseconds.",
            "example": 820
          },
          "source_status": {
            "type": "string",
            "enum": [
              "live",
              "cached",
              "degraded"
            ],
            "description": "Rolled-up worst-case source status across all lookups (seller + buyer).",
            "example": "live"
          },
          "sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DecideSourceEntry"
            },
            "description": "Per-VAT source details for the seller and buyer lookups."
          }
        },
        "required": [
          "request_id",
          "latency_ms",
          "source_status",
          "sources"
        ]
      },
      "DecideResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/DecideData"
          },
          "meta": {
            "$ref": "#/components/schemas/DecideMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "DecideRequest": {
        "type": "object",
        "properties": {
          "seller_vat": {
            "type": "string",
            "minLength": 4,
            "description": "Seller VAT number, full with country prefix. Seller country is derived from the prefix (e.g., \"DE...\" → Germany).",
            "example": "DE811569869"
          },
          "buyer_vat": {
            "type": "string",
            "minLength": 4,
            "description": "Buyer VAT number, full with country prefix. Buyer country is derived from the prefix. This endpoint is B2B-only in v1; for B2C transactions (consumer, no VAT number) support is on the roadmap.",
            "example": "FR44732829320"
          }
        },
        "required": [
          "seller_vat",
          "buyer_vat"
        ],
        "additionalProperties": false
      },
      "RegistrationThreshold": {
        "type": [
          "object",
          "null"
        ],
        "properties": {
          "domestic": {
            "type": [
              "number",
              "null"
            ],
            "description": "Revenue above which a seller based in this country must register for VAT. Null when no threshold exists (VAT mandatory from €0) or when we do not track a threshold for this country.",
            "example": 22000
          },
          "distance_selling": {
            "type": [
              "number",
              "null"
            ],
            "description": "EU-wide OSS cross-border B2C threshold (uniform €10,000 since July 2021). Null for non-EU countries.",
            "example": 10000
          },
          "currency": {
            "type": "string",
            "minLength": 3,
            "maxLength": 3,
            "description": "ISO 4217 currency for the thresholds.",
            "example": "EUR"
          }
        },
        "required": [
          "domestic",
          "distance_selling",
          "currency"
        ],
        "description": "VAT registration thresholds; null when we do not track thresholds for this country."
      },
      "CountryRate": {
        "type": "object",
        "properties": {
          "country_code": {
            "type": "string",
            "minLength": 2,
            "maxLength": 2,
            "description": "ISO 3166-1 alpha-2 code, lowercase.",
            "example": "de"
          },
          "country_name": {
            "type": "string",
            "description": "English country name.",
            "example": "Germany"
          },
          "country_name_local": {
            "type": "string",
            "description": "Country name in its official local language.",
            "example": "Deutschland"
          },
          "currency": {
            "type": "string",
            "minLength": 3,
            "maxLength": 3,
            "description": "ISO 4217 currency code used for invoicing in this country.",
            "example": "EUR"
          },
          "is_eu_member": {
            "type": "boolean",
            "description": "True for the 27 EU member states plus XI (Northern Ireland under the Brexit protocol).",
            "example": true
          },
          "supports_live_validation": {
            "type": "boolean",
            "description": "True when /v1/validate can verify a VAT number for this country against a live registry.",
            "example": true
          },
          "standard_rate": {
            "type": "number",
            "description": "Standard VAT rate as a percentage, e.g. 19 for 19%.",
            "example": 19
          },
          "reduced_rates": {
            "type": "array",
            "items": {
              "type": "number"
            },
            "description": "Ordered array of reduced rates; empty if none.",
            "example": [
              7
            ]
          },
          "super_reduced_rate": {
            "type": [
              "number",
              "null"
            ],
            "description": "Super-reduced rate if applicable, otherwise null.",
            "example": null
          },
          "parking_rate": {
            "type": [
              "number",
              "null"
            ],
            "description": "Transitional parking rate if applicable, otherwise null.",
            "example": null
          },
          "vat_name": {
            "type": "string",
            "description": "Local tax name in the country language.",
            "example": "Umsatzsteuer"
          },
          "vat_abbr": {
            "type": "string",
            "description": "Local tax abbreviation.",
            "example": "USt"
          },
          "vat_number_format": {
            "type": "string",
            "description": "Human-readable description of the VAT number format.",
            "example": "DE + 9 digits"
          },
          "vat_number_regex": {
            "type": "string",
            "description": "Regex pattern for client-side format validation.",
            "example": "^DE\\d{9}$"
          },
          "registration_threshold": {
            "$ref": "#/components/schemas/RegistrationThreshold"
          },
          "updated_at": {
            "type": "string",
            "description": "ISO date (YYYY-MM-DD) of the last verified refresh for this country row. Not a full datetime — precision is day-level.",
            "example": "2026-04-13"
          }
        },
        "required": [
          "country_code",
          "country_name",
          "country_name_local",
          "currency",
          "is_eu_member",
          "supports_live_validation",
          "standard_rate",
          "reduced_rates",
          "super_reduced_rate",
          "parking_rate",
          "vat_name",
          "vat_abbr",
          "vat_number_format",
          "vat_number_regex",
          "registration_threshold",
          "updated_at"
        ]
      },
      "RatesMeta": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string",
            "description": "UUID v7 identifying this specific HTTP request.",
            "example": "0190f8ea-a5b2-7000-a123-000000000000"
          },
          "data_version": {
            "type": "string",
            "description": "ISO date (YYYY-MM-DD) of the underlying rates dataset. Use as an ETag key.",
            "example": "2026-04-13"
          },
          "cached": {
            "type": "boolean",
            "description": "Always true for /v1/rates — data is loaded in-process at startup.",
            "example": true
          }
        },
        "required": [
          "request_id",
          "data_version",
          "cached"
        ]
      },
      "RatesListMeta": {
        "allOf": [
          {
            "$ref": "#/components/schemas/RatesMeta"
          },
          {
            "type": "object",
            "properties": {
              "count": {
                "type": "integer",
                "minimum": 0,
                "description": "Number of country objects in `data`.",
                "example": 44
              }
            },
            "required": [
              "count"
            ]
          }
        ]
      },
      "RatesListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CountryRate"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/RatesListMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "RatesSingleResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/CountryRate"
          },
          "meta": {
            "$ref": "#/components/schemas/RatesMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "BatchSummary": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "Total number of items in the request (`vat_numbers.length`).",
            "example": 3
          },
          "successful": {
            "type": "integer",
            "minimum": 0,
            "description": "Items that returned `ok: true` (the registry answered, regardless of valid/invalid outcome).",
            "example": 2
          },
          "failed": {
            "type": "integer",
            "minimum": 0,
            "description": "Items that returned `ok: false` (normalization failed, country unsupported, or registry unavailable).",
            "example": 1
          }
        },
        "required": [
          "total",
          "successful",
          "failed"
        ]
      },
      "BatchPerItemError": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "invalid_format",
              "country_unsupported",
              "registry_unavailable"
            ],
            "description": "Per-item error code. Only these three codes are possible inside a per-item error; auth / plan / rate-limit errors fail the whole batch, not individual items.",
            "example": "invalid_format"
          },
          "message": {
            "type": "string",
            "description": "Human-readable message for this item. Safe to surface in UIs.",
            "example": "Unsupported country prefix `ZZ`"
          }
        },
        "required": [
          "code",
          "message"
        ]
      },
      "BatchResultItem": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "ok": {
                "type": "boolean",
                "enum": [
                  true
                ]
              },
              "data": {
                "$ref": "#/components/schemas/ValidateData"
              }
            },
            "required": [
              "ok",
              "data"
            ]
          },
          {
            "type": "object",
            "properties": {
              "ok": {
                "type": "boolean",
                "enum": [
                  false
                ]
              },
              "error": {
                "$ref": "#/components/schemas/BatchPerItemError"
              }
            },
            "required": [
              "ok",
              "error"
            ]
          }
        ]
      },
      "ValidateBatchResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "summary": {
                "$ref": "#/components/schemas/BatchSummary"
              },
              "results": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/BatchResultItem"
                },
                "description": "Per-item results in the same order as the input `vat_numbers` array. `results.length === total`."
              }
            },
            "required": [
              "summary",
              "results"
            ]
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "ValidateBatchRequest": {
        "type": "object",
        "properties": {
          "vat_numbers": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 4
            },
            "minItems": 1,
            "maxItems": 50,
            "description": "Array of VAT numbers to validate. Each can include spaces, dots, or mixed case — normalized automatically. Max 50 items per request. Each item is normalized and routed to the correct registry (VIES/HMRC/BFS/BRREG) independently.",
            "example": [
              "IE6388047V",
              "DE811569869",
              "FR44732829320"
            ]
          },
          "requester_vat_number": {
            "type": "string",
            "minLength": 4,
            "description": "Your own VAT number. When provided, each VIES item is looked up via an authenticated consultation and the response includes a per-item `verify_id` — the official consultation identifier accepted by tax auditors as proof of verification. These calls always bypass the cache and count toward your quota. Not applicable for CH, LI, or NO registrations (those items will have `verify_id: null`).",
            "example": "DE100000001"
          }
        },
        "required": [
          "vat_numbers"
        ]
      },
      "AuditResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "request_id": {
                "type": "string",
                "format": "uuid",
                "example": "019d917e-4fa4-766e-9e0f-d977b47bf2c6"
              },
              "endpoint": {
                "type": "string",
                "enum": [
                  "validate",
                  "decide",
                  "validate_batch"
                ],
                "example": "validate"
              },
              "response": {
                "type": "object",
                "additionalProperties": {},
                "description": "The full original success response envelope."
              },
              "created_at": {
                "type": "string",
                "example": "2026-04-15T14:11:49.110Z"
              },
              "expires_at": {
                "type": "string",
                "example": "2026-07-14T14:11:49.110Z"
              }
            },
            "required": [
              "request_id",
              "endpoint",
              "response",
              "created_at",
              "expires_at"
            ]
          },
          "meta": {
            "type": "object",
            "properties": {
              "request_id": {
                "type": "string",
                "format": "uuid"
              },
              "latency_ms": {
                "type": "number"
              }
            },
            "required": [
              "request_id",
              "latency_ms"
            ]
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "WebhookResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "019d917e-4fa4-766e-9e0f-d977b47bf2c6"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "example": "https://example.com/webhooks/vatverify"
          },
          "secret": {
            "type": "string",
            "description": "Shown once — store it securely.",
            "example": "whsec_a1b2c3d4e5f6..."
          },
          "created_at": {
            "type": "string",
            "example": "2026-04-15T10:00:00Z"
          }
        },
        "required": [
          "id",
          "url",
          "secret",
          "created_at"
        ]
      },
      "WebhookCreateBody": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "example": "https://example.com/webhooks/vatverify"
          }
        },
        "required": [
          "url"
        ]
      },
      "WebhookPublic": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "019d917e-4fa4-766e-9e0f-d977b47bf2c6"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "example": "https://example.com/webhooks/vatverify"
          },
          "created_at": {
            "type": "string",
            "example": "2026-04-15T10:00:00Z"
          }
        },
        "required": [
          "id",
          "url",
          "created_at"
        ]
      },
      "WebhookListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookPublic"
            }
          }
        },
        "required": [
          "data"
        ]
      },
      "WebhookTestResponse": {
        "type": "object",
        "properties": {
          "delivered": {
            "type": "boolean",
            "example": true
          },
          "status": {
            "type": "integer",
            "example": 200
          }
        },
        "required": [
          "delivered",
          "status"
        ]
      }
    },
    "parameters": {}
  },
  "paths": {
    "/health": {
      "get": {
        "tags": [
          "Meta"
        ],
        "operationId": "healthcheck",
        "summary": "Liveness probe",
        "description": "Returns { ok: true } when the server is up. No authentication required.",
        "responses": {
          "200": {
            "description": "Server is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/validate": {
      "get": {
        "tags": [
          "Validation"
        ],
        "operationId": "validateVat",
        "summary": "Validate a VAT number",
        "description": "Validate a VAT number against the appropriate upstream service (VIES, HMRC, BFS, or BRREG) and return the validity status, company details, and VAT metadata for the country.\n\nInput is normalized automatically — spaces, dots, and casing are handled for you (\"de 811.569.869\" → \"DE811569869\").\n\nResults are cached for 30 days. Cached responses include `meta.cached: true`; `data.verified_at` always reflects the original registry fetch time. Pass `cache=false` to bypass the cache and force a fresh lookup from the upstream service.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 4,
              "description": "Full VAT number with country prefix. Spaces, dots, and casing are handled automatically (\"de 811.569.869\" → \"DE811569869\"). Norwegian registrations use the \"NO\" prefix even though the underlying 9-digit number has no prefix in Brønnøysund.",
              "example": "DE811569869"
            },
            "required": true,
            "name": "vat_number",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "description": "Set to `false` to bypass the 30-day cache and force a fresh upstream lookup. Defaults to `true`.",
              "example": "true"
            },
            "required": false,
            "name": "cache",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 4,
              "description": "Your own VAT number. When provided, the response includes a `data.verify_id` — the official consultation identifier emitted by VIES (or HMRC, when supported). These calls bypass the cache since the verify_id is specific to each consultation.",
              "example": "DE100000001"
            },
            "required": false,
            "name": "requester_vat_number",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Validation result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidateResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "Test-mode VAT not in magic fixtures",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "502": {
            "description": "Upstream registry unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/decide": {
      "post": {
        "tags": [
          "Tax rules"
        ],
        "operationId": "decideTax",
        "summary": "Decide whether to charge VAT",
        "description": "Given seller and buyer VAT numbers, returns whether to charge VAT, at what rate, under which mechanism, with legal basis and invoice note. Requires a Business-plan API key. Shares the monthly quota pool with /v1/validate.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DecideRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Decision result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DecideResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or unsupported scenario",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "402": {
            "description": "Requires Business plan",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "Test-mode VAT not in magic fixtures",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/rates": {
      "get": {
        "tags": [
          "Rates"
        ],
        "operationId": "listRates",
        "summary": "List VAT rates for all 44 countries",
        "description": "Return VAT rates for all 44 countries in our dataset (EU-27 + XI + 16 non-EU European states). Public endpoint — no API key required. Rate-limited to 20 requests per hour per IP. Response body is cacheable (`Cache-Control: public, max-age=3600, stale-while-revalidate=86400`). Clients should honor the `ETag` and use `If-None-Match` for conditional GETs to avoid hitting the limit.",
        "responses": {
          "200": {
            "description": "List of country rate objects",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RatesListResponse"
                }
              }
            }
          },
          "304": {
            "description": "Not modified (If-None-Match matched current data_version)"
          },
          "429": {
            "description": "Rate limit exceeded (20 req/hour per IP)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/rates/{country}": {
      "get": {
        "tags": [
          "Rates"
        ],
        "operationId": "getRate",
        "summary": "Get VAT rates for a single country",
        "description": "Return VAT rates for a single country by ISO 3166-1 alpha-2 code (case-insensitive). Public endpoint — no API key required. Same rate limit and cache semantics as `GET /v1/rates`.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z]{2}$",
              "description": "Two-letter ISO 3166-1 alpha-2 country code (case-insensitive).",
              "example": "de"
            },
            "required": true,
            "name": "country",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Country rate object",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RatesSingleResponse"
                }
              }
            }
          },
          "304": {
            "description": "Not modified"
          },
          "400": {
            "description": "Malformed country code (not 2 letters)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "Country not in our dataset",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/validate/batch": {
      "post": {
        "tags": [
          "Validation"
        ],
        "operationId": "validateBatch",
        "summary": "Validate up to 50 VAT numbers in one request",
        "description": "Validate up to 50 VAT numbers in a single request. Each item is normalized and routed to the correct registry (VIES/HMRC/BFS/BRREG) independently. Per-item successes and failures coexist in the 200 response under `data.results`. Cache hits do not count against your monthly quota.\n\nPass `requester_vat_number` to obtain a per-item `verify_id` (VIES consultation number) for each EU result — useful for tax-audit trails. Calls with a requester always bypass the cache.\n\nPro plan or Business plan required.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ValidateBatchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Per-item results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidateBatchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body / empty array",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "402": {
            "description": "Plan does not include batch (Free + Starter)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "Monthly quota insufficient for batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/audits/{request_id}": {
      "get": {
        "tags": [
          "Audit"
        ],
        "operationId": "getAuditLog",
        "summary": "Retrieve a past response by request_id",
        "description": "Returns the full response envelope for a previous validate, decide, or batch call. Records are retained for 7 days (Starter), 30 days (Pro), or 90 days (Business). Free plan keys always return 404.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "The `meta.request_id` value from the original API response.",
              "example": "019d917e-4fa4-766e-9e0f-d977b47bf2c6"
            },
            "required": true,
            "name": "request_id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Audit record found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "Record not found, expired, or belongs to a different key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/webhooks": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "createWebhook",
        "summary": "Register a webhook endpoint",
        "description": "Registers an HTTPS URL to receive signed webhook events. The `secret` is returned once — store it securely. Requires Pro or Business plan.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookCreateBody"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook endpoint registered",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid URL or webhook limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "402": {
            "description": "Plan does not include webhooks — Pro or Business required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "listWebhooks",
        "summary": "List registered webhook endpoints",
        "description": "Returns all webhook endpoints for the authenticated key. Secrets are never returned.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of registered endpoints",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookListResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "402": {
            "description": "Plan does not include webhooks — Pro or Business required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/webhooks/{id}": {
      "delete": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "deleteWebhook",
        "summary": "Delete a webhook endpoint",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "example": "019d917e-4fa4-766e-9e0f-d977b47bf2c6"
            },
            "required": true,
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "204": {
            "description": "Endpoint deleted"
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "402": {
            "description": "Plan does not include webhooks — Pro or Business required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "Endpoint not found or belongs to a different key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/webhooks/{id}/test": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "testWebhook",
        "summary": "Fire a test event to a registered endpoint",
        "description": "Delivers a `test` event directly (bypasses the delivery queue) so you can verify your endpoint is reachable.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "example": "019d917e-4fa4-766e-9e0f-d977b47bf2c6"
            },
            "required": true,
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Test event delivered",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookTestResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "402": {
            "description": "Plan does not include webhooks — Pro or Business required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "Endpoint not found or belongs to a different key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {}
}