Response schemas

The VAT endpoints use snake_case, mirroring TEDB’s source naming; the VIES endpoint uses camelCase, mirroring the VIES SOAP response. This inconsistency is deliberate — each endpoint preserves its upstream’s conventions so users can correlate fields with the original docs.

For a machine-readable version, see the interactive API reference or fetch the spec directly at /openapi.json.

GET /rates and GET /rates/YYYY-MM-DD

{
  "version": "2026-05-27",          // situation-on date the rates apply to
  "source": "European Commission TEDB",
  "rates": {
    "DE": {
      "country": "Germany",
      "currency": "EUR",
      "flag": "https://flagcdn.com/de.svg",
      "standard": 19,               // percentage points, null if missing
      "reduced": [7],               // sorted ascending, may be empty
      "super_reduced": null,        // single rate or null
      "parking": null               // single rate or null
    }
    // ... one entry per EU-27 country with a STANDARD rate
  }
}

GET /changes

{
  "changes": [
    {
      "id": "rc_a1b2c3d4e5f6",         // stable id, dedupe-safe across retries
      "snapshotDate": "2026-05-30",    // date the change took effect
      "country": "HU",                  // ISO 3166-1 alpha-2
      "field": "standard",              // standard | super_reduced | parking | reduced[N]
      "old": 27,                        // previous value, null if rate didn't exist
      "new": 25,                        // current value, null if rate removed
      "detectedAt": "2026-05-30T07:00:23.000Z"
    }
  ],
  "count": 1,                           // number of rows returned (≤ limit)
  "limit": 50                           // effective limit applied
}

GET /changes/YYYY-MM-DD

{
  "snapshotDate": "2026-05-30",         // echoes the path param
  "changes": [
    // ... same shape as above, ordered by country then field
  ],
  "count": 0                            // 0 is a valid steady-state day
}

GET /fx and GET /fx/YYYY-MM-DD

{
  "date": "2026-05-27",             // ECB publication date
  "base": "EUR",
  "rates": {                        // currency → units per 1 EUR
    "USD": 1.085,
    "GBP": 0.84
    // ... sorted alphabetically
  }
}

GET /vies/{country}/{vat}

{
  "countryCode": "DE",              // echoed as caller spelt it (GR vs EL)
  "vatNumber": "123456789",
  "requestDate": "2026-05-27+02:00",// raw VIES timestamp incl. timezone
  "valid": true,
  "name": "Acme GmbH",              // null if VIES omitted or returned '---'
  "address": "Hauptstraße 1"        // null if VIES omitted or returned '---'
}

Errors

All error responses share the shape:

{ "error": "<code>" }

See Errors for the full list of codes and their HTTP status mappings.