openapi: 3.1.0
info:
  title: vatcheckapi
  version: "2"
  summary: VAT number validation, EU VAT registration lookup, EORI number checks, IBAN validation and e-invoice validation (XRechnung, ZUGFeRD / Factur-X).
  description: >-
    vatcheckapi validates VAT numbers (format and checksum) and looks up their
    registration details. It also checks EORI numbers of the EU member states,
    Northern Ireland (XI) and Great Britain (GB) against their official
    registers, validates IBANs and, for some countries, returns the bank from
    the national central bank's directory, and validates e-invoices
    (XRechnung, ZUGFeRD / Factur-X, EN 16931) against the official rule sets.
    All endpoints are served over HTTPS and return JSON. Authenticate every
    request with your API key, either as the `apikey` query parameter or the
    `apikey` request header.


    `HEAD` answers 405 (`method_not_allowed`; `Allow` names the methods the
    endpoint takes) on every billed endpoint, without running or billing it.
    `/v2/status` and the other free endpoints answer it like `GET`.


    This document is generated from the vatcheckapi service implementation and is
    the machine-readable source of truth for the v2 REST API. A human-readable
    version is available at https://vatcheckapi.com/docs.
  contact:
    name: vatcheckapi support
    email: support@vatcheckapi.com
servers:
  - url: https://api.vatcheckapi.com
    description: Production
security:
  - ApiKeyQuery: []
  - ApiKeyHeader: []
tags:
  - name: Validation
    description: Single VAT number validation.
  - name: Rates
    description: VAT rates of the EU member states and the UK, a price calculator and the whole table.
  - name: EORI
    description: EORI number checks (EU member states, Northern Ireland and Great Britain).
  - name: IBAN
    description: IBAN validation and bank lookup in national central bank directories.
  - name: E-Invoice
    description: Technical validation of XRechnung, ZUGFeRD / Factur-X and EN 16931 e-invoices.
  - name: Metadata
    description: Account status and VIES availability.
paths:
  /v2/check:
    get:
      tags: [Validation]
      summary: Check a VAT number
      operationId: check
      description: >-
        Validates a VAT number's format and checksum and returns its
        registration information: name and address as the register publishes
        them. EU and XI (Northern Ireland) numbers are checked in VIES, the
        European Commission's VAT register service; GB numbers against the UK
        register. Every check asks the register again (no cache). The country
        code may be supplied separately or prefixed on the VAT number (e.g.
        `LU26375245`). Spaces, dots and dashes are removed, lower case is
        accepted, and Greece is accepted as `EL` or `GR` (answered as `EL`).


        Send your own EU VAT number as `requester_vat_number` to get a VIES
        consultation number (`registration_info.consultation_number`), the
        proof that you checked the number at that time. It costs nothing extra.
        GB numbers get none (they are not checked through VIES).


        Cost: 1 request for every `200`, also for a number with an invalid
        format or checksum (no register is asked then). `422` and `503`
        answers are not billed; sandbox keys cost 0. A check retries VIES
        within a deadline of about 55 seconds and answers `503` if VIES does
        not answer by then: use a client timeout of at least 60 seconds.


        Sandbox API keys never ask a register: every number with a valid
        format and checksum is registered to `GOOGLE IRELAND LIMITED`, except
        `ATU00000006`, which is not registered. With a requester, the
        consultation number is `WAPI0000000SANDBOX` (null for GB numbers).
      parameters:
        - name: vat_number
          in: query
          required: true
          description: >-
            The VAT number to check, with or without the two-letter country
            prefix. Spaces, dots and dashes are removed and lower case is
            accepted (`lu 2637-5245` is `LU26375245`). Greece's prefix is `EL`;
            `GR` is accepted too.
          schema: { type: string }
          example: "LU26375245"
        - name: country_code
          in: query
          required: false
          description: >-
            Two-letter country code. Required if the VAT number is not prefixed
            with it; ignored when it is. One of the 29 supported codes: the EU
            member states (Greece uses its VAT code `EL`; `GR` is accepted and
            answered as `EL`) plus `GB` and `XI` (Northern Ireland). Case does
            not matter. Any other value fails validation with a 422.
          schema: { type: string }
          example: "LU"
        - name: requester_vat_number
          in: query
          required: false
          description: >-
            Your own EU VAT number (the 27 member states or `XI`) with its
            country prefix, e.g. `ATU63611700`. VIES then returns a
            consultation number in `registration_info.consultation_number`. It
            is checked locally first: a number without prefix, a GB number or
            an invalid format or checksum fails with a 422 before VIES is
            asked. Normalised like `vat_number`. At most 32 characters. No
            extra cost.
          schema: { type: string, maxLength: 32 }
          example: "ATU63611700"
      responses:
        '200':
          description: >-
            VAT validation result. Costs 1 request, also when the format or
            checksum is invalid (0 for sandbox keys).
          headers:
            X-RateLimit-Remaining-Quota-Month: { $ref: '#/components/headers/RateLimitRemainingQuotaMonth' }
            X-Cost: { $ref: '#/components/headers/Cost' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VatCheckResult' }
              examples:
                registered:
                  summary: Registered, with a consultation number (requester_vat_number sent)
                  value:
                    country_code: "LU"
                    vat_number: "26375245"
                    format_valid: true
                    checksum_valid: true
                    registration_info:
                      is_registered: true
                      name: "AMAZON EUROPE CORE S.A R.L."
                      address: "38, AVENUE JOHN F. KENNEDY\nL-1855  LUXEMBOURG"
                      address_parts: null
                      consultation_number: "WAPIAAAAZ3x9Q1bk"
                      checked_at: "2026-10-17T09:30:00.000000Z"
                    registration_info_history: []
                changed:
                  summary: Registered, the name changed since an earlier check
                  value:
                    country_code: "DE"
                    vat_number: "123456789"
                    format_valid: true
                    checksum_valid: true
                    registration_info:
                      is_registered: true
                      name: "EXAMPLE GMBH"
                      address: "MUSTERSTRASSE 1\n10115 BERLIN"
                      address_parts: null
                      consultation_number: null
                      checked_at: "2026-10-17T09:30:00.000000Z"
                    registration_info_history:
                      - is_registered: true
                        name: "EXAMPLE UG"
                        address: "MUSTERSTRASSE 1\n10115 BERLIN"
                        checked_at: "2025-03-02T08:15:41.000000Z"
                        created_at: "2026-10-17 09:30:00"
                invalidFormat:
                  summary: Invalid format, no register was asked (billed)
                  value:
                    country_code: "DE"
                    vat_number: "123"
                    format_valid: false
                    checksum_valid: false
                    registration_info:
                      is_registered: false
                      name: null
                      address: null
                      address_parts: null
                      consultation_number: null
                      checked_at: null
                    registration_info_history: []
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422':
          description: >-
            Not billed. A parameter is missing or invalid: `vat_number`
            (missing or not a string: generic body with `info`),
            `country_code` (missing for a number without prefix, or not
            supported), `requester_vat_number` (not a string, too long, not an
            EU VAT number with prefix, or invalid format or checksum); for
            these `message` is the first error and there is no `info`. Or VIES
            rejected the request itself (`INVALID_INPUT` for the VAT number,
            `INVALID_REQUESTER_INFO` for the requester): a bare `message`,
            and sending it again gives the same answer. A number with an
            invalid format is not a 422 but a billed 200 with `format_valid:
            false`.
          content:
            application/json:
              schema:
                anyOf:
                  - { $ref: '#/components/schemas/Error' }
                  - { $ref: '#/components/schemas/ValidationError' }
              examples:
                missingVatNumber:
                  summary: vat_number is missing
                  value:
                    message: "Validation error"
                    errors: { vat_number: ["The vat number field is required."] }
                    info: "For more information, see documentation: https://vatcheckapi.com/docs/status-codes#_422"
                missingCountryCode:
                  summary: A number without prefix and no country_code
                  value:
                    message: "The country code field is required."
                    errors: { country_code: ["The country code field is required."] }
                unsupportedCountryCode:
                  summary: country_code is not supported
                  value:
                    message: "The selected country code is invalid."
                    errors: { country_code: ["The selected country code is invalid."] }
                requesterNotEu:
                  summary: requester_vat_number is not an EU VAT number with prefix
                  value:
                    message: "The requester VAT number must be an EU VAT number with its country prefix, for example ATU12345678."
                    errors: { requester_vat_number: ["The requester VAT number must be an EU VAT number with its country prefix, for example ATU12345678."] }
                requesterInvalid:
                  summary: requester_vat_number has an invalid format or checksum
                  value:
                    message: "The requester VAT number is not a valid AT VAT number."
                    errors: { requester_vat_number: ["The requester VAT number is not a valid AT VAT number."] }
                viesRejectedInput:
                  summary: VIES rejected the VAT number as invalid input
                  value: { message: "VIES rejected the VAT number as invalid input." }
                viesRejectedRequester:
                  summary: VIES rejected the requester VAT number
                  value: { message: "VIES rejected the requester VAT number. Check requester_vat_number." }
                invalidVatNumber:
                  summary: The VAT number could not be validated
                  value: { message: "Invalid VAT number." }
        '429': { $ref: '#/components/responses/RateLimited' }
        '503':
          description: >-
            VIES, the member state's register or the GB data service is not
            available, or did not answer within the deadline of about 55
            seconds (retries included). Also answered at once, without asking
            VIES, while VIES reports the member state or VIES itself as
            unavailable (see `GET /v2/vies-status`). Not billed. Retry later.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
              example: { message: "The country's VAT validation service is currently not available. Please check again later." }
  /v2/vies-status:
    get:
      tags: [Metadata]
      summary: VIES availability per member state
      operationId: getViesStatus
      description: >-
        Whether VIES and the VAT register of each member state can be checked
        right now, as VIES's own status report says. We read it every minute
        and use a reading for 5 minutes at most; after that everything is
        `unknown`. `unavailable` means VAT checks for that country (every EU
        and XI check when `vies` is `unavailable`) answer 503 at once, without
        asking VIES; a 503 is not billed. GB is not included: UK numbers are
        not checked through VIES. Free (`X-Cost: 0`); needs your API key.
      responses:
        '200':
          description: VIES availability. Costs nothing.
          headers:
            X-Cost: { $ref: '#/components/headers/Cost' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ViesStatus' }
              example:
                checked_at: "2026-10-17T09:30:00Z"
                vies: "available"
                countries:
                  AT: "available"
                  BE: "available"
                  BG: "available"
                  CY: "available"
                  CZ: "available"
                  DE: "unavailable"
                  DK: "available"
                  EE: "available"
                  EL: "available"
                  ES: "available"
                  FI: "available"
                  FR: "available"
                  HR: "available"
                  HU: "available"
                  IE: "available"
                  IT: "available"
                  LT: "available"
                  LU: "available"
                  LV: "available"
                  MT: "available"
                  NL: "available"
                  PL: "available"
                  PT: "available"
                  RO: "available"
                  SE: "available"
                  SI: "available"
                  SK: "available"
                  XI: "available"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /v2/rates:
    get:
      tags: [Rates]
      summary: VAT rates of a country
      operationId: getVatRates
      description: >-
        The VAT rates of an EU member state or the UK on a date (today by
        default): standard, reduced, super-reduced, parking and regional
        rates, and every rate with the goods and services it applies to (TEDB
        categories, CN and CPA codes, the member state's comment). EU rates
        come from the European Commission's Taxes in Europe Database (TEDB,
        CC BY 4.0), imported daily with the changes announced for the next 90
        days; GB rates are kept by hand from HMRC's guidance (`source.id`
        `manual`). Pass `country_code`, or `ip` to take the country an IP
        address is located in. Reference data, not tax advice. Cost: 1
        request; `422` and `503` are not billed.
      parameters:
        - $ref: '#/components/parameters/RatesCountryCode'
        - $ref: '#/components/parameters/RatesIp'
        - $ref: '#/components/parameters/RatesAsOf'
      responses:
        '200':
          description: The country's rates on `as_of`. Costs 1 request.
          headers:
            X-RateLimit-Remaining-Quota-Month: { $ref: '#/components/headers/RateLimitRemainingQuotaMonth' }
            X-Cost: { $ref: '#/components/headers/Cost' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VatRates' }
              example:
                country_code: "AT"
                as_of: "2026-10-17"
                valid_from: "2026-07-01"
                valid_to: null
                standard_rate: 20.0
                reduced_rates: [10.0, 13.0]
                super_reduced_rates: [4.9]
                parking_rates: []
                regional_rates:
                  - rate: 19.0
                    comment: "Jungholz, Mittelberg"
                rates:
                  - type: "super_reduced"
                    rate: 4.9
                    category: "FOODSTUFFS"
                    category_description: "Foodstuffs (including beverages but excluding alcoholic beverages) for human and animal consumption; ..."
                    cn_codes:
                      - code: "0401 10"
                        description: "Of a fat content, by weight, not exceeding 1 %"
                    cpa_codes: null
                    comment: "From July 1, 2026, the tax rate of 4.9% applies to the foodstuffs listed in Annex 3 to Sec. 10 of the Austrian VAT Act 1994."
                  - type: "standard"
                    rate: 20.0
                    category: null
                    category_description: null
                    cn_codes: null
                    cpa_codes: null
                    comment: null
                source:
                  id: "tedb"
                  name: "European Commission, Taxes in Europe Database (TEDB)"
                  url: "https://ec.europa.eu/taxation_customs/tedb/"
                  licence: "CC BY 4.0"
                  attribution: "European Commission TEDB, CC BY 4.0"
                last_updated: "2026-10-17T04:40:00Z"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422':
          description: >-
            Not billed. `country_code` and `ip` are both missing,
            `country_code` is not an EU member state's VAT prefix or `GB`,
            `ip` is not an IP address or is located elsewhere or nowhere
            known, or `as_of` is not `YYYY-MM-DD` or before the earliest rates
            held for the country.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ValidationError' }
              examples:
                ipElsewhere:
                  summary: The IP address is outside the EU and the UK
                  value:
                    message: "The IP address is located in US: there are VAT rates for the EU member states and GB only."
                    errors: { ip: ["The IP address is located in US: there are VAT rates for the EU member states and GB only."] }
                tooEarly:
                  summary: as_of is before the earliest rates held
                  value:
                    message: "There are no rates for AT before 2026-07-01, the earliest date we hold."
                    errors: { as_of: ["There are no rates for AT before 2026-07-01, the earliest date we hold."] }
        '429': { $ref: '#/components/responses/RateLimited' }
        '503': { $ref: '#/components/responses/RatesUnavailable' }
  /v2/rates/price:
    get:
      tags: [Rates]
      summary: Work out a price with VAT
      operationId: calculateVatPrice
      description: >-
        Net, VAT and gross of an amount at a country's rate on a date: the
        standard rate by default, or the reduced, super-reduced or parking
        rate (with `category` where the country has several). The VAT of a
        net amount and the net of a gross amount are rounded half up to the
        cent; the third amount is the difference. Takes the parameters of
        `getVatRates`. Cost: 1 request; `422` (also for an ambiguous or
        missing rate) and `503` are not billed.
      parameters:
        - $ref: '#/components/parameters/RatesCountryCode'
        - $ref: '#/components/parameters/RatesIp'
        - $ref: '#/components/parameters/RatesAsOf'
        - name: amount
          in: query
          required: true
          description: The amount, at least 0, with at most two decimals (`100`, `99.95`). The currency does not matter.
          schema: { type: string, pattern: '^\d{1,13}(\.\d{1,2})?$' }
          example: "99.99"
        - name: amount_type
          in: query
          required: false
          description: "`net` (default): the amount is without VAT. `gross`: it includes VAT."
          schema: { type: string, enum: [net, gross], default: net }
        - name: rate_type
          in: query
          required: false
          description: The rate to apply.
          schema: { type: string, enum: [standard, reduced, super_reduced, parking], default: standard }
        - name: category
          in: query
          required: false
          description: >-
            The TEDB category to take the rate of (e.g. `ACCOMMODATION`; see
            `rates[].category` of `getVatRates`). Needed when the country has
            several rates of `rate_type`. Case does not matter.
          schema: { type: string, maxLength: 64 }
      responses:
        '200':
          description: The amounts. Costs 1 request.
          headers:
            X-RateLimit-Remaining-Quota-Month: { $ref: '#/components/headers/RateLimitRemainingQuotaMonth' }
            X-Cost: { $ref: '#/components/headers/Cost' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VatPrice' }
              example:
                country_code: "AT"
                as_of: "2026-10-17"
                rate_type: "standard"
                category: null
                rate: 20.0
                amount_type: "gross"
                net_amount: 83.33
                vat_amount: 16.66
                gross_amount: 99.99
                valid_from: "2026-07-01"
                source:
                  id: "tedb"
                  name: "European Commission, Taxes in Europe Database (TEDB)"
                  url: "https://ec.europa.eu/taxation_customs/tedb/"
                  licence: "CC BY 4.0"
                  attribution: "European Commission TEDB, CC BY 4.0"
                last_updated: "2026-10-17T04:40:00Z"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422':
          description: >-
            Not billed. A parameter is invalid (see `getVatRates`; `amount`
            is not a number with at most two decimals, `amount_type` or
            `rate_type` is unknown), or the rate is ambiguous or missing.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ValidationError' }
              examples:
                ambiguous:
                  summary: Several reduced rates and no category
                  value:
                    message: "AT has 2 reduced rates (10, 13). Pass category to choose one (see GET /v2/rates)."
                    errors: { category: ["AT has 2 reduced rates (10, 13). Pass category to choose one (see GET /v2/rates)."] }
                missing:
                  summary: The country has no rate of that type
                  value:
                    message: "AT has no parking rate."
                    errors: { rate_type: ["AT has no parking rate."] }
        '429': { $ref: '#/components/responses/RateLimited' }
        '503': { $ref: '#/components/responses/RatesUnavailable' }
  /v2/rates/table:
    get:
      tags: [Rates]
      summary: Download every country's VAT rates
      operationId: downloadVatRatesTable
      x-mcp-exclude: true
      description: >-
        Every country's rates on `as_of` (today by default) in one download:
        JSON (a list of `getVatRates` answers) or CSV (one row per rate,
        codes separated by spaces, each row with its source's attribution).
        Free (`X-Cost: 0`); needs your API key. When you republish the EU
        rates, name the source: "European Commission TEDB, CC BY 4.0".
      parameters:
        - name: format
          in: query
          required: false
          schema: { type: string, enum: [json, csv], default: json }
        - $ref: '#/components/parameters/RatesAsOf'
      responses:
        '200':
          description: The table. Costs nothing.
          headers:
            X-Cost: { $ref: '#/components/headers/Cost' }
          content:
            application/json:
              schema:
                type: object
                properties:
                  as_of: { type: string, format: date }
                  attribution: { type: string }
                  countries:
                    type: array
                    items: { $ref: '#/components/schemas/VatRates' }
                required: [as_of, attribution, countries]
            text/csv:
              schema: { type: string }
              example: |
                country_code,valid_from,valid_to,type,rate,category,category_description,cn_codes,cpa_codes,comment,source,last_updated
                AT,2026-07-01,,standard,20,,,,,,"European Commission TEDB, CC BY 4.0",2026-10-17T04:40:00Z
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422':
          description: "`format` or `as_of` is invalid. Not billed."
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '503': { $ref: '#/components/responses/RatesUnavailable' }
  /v2/eori:
    get:
      tags: [EORI]
      summary: Check an EORI number
      operationId: checkEori
      description: >-
        Checks an EORI (Economic Operators Registration and Identification)
        number. The format is checked first. A number with a valid format is
        then looked up in its official register: GB numbers with HMRC's public
        "Check an EORI number" API, EU and XI (Northern Ireland) numbers with
        the European Commission's EORI validation service. Name and address
        are only returned when the trader agreed to publish them, so a
        registered number may come without them. A number with an invalid
        format is answered without a lookup (`format_valid: false`) and counts
        like any other check. Results are cached for up to 1 hour (10 minutes
        for numbers that are not registered); a cached answer keeps the
        `checked_at` of the lookup it came from. Uncached GB lookups are paced
        to HMRC's rate limit, about one per second per account. A `503` is not
        counted against your quota. For a GB number it usually means this
        pacing, and the response then has `Retry-After: 1`: wait one second
        and retry, and check lists of GB numbers one at a time, not in
        parallel. A `503` without `Retry-After` means the register is down or
        slow; retry a little later.


        Sandbox API keys never query a register and cost nothing. A number
        with a valid format gets a fixed answer chosen by its last character:
        `8` or `9` is not registered; `6` or `7` is registered without name
        and address; any other character is registered to a fictional trader
        (`SANDBOX TRADING LTD`, London, for GB numbers; `Sandbox Trading GmbH`,
        Berlin, for EU and XI numbers). An invalid format is answered as with
        a live key.
      parameters:
        - name: eori_number
          in: query
          required: true
          description: >-
            The EORI number, with its two-letter country prefix (e.g.
            `DE4204891`), or without any country code when `country_code` names
            the country. Spaces, invisible characters (such as zero-width
            spaces), dots, dashes and slashes are ignored and lower case is
            accepted. At most 64 characters.
          schema: { type: string, maxLength: 64 }
          example: "DE4204891"
        - name: country_code
          in: query
          required: false
          description: >-
            Two-letter country code, put in front of an EORI number given
            without any country code. Ignored when the number starts with a
            supported code. A number that starts with another country's code
            (such as `EL` or `US`) is not completed and fails validation with a
            422. When it is used, it must be one of the 29 supported codes: the
            EU member states (Greece is `GR` in EORI numbers, not `EL` as in
            VAT numbers) plus `GB` and `XI` (Northern Ireland); any other value
            then fails validation with a 422. When sent, it must be a string.
          schema: { type: string }
          example: "DE"
      responses:
        '200':
          description: EORI check result.
          headers:
            X-RateLimit-Remaining-Quota-Month: { $ref: '#/components/headers/RateLimitRemainingQuotaMonth' }
            X-Cost: { $ref: '#/components/headers/Cost' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EoriCheckResult' }
              examples:
                registered:
                  summary: Registered, name and address published
                  value:
                    country_code: "DE"
                    eori_number: "DE4204891"
                    format_valid: true
                    registration_info:
                      is_registered: true
                      name: "Friedrich-Alexander-Universität Erlangen-Nürnberg"
                      address: "Freyeslebenstr. 1\n91058 Erlangen\nGermany"
                      address_parts:
                        street: "Freyeslebenstr. 1"
                        postcode: "91058"
                        city: "Erlangen"
                        country: "Germany"
                      checked_at: "2026-10-04T19:04:07Z"
                    source: "eu_eos"
                registeredWithoutDetails:
                  summary: Registered, the trader did not agree to publish name and address
                  value:
                    country_code: "GB"
                    eori_number: "GB220430231000"
                    format_valid: true
                    registration_info:
                      is_registered: true
                      name: null
                      address: null
                      address_parts: null
                      checked_at: "2026-10-04T19:04:25Z"
                    source: "hmrc"
                invalidFormat:
                  summary: Invalid format, no register was asked
                  value:
                    country_code: "GB"
                    eori_number: "GB1234567890001"
                    format_valid: false
                    registration_info:
                      is_registered: false
                      name: null
                      address: null
                      address_parts: null
                      checked_at: null
                    source: null
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422':
          description: >-
            `eori_number` is missing, not a string or longer than 64
            characters; `country_code` is not a string; or the number does not
            start with a supported country code: it starts with another
            country's code (such as `EL` or `US`), or it has none and
            `country_code` names no supported one. Not counted against your
            quota.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ValidationError' }
              example:
                message: "Validation error"
                errors:
                  country_code: ["The EORI number must start with a supported country code: AT, BE, BG, CY, CZ, DE, DK, EE, ES, FI, FR, GR, HR, HU, IE, IT, LT, LU, LV, MT, NL, PL, PT, RO, SE, SI, SK, XI, GB (Greece is GR in EORI numbers). For a number without a country code, country_code must name one of them."]
                info: "For more information, see documentation: https://vatcheckapi.com/docs/status-codes#_422"
        '429': { $ref: '#/components/responses/RateLimited' }
        '503':
          description: >-
            The register for this number (HMRC for GB, the European Commission
            for EU and XI) did not answer in time or is failing, or, for GB
            numbers, HMRC's rate limit is used up for the moment (HMRC allows a
            few requests per second for all our customers together, and each
            account gets about one uncached GB lookup per second). Not counted
            against your quota. When the `Retry-After` header is present, retry
            after that many seconds; otherwise retry a little later.
          headers:
            Retry-After:
              description: >-
                Only present when the register's rate limit is the reason: the
                GB lookups available right now are used up, or the register
                asked us to slow down. Seconds to wait before retrying, currently
                always 1. Absent when the register is down or did not answer in
                time.
              schema: { type: integer, minimum: 1 }
              example: 1
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
              example: { message: "The EORI validation service is currently not available. Please check again later." }
  /v2/iban:
    get:
      tags: [IBAN]
      summary: Validate an IBAN
      operationId: checkIban
      description: >-
        Checks that an IBAN is well formed, in this order: allowed characters,
        a country of the SWIFT IBAN Registry (ISO 13616), the country's length
        and BBAN structure, the ISO 7064 MOD 97-10 check digits and, where a
        public algorithm exists, the country's own check digits (for Germany
        the Bundesbank check digit method of the bank code). Returns the IBAN's
        parts and, for DE, AT, CH, LI, BE and CZ, the bank from the national
        central bank's directory. An IBAN that fails a check is a 200 with
        `valid: false` and the first failed check in `reason`. A valid IBAN
        does not prove that the account exists, is open, or who holds it. No
        bank or other third party is contacted. Costs 1 request whether the
        IBAN is valid or not (0 for sandbox keys). The IBAN is part of the
        request URL; to validate several IBANs, use `POST /v2/iban/batch`,
        which takes them in the request body.
      parameters:
        - name: iban
          in: query
          required: true
          description: >-
            The IBAN in electronic (`DE89370400440532013000`) or print format
            (`DE89 3704 0044 0532 0130 00`). Spaces and lower case are
            accepted. At most 64 characters of UTF-8 text.
          schema: { type: string, minLength: 1, maxLength: 64 }
          example: "DE89370400440532013000"
      responses:
        '200':
          description: >-
            Validation result. An IBAN that fails a check is a 200 with
            `valid: false` and the first failed check in `reason`; it costs 1
            request like a valid one.
          headers:
            X-RateLimit-Remaining-Quota-Month: { $ref: '#/components/headers/RateLimitRemainingQuotaMonth' }
            X-Cost: { $ref: '#/components/headers/Cost' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/IbanCheckResponse' }
              examples:
                valid:
                  summary: A valid German IBAN with its bank
                  value:
                    iban: "DE89370400440532013000"
                    iban_print_format: "DE89 3704 0044 0532 0130 00"
                    valid: true
                    reason: null
                    checks: { length: true, structure: true, checksum: true, national_checksum: true }
                    country_code: "DE"
                    sepa: true
                    bban: "370400440532013000"
                    bank_code: "37040044"
                    branch_code: null
                    account_number: "0532013000"
                    bank:
                      name: "Commerzbank"
                      bic: "COBADEFFXXX"
                      city: "Köln"
                      source: "Quelle: Deutsche Bundesbank"
                    notice: "A valid IBAN is well formed and has correct check digits. It does not prove that the account exists, is open, or who holds it."
                invalidChecksum:
                  summary: Wrong check digits; the parts and the bank are still returned
                  value:
                    iban: "DE88370400440532013000"
                    iban_print_format: "DE88 3704 0044 0532 0130 00"
                    valid: false
                    reason: "invalid_checksum"
                    checks: { length: true, structure: true, checksum: false, national_checksum: null }
                    country_code: "DE"
                    sepa: true
                    bban: "370400440532013000"
                    bank_code: "37040044"
                    branch_code: null
                    account_number: "0532013000"
                    bank:
                      name: "Commerzbank"
                      bic: "COBADEFFXXX"
                      city: "Köln"
                      source: "Quelle: Deutsche Bundesbank"
                    notice: "A valid IBAN is well formed and has correct check digits. It does not prove that the account exists, is open, or who holds it."
                invalidLength:
                  summary: A partly typed IBAN
                  value:
                    iban: "DE89"
                    iban_print_format: "DE89"
                    valid: false
                    reason: "invalid_length"
                    checks: { length: false, structure: false, checksum: false, national_checksum: null }
                    country_code: "DE"
                    sepa: true
                    bban: null
                    bank_code: null
                    branch_code: null
                    account_number: null
                    bank: null
                    notice: "A valid IBAN is well formed and has correct check digits. It does not prove that the account exists, is open, or who holds it."
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422':
          description: >-
            The `iban` parameter is missing or empty, not a string, longer than
            64 characters or not valid UTF-8. Not counted against your quota.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ValidationError' }
              examples:
                missing:
                  summary: No IBAN sent
                  value:
                    message: "Validation error"
                    errors: { iban: ["The iban field is required."] }
                    info: "For more information, see documentation: https://vatcheckapi.com/docs/status-codes#_422"
                notUtf8:
                  summary: Bytes that are not UTF-8, e.g. a Latin-1 non-breaking space
                  value:
                    message: "Validation error"
                    errors: { iban: ["The iban must be valid UTF-8 text."] }
                    info: "For more information, see documentation: https://vatcheckapi.com/docs/status-codes#_422"
        '429': { $ref: '#/components/responses/RateLimited' }
  /v2/iban/batch:
    post:
      tags: [IBAN]
      summary: Validate up to 100 IBANs
      operationId: checkIbanBatch
      description: >-
        Validates up to 100 IBANs in one request, with the same checks and bank
        lookup as `GET /v2/iban`. The IBANs are normalised (spaces removed,
        upper case) and duplicates removed before the limit of 100 is checked;
        the list may hold up to 1,000 entries before that. The result is keyed
        by the normalised IBAN, in the order of first occurrence, and the
        `notice` is sent once. Costs 1 request per unique IBAN, valid or not (0
        for sandbox keys). The batch is checked against your remaining quota
        before it runs: if its cost would use up the remaining quota it is
        refused with a 429 that carries `quota.required` and the code of the
        quota that runs short, and nothing is processed or billed. The IBANs are read from the request body only (a
        JSON body, or a form-encoded one); `ibans` may also be one
        comma-separated string. An `ibans` parameter in the query string is
        refused with a 422.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/IbanBatchRequest' }
            example:
              ibans: ["DE89 3704 0044 0532 0130 00", "DE88370400440532013000", "de89370400440532013000"]
      responses:
        '200':
          description: One result per unique IBAN.
          headers:
            X-RateLimit-Remaining-Quota-Month: { $ref: '#/components/headers/RateLimitRemainingQuotaMonth' }
            X-Cost: { $ref: '#/components/headers/Cost' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/IbanBatchResponse' }
              example:
                data:
                  DE89370400440532013000:
                    iban: "DE89370400440532013000"
                    iban_print_format: "DE89 3704 0044 0532 0130 00"
                    valid: true
                    reason: null
                    checks: { length: true, structure: true, checksum: true, national_checksum: true }
                    country_code: "DE"
                    sepa: true
                    bban: "370400440532013000"
                    bank_code: "37040044"
                    branch_code: null
                    account_number: "0532013000"
                    bank: { name: "Commerzbank", bic: "COBADEFFXXX", city: "Köln", source: "Quelle: Deutsche Bundesbank" }
                  DE88370400440532013000:
                    iban: "DE88370400440532013000"
                    iban_print_format: "DE88 3704 0044 0532 0130 00"
                    valid: false
                    reason: "invalid_checksum"
                    checks: { length: true, structure: true, checksum: false, national_checksum: null }
                    country_code: "DE"
                    sepa: true
                    bban: "370400440532013000"
                    bank_code: "37040044"
                    branch_code: null
                    account_number: "0532013000"
                    bank: { name: "Commerzbank", bic: "COBADEFFXXX", city: "Köln", source: "Quelle: Deutsche Bundesbank" }
                notice: "A valid IBAN is well formed and has correct check digits. It does not prove that the account exists, is open, or who holds it."
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Your plan does not include batch requests. Not counted against your quota.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
              example:
                message: "You are not allowed to use the batch endpoint, please upgrade your plan"
                error:
                  code: "plan_upgrade_required"
                  message: "You are not allowed to use the batch endpoint, please upgrade your plan"
                actions:
                  upgrade: "https://app.vatcheckapi.com/upgrade?utm_source=api_error&utm_campaign=plan_upgrade_required&team=7123456789012345678"
                  docs: "https://vatcheckapi.com/docs/openapi.yaml"
        '422':
          description: >-
            `ibans` is missing or empty, holds more than 100 unique IBANs (or
            more than 1,000 entries), holds an entry that is not a string of
            UTF-8 text with at most 64 characters, or was sent in the query
            string. An invalid entry is reported under its position in the
            list as sent, counting from 0. Not counted against your quota.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ValidationError' }
              examples:
                tooMany:
                  summary: More than 100 unique IBANs
                  value:
                    message: "Validation error"
                    errors: { ibans: ["A batch can contain at most 100 IBANs."] }
                    info: "For more information, see documentation: https://vatcheckapi.com/docs/status-codes#_422"
                invalidEntry:
                  summary: An entry that is not a string, and one that is too long
                  value:
                    message: "Validation error"
                    errors:
                      ibans.1: ["The ibans.1 field must be a string."]
                      ibans.2: ["The ibans.2 field must not be greater than 64 characters."]
                    info: "For more information, see documentation: https://vatcheckapi.com/docs/status-codes#_422"
                queryString:
                  summary: IBANs sent in the query string
                  value:
                    message: "Validation error"
                    errors: { ibans: ["The ibans field is required.", "Send the IBANs in the request body, not in the query string."] }
                    info: "For more information, see documentation: https://vatcheckapi.com/docs/status-codes#_422"
        '429': { $ref: '#/components/responses/InsufficientQuota' }
  /v2/einvoice/validate:
    post:
      tags: [E-Invoice]
      summary: Validate an e-invoice
      operationId: validateEinvoice
      description: >-
        Checks an e-invoice file against the official rule sets and lists every
        error and warning with its rule id: XML well-formedness, the XML schema,
        the EN 16931 business rules and the national XRechnung rules, and for a
        ZUGFeRD / Factur-X PDF also PDF/A-3 conformance and the embedded invoice
        file. Validated: XRechnung 3.0 (UBL and CII, also CVD and the
        Extension), EN 16931 (UBL and CII), and ZUGFeRD / Factur-X PDFs with
        the EN 16931 or XRECHNUNG profile. Other profiles (MINIMUM, BASIC WL,
        BASIC, EXTENDED, EXTENDED-CTC-FR), ZUGFeRD 1.0, XRechnung versions other
        than 3.0, the XRechnung 3.0 Extension as a UBL credit note and Peppol
        BIS are recognised and answered with the error `UNSUPPORTED_PROFILE`,
        free of charge.


        Send the invoice as the raw request body (`Content-Type:
        application/xml` or `application/pdf`), as the multipart field `file`,
        or base64-encoded in the JSON property `content_base64` (as the MCP tool
        does). At most 10 MB after decoding; the limit also applies to the
        invoice XML inside a PDF (`EMBEDDED_XML_TOO_LARGE`, free). Invoices with
        more than 50 VAT breakdowns or more than 1,000 document level allowances
        and charges are not validated (`INVOICE_TOO_COMPLEX`, free). Invoices
        are processed transiently and never persisted.


        An invalid invoice is a normal result: status 200 with `valid: false`.
        An XML file costs 1 request, also when it is not well-formed or not an
        e-invoice. A ZUGFeRD / Factur-X PDF whose invoice was validated (XML
        rules and PDF/A) costs 2; a PDF without readable invoice XML costs 1.
        `UNSUPPORTED_PROFILE`, `EMBEDDED_XML_TOO_LARGE` and
        `INVOICE_TOO_COMPLEX` results are free, and so are rejected input (422)
        and an unavailable validation service (503). On the free plan the cost
        also counts against the minute rate limit (10 requests; a PDF uses 2).
        Rule set messages keep their original language, given in
        `message_language` (EN 16931, schema and PDF/A messages English,
        national XRechnung rules German). Sandbox keys get fixed rule set
        results and cost nothing. Technical validation only, not tax or legal
        advice.
      parameters:
        - name: format
          in: query
          required: false
          description: >-
            The format you expect. The invoice is always validated against the
            rules its own specification identifier (BT-24) names; when it
            declares another format, the response gets the error
            `FORMAT_MISMATCH`. XRechnung and ZUGFeRD / Factur-X invoices also
            count as `en16931`, and an EN 16931 CII invoice also counts as
            `zugferd`. `auto` (the default) checks nothing.
          schema: { type: string, enum: [auto, xrechnung, zugferd, en16931], default: auto }
        - name: language
          in: query
          required: false
          description: >-
            Language of the API's own messages (e.g. `NO_EINVOICE_XML`) and of
            the disclaimer. Rule set messages keep their original language (see
            `message_language`).
          schema: { type: string, enum: [en, de], default: en }
      requestBody:
        required: true
        description: The invoice file, XML or PDF, at most 10 MB.
        content:
          application/json:
            schema: { $ref: '#/components/schemas/EinvoiceUpload' }
            example:
              content_base64: "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPEludm9pY2UgeG1sbnM9InVybjpvYXNpczpuYW1lczpzcGVjaWZpY2F0aW9uOnVibDpzY2hlbWE6eHNkOkludm9pY2UtMiIvPgo="
              filename: "invoice.xml"
          application/xml:
            schema: { type: string, description: "The invoice XML (XRechnung or EN 16931, UBL or CII)." }
          text/xml:
            schema: { type: string, description: The invoice XML. }
          application/pdf:
            schema: { type: string, format: binary, description: A ZUGFeRD / Factur-X PDF with the embedded invoice XML. }
          multipart/form-data:
            schema:
              type: object
              properties:
                file: { type: string, format: binary, description: "The invoice file, XML or PDF." }
              required: [file]
      responses:
        '200':
          description: >-
            The validation result. `valid` is false for an invalid invoice; the
            status is still 200.
          headers:
            X-RateLimit-Remaining-Quota-Month: { $ref: '#/components/headers/RateLimitRemainingQuotaMonth' }
            X-Cost: { $ref: '#/components/headers/Cost' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EinvoiceValidation' }
              examples:
                invalidXrechnung:
                  summary: XRechnung 3.0 (UBL) with a business rule error
                  value:
                    valid: false
                    format: "xrechnung"
                    syntax: "UBL"
                    profile: "XRECHNUNG"
                    version: "3.0"
                    container: "xml"
                    specification_identifier: "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0"
                    scenario: "EN16931 XRechnung (UBL Invoice)"
                    ruleset_version: "xrechnung-3.0.2+cfg-2026-08-31;en16931-1.3.16;xrechnung-schematron-2.6.0;kosit-1.6.3;verapdf-1.30.2"
                    pdfa: null
                    errors:
                      - rule_id: "BR-DE-15"
                        severity: "error"
                        message: "Das Element \"Buyer reference\" (BT-10) muss übermittelt werden."
                        message_language: "de"
                        source: "business_rules"
                        location: "/ubl:Invoice[1]"
                        line: null
                        column: null
                    warnings:
                      - rule_id: "BR-DE-TMP-32"
                        severity: "information"
                        message: "Eine Rechnung sollte zur Angabe des Liefer-/Leistungsdatums entweder BT-72 \"Actual delivery date\", BG-14 \"Invoicing period\" oder in jeder Rechnungsposition BG-26 \"Invoice line period\" enthalten."
                        message_language: "de"
                        source: "business_rules"
                        location: "/ubl:Invoice[1]"
                        line: null
                        column: null
                    summary:
                      invoice_number: "123456XX"
                      issue_date: "2016-04-04"
                      type_code: "380"
                      currency: "EUR"
                      seller: { name: "[Seller name]", vat_id: "DE 123456789" }
                      buyer: { name: "[Buyer name]" }
                      totals: { net_amount: "314.86", tax_amount: "22.04", gross_amount: "336.9", payable_amount: "336.9" }
                    language: "en"
                    disclaimer: "Technical validation against the rule sets listed in ruleset_version. It is not tax or legal advice."
                validZugferdPdf:
                  summary: Valid ZUGFeRD / Factur-X PDF, profile EN 16931 (costs 2)
                  value:
                    valid: true
                    format: "zugferd"
                    syntax: "CII"
                    profile: "EN 16931"
                    version: "1.0"
                    container: "pdf"
                    specification_identifier: "urn:cen.eu:en16931:2017"
                    scenario: "EN16931 (CII)"
                    ruleset_version: "xrechnung-3.0.2+cfg-2026-08-31;en16931-1.3.16;xrechnung-schematron-2.6.0;kosit-1.6.3;verapdf-1.30.2"
                    pdfa: { compliant: true, profile: "PDF/A-3B" }
                    errors: []
                    warnings: []
                    summary:
                      invoice_number: "123456XX"
                      issue_date: "2016-04-04"
                      type_code: "380"
                      currency: "EUR"
                      seller: { name: "[Seller name]", vat_id: "DE 123456789" }
                      buyer: { name: "[Buyer name]" }
                      totals: { net_amount: "314.86", tax_amount: "22.04", gross_amount: "336.9", payable_amount: "336.9" }
                    language: "en"
                    disclaimer: "Technical validation against the rule sets listed in ruleset_version. It is not tax or legal advice."
                pdfWithoutInvoice:
                  summary: PDF without an embedded invoice XML (costs 1)
                  value:
                    valid: false
                    format: null
                    syntax: null
                    profile: null
                    version: null
                    container: "pdf"
                    specification_identifier: null
                    scenario: null
                    ruleset_version: null
                    pdfa: { compliant: null, profile: null }
                    errors:
                      - rule_id: "NO_EINVOICE_XML"
                        severity: "error"
                        message: "No e-invoice XML found: the PDF has no embedded ZUGFeRD, Factur-X or XRechnung XML file."
                        message_language: "en"
                        source: "container"
                        location: null
                        line: null
                        column: null
                    warnings: []
                    summary: null
                    language: "en"
                    disclaimer: "Technical validation against the rule sets listed in ruleset_version. It is not tax or legal advice."
                unsupportedProfile:
                  summary: Recognised but unsupported profile (free)
                  value:
                    valid: false
                    format: "zugferd"
                    syntax: "CII"
                    profile: "BASIC"
                    version: "1.0"
                    container: "xml"
                    specification_identifier: "urn:cen.eu:en16931:2017#compliant#urn:factur-x.eu:1p0:basic"
                    scenario: null
                    ruleset_version: null
                    pdfa: null
                    errors:
                      - rule_id: "UNSUPPORTED_PROFILE"
                        severity: "error"
                        message: "ZUGFeRD / Factur-X BASIC is recognised but not supported yet, so its rules were not checked."
                        message_language: "en"
                        source: "input"
                        location: null
                        line: null
                        column: null
                    warnings: []
                    summary:
                      invoice_number: "123456XX"
                      issue_date: "2016-04-04"
                      type_code: "380"
                      currency: "EUR"
                      seller: { name: "[Seller name]", vat_id: "DE 123456789" }
                      buyer: { name: "[Buyer name]" }
                      totals: { net_amount: "314.86", tax_amount: "22.04", gross_amount: "336.9", payable_amount: "336.9" }
                    language: "en"
                    disclaimer: "Technical validation against the rule sets listed in ruleset_version. It is not tax or legal advice."
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: >-
            Your plan does not include e-invoice validation, or another reason
            for a 403 (e.g. the referrer whitelist of your API key). Not billed.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
              example:
                message: "E-invoice validation is not included in your plan. Please upgrade your plan."
                error:
                  code: "plan_upgrade_required"
                  message: "E-invoice validation is not included in your plan. Please upgrade your plan."
                actions:
                  upgrade: "https://app.vatcheckapi.com/upgrade?utm_source=api_error&utm_campaign=plan_upgrade_required&team=7123456789012345678"
                  docs: "https://vatcheckapi.com/docs/openapi.yaml"
        '422':
          description: >-
            The invoice is missing, is neither an XML file nor a PDF, is larger
            than 10 MB, `content_base64` is not valid base64, or `format`,
            `language` or `filename` is invalid. The errors are listed under
            `file` for a raw body or multipart upload and under
            `content_base64` for JSON. Not billed.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ValidationError' }
              examples:
                notAnInvoiceFile:
                  summary: Neither XML nor PDF
                  value:
                    message: "Validation error"
                    errors: { file: ["The invoice must be an XML file (XRechnung, EN 16931) or a PDF (ZUGFeRD / Factur-X)."] }
                    info: "For more information, see documentation: https://vatcheckapi.com/docs/status-codes#_422"
                invalidBase64:
                  summary: content_base64 is not valid base64
                  value:
                    message: "Validation error"
                    errors: { content_base64: ["content_base64 is not valid base64."] }
                    info: "For more information, see documentation: https://vatcheckapi.com/docs/status-codes#_422"
        '429':
          description: >-
            Your remaining quota cannot pay for this request (checked before any
            work: 1 request for an XML file, 2 for a PDF; `quota.required` names
            the cost), your monthly quota is used up, or the free plan's minute
            rate limit is reached. For a quota error, `error.code` names the
            quota that runs short: `quota_exceeded`, `grace_quota_exceeded` or
            `overage_quota_exceeded`. Not billed.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
              example:
                message: "This request needs 2 requests, but your quota only allows 1 more. Please upgrade your plan at https://app.vatcheckapi.com/upgrade"
                error:
                  code: "quota_exceeded"
                  message: "This request needs 2 requests, but your quota only allows 1 more. Please upgrade your plan at https://app.vatcheckapi.com/upgrade"
                quota:
                  limit: 1000
                  used: 998
                  remaining: 2
                  resets_at: "2026-11-01T00:00:00+00:00"
                  required: 2
                actions:
                  upgrade: "https://app.vatcheckapi.com/upgrade?utm_source=api_error&utm_campaign=quota_exceeded"
                  docs: "https://vatcheckapi.com/docs/openapi.yaml"
        '503':
          description: >-
            The validation service is down, busy or did not finish in time;
            retry later. Not billed.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
              example: { message: "The e-invoice validation service is currently not available. Please try again later." }
  /v2/status:
    get:
      tags: [Metadata]
      summary: Account quota status
      operationId: getStatus
      description: >-
        Returns your quota usage and the plan of your API key's account, so you
        can check that an upgrade took effect. Does not count against your
        quota.
      responses:
        '200':
          description: Current quota usage and plan.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StatusResponse' }
              example:
                account_id: 313373133731337
                account_id_str: "313373133731337"
                quotas:
                  month: { total: 150, used: 72, remaining: 78 }
                  grace: { total: 0, used: 0, remaining: 0 }
                plan:
                  name: "free"
                  interval: "month"
                  price_id: "price_1LDnBAKszEJd98nkp0nv1E7e"
                  free: true
                  custom: false
                  status: "active"
                  renews_at: "2026-11-01T00:00:00+00:00"
                  scheduled: null
                  upgrade_url: "https://app.vatcheckapi.com/upgrade?utm_source=agent&utm_campaign=status&team=313373133731337"
                  plans_url: "https://api.vatcheckapi.com/v1/agent/plans"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
components:
  parameters:
    RatesCountryCode:
      name: country_code
      in: query
      required: false
      description: >-
        An EU member state's VAT prefix (Greece: `EL`; `GR` is accepted) or
        `GB`. Case does not matter. Required unless `ip` is sent.
      schema: { type: string }
      example: "AT"
    RatesIp:
      name: ip
      in: query
      required: false
      description: >-
        Instead of `country_code`: an IPv4 or IPv6 address, for the rates of
        the country it is located in (for example your customer's).
      schema: { type: string }
      example: "91.115.1.1"
    RatesAsOf:
      name: as_of
      in: query
      required: false
      description: "The date the rates are for, `YYYY-MM-DD`. Default: today (UTC)."
      schema: { type: string, format: date }
      example: "2026-10-17"
  securitySchemes:
    ApiKeyQuery: { type: apiKey, in: query, name: apikey, description: "API key as the apikey query parameter." }
    ApiKeyHeader: { type: apiKey, in: header, name: apikey, description: "API key as the apikey request header (recommended)." }
  headers:
    RateLimitRemainingQuotaMonth:
      description: >-
        Remaining requests in your monthly quota. Attached on every plan; while
        a temporary grace quota is active (after a failed payment) it is
        replaced by `X-RateLimit-Remaining-Grace-Month`. You can also monitor
        your quota with `GET /v2/status`.
      schema: { type: integer }
      example: 78
    Cost:
      description: Requests this call counted against your quota. Always 0 for sandbox API keys.
      schema: { type: integer }
      example: 1
  responses:
    Unauthorized:
      description: >-
        The API key is missing or invalid: every request needs one, in the
        `apikey` header or query parameter. Without a key the message is "No
        API key found in request" (`error.code` `missing_api_key`), with an
        unknown key "Unauthorized" (`invalid_api_key`). `actions.sign_up`
        creates an account with a free API key. `actions` can also carry
        `agent_setup` (setup steps for AI coding agents), `pricing` (the plans
        as JSON) and `openapi`; `docs` then points to the docs' llms.txt
        (example `missing_api_key_agent_links`).
      headers:
        WWW-Authenticate:
          description: Always `Key`.
          schema: { type: string }
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
          examples:
            missing_api_key:
              summary: No API key sent
              value:
                message: "No API key found in request"
                error: { code: "missing_api_key", message: "No API key found in request" }
                actions:
                  sign_up: "https://app.vatcheckapi.com/register?utm_source=api_error&utm_campaign=missing_api_key"
                  docs: "https://vatcheckapi.com/docs/openapi.yaml"
            invalid_api_key:
              summary: Unknown API key
              value:
                message: "Unauthorized"
                error: { code: "invalid_api_key", message: "Unauthorized" }
                actions:
                  sign_up: "https://app.vatcheckapi.com/register?utm_source=api_error&utm_campaign=invalid_api_key"
                  docs: "https://vatcheckapi.com/docs/openapi.yaml"
            missing_api_key_agent_links:
              summary: No API key sent, with the links for AI coding agents
              value:
                message: "No API key found in request"
                error: { code: "missing_api_key", message: "No API key found in request" }
                actions:
                  agent_setup: "https://vatcheckapi.com/agents.md"
                  sign_up: "https://app.vatcheckapi.com/register?utm_source=api_error&utm_campaign=missing_api_key"
                  pricing: "https://api.vatcheckapi.com/v1/agent/plans"
                  docs: "https://vatcheckapi.com/docs/llms.txt"
                  openapi: "https://vatcheckapi.com/docs/openapi.yaml"
    RateLimited:
      description: >-
        Your quota is used up, or you exceeded the free plan's minute rate
        limit. `error.code` says which: `quota_exceeded` (monthly quota),
        `grace_quota_exceeded` (grace quota after a failed payment) or
        `overage_quota_exceeded` (overage budget), each with the `quota`
        object; `rate_limit_exceeded` with the message "API rate limit
        exceeded" and no `quota` object for the minute limit. The request that
        uses the last unit of a quota is still served; the next one gets this
        429. A 429 is not billed. `actions` can also carry `pricing` (the plans as
        JSON) and `openapi`; `docs` then points to the docs' llms.txt (the
        examples ending in `_agent_links`).
      headers:
        Retry-After:
          description: >-
            Seconds until the next full minute, with the requests-per-minute
            `rate_limit_exceeded` of an API key. A used-up quota has none: it
            lasts until `quota.resets_at`.
          schema: { type: integer }
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
          examples:
            quota_exceeded:
              summary: The month's requests are used up
              value:
                message: "You used all your monthly requests. Please upgrade your plan at https://app.vatcheckapi.com/upgrade"
                error: { code: "quota_exceeded", message: "You used all your monthly requests. Please upgrade your plan at https://app.vatcheckapi.com/upgrade" }
                quota: { limit: 150, used: 150, remaining: 0, resets_at: "2026-11-01T00:00:00+00:00" }
                actions:
                  upgrade: "https://app.vatcheckapi.com/upgrade?utm_source=api_error&utm_campaign=quota_exceeded&team=7123456789012345678"
                  docs: "https://vatcheckapi.com/docs/openapi.yaml"
            rate_limit_exceeded:
              summary: The requests per minute are used up
              value:
                message: "API rate limit exceeded"
                error: { code: "rate_limit_exceeded", message: "API rate limit exceeded" }
                actions:
                  upgrade: "https://app.vatcheckapi.com/upgrade?utm_source=api_error&utm_campaign=rate_limit_exceeded&team=7123456789012345678"
                  docs: "https://vatcheckapi.com/docs/openapi.yaml"
            quota_exceeded_agent_links:
              summary: The month's requests are used up, with the links for AI coding agents
              value:
                message: "You used all your monthly requests. Please upgrade your plan at https://app.vatcheckapi.com/upgrade"
                error: { code: "quota_exceeded", message: "You used all your monthly requests. Please upgrade your plan at https://app.vatcheckapi.com/upgrade" }
                quota: { limit: 150, used: 150, remaining: 0, resets_at: "2026-11-01T00:00:00+00:00" }
                actions:
                  upgrade: "https://app.vatcheckapi.com/upgrade?utm_source=api_error&utm_campaign=quota_exceeded&team=7123456789012345678"
                  pricing: "https://api.vatcheckapi.com/v1/agent/plans"
                  docs: "https://vatcheckapi.com/docs/llms.txt"
                  openapi: "https://vatcheckapi.com/docs/openapi.yaml"
            rate_limit_exceeded_agent_links:
              summary: The requests per minute are used up, with the links for AI coding agents
              value:
                message: "API rate limit exceeded"
                error: { code: "rate_limit_exceeded", message: "API rate limit exceeded" }
                actions:
                  upgrade: "https://app.vatcheckapi.com/upgrade?utm_source=api_error&utm_campaign=rate_limit_exceeded&team=7123456789012345678"
                  pricing: "https://api.vatcheckapi.com/v1/agent/plans"
                  docs: "https://vatcheckapi.com/docs/llms.txt"
                  openapi: "https://vatcheckapi.com/docs/openapi.yaml"
    Forbidden:
      description: >-
        The request is not allowed. `error.code` says why:
        `referrer_not_allowed` (the request's referrer is not on your API
        key's whitelist), `key_not_allowed_for_product` (the key belongs to
        another EverAPI product) or `email_not_verified` (a free account whose
        email address is not verified yet used the 5 requests it gets until
        then; `actions.verify_email` links to the verification, and the full
        free quota applies within 30 seconds of verifying). Not billed.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    InsufficientQuota:
      description: >-
        The request costs more than your remaining quota allows, or your quota
        or the free plan's minute limit is used up. A batch refused for its
        cost carries `quota.required` (its cost) and the code of the quota that
        runs short: `quota_exceeded` (monthly quota), `grace_quota_exceeded`
        (grace quota after a failed payment) or `overage_quota_exceeded`
        (overage budget). Nothing was processed or billed. Retry with fewer
        IBANs, or upgrade your plan.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
          example:
            message: "This request needs 3 requests, but your quota only allows 2 more. Please upgrade your plan at https://app.vatcheckapi.com/upgrade"
            error:
              code: "quota_exceeded"
              message: "This request needs 3 requests, but your quota only allows 2 more. Please upgrade your plan at https://app.vatcheckapi.com/upgrade"
            quota:
              limit: 1000
              used: 997
              remaining: 3
              resets_at: "2026-11-01T00:00:00+00:00"
              required: 3
            actions:
              upgrade: "https://app.vatcheckapi.com/upgrade?utm_source=api_error&utm_campaign=quota_exceeded"
              docs: "https://vatcheckapi.com/docs/openapi.yaml"
    RatesUnavailable:
      description: >-
        No rates are held for the country (the daily import has not run yet),
        or the IP address lookup failed. Not billed. Retry later.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
          example: { message: "VAT rates are currently not available. Please check again later." }
  schemas:
    VatCheckResult:
      type: object
      properties:
        country_code:
          type: string
          description: The country prefix of the number (`EL` for Greece, also when sent as `GR`; `XI` for Northern Ireland).
          example: "LU"
        vat_number:
          type: string
          description: The number as checked, without prefix, spaces, dots and dashes, in upper case.
          example: "26375245"
        format_valid:
          type: boolean
          description: Whether the number has the country's VAT number format.
        checksum_valid:
          type: boolean
          description: >-
            Whether the check digits are correct, for countries that have them.
            When this or `format_valid` is false, no register was asked.
        registration_info:
          type: object
          properties:
            is_registered:
              type: boolean
              description: Whether the register knows the number as a valid VAT number. False when the format or checksum is invalid.
            name:
              type: [string, "null"]
              description: The registered name; null when not registered or not published.
              example: "AMAZON EUROPE CORE S.A R.L."
            address:
              type: [string, "null"]
              description: The registered address, lines separated by `\n`; null when not registered or not published.
              example: "38, AVENUE JOHN F. KENNEDY\nL-1855  LUXEMBOURG"
            address_parts:
              type: [object, "null"]
              description: Reserved for a split address. Currently always null.
              additionalProperties: true
            consultation_number:
              type: [string, "null"]
              description: >-
                The VIES consultation number of this check, the proof that you
                checked the number at this time. Only with
                `requester_vat_number`; null without it, for GB numbers (not
                checked through VIES), for an invalid format or checksum, and
                when VIES returns none. Sandbox keys get `WAPI0000000SANDBOX`.
              example: "WAPIAAAAZ3x9Q1bk"
            checked_at:
              type: [string, "null"]
              format: date-time
              description: >-
                When this check asked the register (UTC, with microseconds).
                Null when the format or checksum is invalid. Sandbox keys get
                the time of the request.
              example: "2026-10-17T09:30:00.000000Z"
          required: [is_registered, name, address, address_parts, consultation_number, checked_at]
        registration_info_history:
          type: array
          description: >-
            Earlier states of this number, newest first: one entry each time
            its name, address or registration status changed between two
            checks made through vatcheckapi. Empty when nothing changed, for
            an invalid format or checksum, and for sandbox keys.
          items: { $ref: '#/components/schemas/VatRegistrationHistoryEntry' }
      required: [country_code, vat_number, format_valid, checksum_valid, registration_info, registration_info_history]
    VatRateSource:
      type: object
      description: Where the rates come from.
      properties:
        id: { type: string, enum: [tedb, manual], description: "`tedb`: the European Commission's TEDB. `manual`: kept by hand from `url` (GB)." }
        name: { type: string }
        url: { type: string, format: uri }
        licence: { type: [string, "null"], description: "`CC BY 4.0` for TEDB." }
        attribution: { type: string, description: The credit to show when you republish the rates. }
      required: [id, name, url, licence, attribution]
    VatRates:
      type: object
      properties:
        country_code: { type: string, description: "The country (`EL` for Greece)." }
        as_of: { type: string, format: date, description: The date the rates are for. }
        valid_from: { type: string, format: date, description: "Since when this set of rates applies (the date of the country's latest change)." }
        valid_to: { type: [string, "null"], format: date, description: The last day this set applies when a change is announced. }
        standard_rate: { type: [number, "null"], description: The standard rate in percent. }
        reduced_rates: { type: array, items: { type: number }, description: "The distinct reduced rates, lowest first (regional rates not included)." }
        super_reduced_rates: { type: array, items: { type: number } }
        parking_rates: { type: array, items: { type: number } }
        regional_rates:
          type: array
          description: Rates for particular regions; `comment` names them.
          items:
            type: object
            properties:
              rate: { type: number }
              comment: { type: [string, "null"] }
            required: [rate, comment]
        rates:
          type: array
          description: Every rate with what it applies to.
          items: { $ref: '#/components/schemas/VatRate' }
        source: { $ref: '#/components/schemas/VatRateSource' }
        last_updated: { type: string, format: date-time, description: When we last got these rates from the source (UTC). }
      required: [country_code, as_of, valid_from, valid_to, standard_rate, reduced_rates, super_reduced_rates, parking_rates, regional_rates, rates, source, last_updated]
    VatRate:
      type: object
      properties:
        type:
          type: string
          description: "`exempted`: 0 %, exempt with the right to deduct (zero-rated)."
          enum: [standard, reduced, super_reduced, parking, exempted, not_applicable, out_of_scope]
        rate: { type: number, description: The rate in percent. }
        category: { type: [string, "null"], description: "TEDB's category (`FOODSTUFFS`, `ACCOMMODATION`, `REGION`, ...); null for the standard rate." }
        category_description: { type: [string, "null"] }
        cn_codes:
          type: [array, "null"]
          description: The goods the rate applies to, as Combined Nomenclature codes.
          items: { $ref: '#/components/schemas/VatRateCode' }
        cpa_codes:
          type: [array, "null"]
          description: The services the rate applies to, as CPA codes.
          items: { $ref: '#/components/schemas/VatRateCode' }
        comment: { type: [string, "null"], description: "The member state's note, as plain text." }
      required: [type, rate, category, category_description, cn_codes, cpa_codes, comment]
    VatRateCode:
      type: object
      properties:
        code: { type: string, example: "0401 10" }
        description: { type: [string, "null"] }
      required: [code, description]
    VatPrice:
      type: object
      properties:
        country_code: { type: string }
        as_of: { type: string, format: date }
        rate_type: { type: string, enum: [standard, reduced, super_reduced, parking] }
        category: { type: [string, "null"], description: "The category the rate was taken for, in upper case." }
        rate: { type: number, description: "The rate applied, in percent." }
        amount_type: { type: string, enum: [net, gross] }
        net_amount: { type: number }
        vat_amount: { type: number }
        gross_amount: { type: number }
        valid_from: { type: string, format: date }
        source: { $ref: '#/components/schemas/VatRateSource' }
        last_updated: { type: string, format: date-time }
      required: [country_code, as_of, rate_type, category, rate, amount_type, net_amount, vat_amount, gross_amount, valid_from, source, last_updated]
    VatRegistrationHistoryEntry:
      type: object
      properties:
        is_registered:
          type: [boolean, "null"]
          description: The registration status before the change.
        name: { type: [string, "null"], description: "The name before the change." }
        address: { type: [string, "null"], description: "The address before the change." }
        checked_at:
          type: [string, "null"]
          format: date-time
          description: When that earlier state was first seen (UTC, with microseconds).
          example: "2025-03-02T08:15:41.000000Z"
        created_at:
          type: string
          description: When the change was recorded, `YYYY-MM-DD HH:MM:SS` in UTC (not ISO 8601).
          example: "2026-10-17 09:30:00"
      required: [is_registered, name, address, checked_at, created_at]
    ViesStatus:
      type: object
      properties:
        checked_at:
          type: [string, "null"]
          format: date-time
          description: When VIES's status was last read (UTC). Null when there is no reading from the last 5 minutes.
          example: "2026-10-17T09:30:00Z"
        vies:
          type: string
          enum: [available, unavailable, unknown]
          description: VIES as a whole. While `unavailable`, every EU and XI check answers 503 (not billed).
        countries:
          type: object
          description: >-
            One entry per country VIES checks: the 27 member states (Greece as
            `EL`) and `XI`, 28 in all. `available`: VIES reports the register
            as working. `unavailable`: checks for this country answer 503 at
            once, without asking VIES (not billed). `unknown`: VIES reports no
            status for it, or there is no reading from the last 5 minutes.
          additionalProperties:
            type: string
            enum: [available, unavailable, unknown]
      required: [checked_at, vies, countries]
    EoriCheckResult:
      type: object
      properties:
        country_code:
          type: string
          description: The country prefix of the number (`GR` for Greece, `XI` for Northern Ireland).
          example: "DE"
        eori_number:
          type: string
          description: The normalised EORI number, including its country prefix.
          example: "DE4204891"
        format_valid: { type: boolean }
        registration_info:
          type: object
          properties:
            is_registered: { type: boolean }
            name:
              type: [string, "null"]
              description: Null when the register published no name (the trader did not agree to publish it).
              example: "Friedrich-Alexander-Universität Erlangen-Nürnberg"
            address:
              type: [string, "null"]
              description: >-
                The published address, one line each for the street, the
                postcode and city, and the country. Null when the register
                published no address.
              example: "Freyeslebenstr. 1\n91058 Erlangen\nGermany"
            address_parts:
              type: [object, "null"]
              description: The address as the register publishes it; null when it publishes none.
              properties:
                street: { type: [string, "null"] }
                postcode: { type: [string, "null"] }
                city: { type: [string, "null"] }
                country:
                  type: [string, "null"]
                  description: Country name as the register writes it (the European Commission writes it in English; HMRC sends none).
              required: [street, postcode, city, country]
            checked_at:
              type: [string, "null"]
              format: date-time
              description: When the register was asked. Null when the format is invalid.
              example: "2026-10-04T19:04:07Z"
          required: [is_registered, name, address, address_parts, checked_at]
        source:
          type: [string, "null"]
          description: >-
            The register that answered: `hmrc` (GB numbers) or `eu_eos` (EU and
            XI numbers, European Commission). Null when the format is invalid.
          example: "eu_eos"
      required: [country_code, eori_number, format_valid, registration_info, source]
    StatusResponse:
      type: object
      properties:
        account_id: { type: integer, example: 313373133731337 }
        account_id_str: { type: string, description: "The same id as `account_id`, as a string for JavaScript clients, whose numbers lose precision above 2^53.", example: "313373133731337" }
        quotas:
          type: object
          description: >-
            `month`: your plan's monthly quota. `grace`: a temporary allowance
            (e.g. while a payment is being completed), all zero unless active;
            while it is active, requests count against it instead.
          properties:
            month: { $ref: '#/components/schemas/QuotaBucket' }
            grace: { $ref: '#/components/schemas/QuotaBucket' }
          required: [month]
        plan:
          type: object
          description: The plan of the API key's account, so you can check that an upgrade took effect.
          properties:
            name: { type: [string, "null"], example: "free" }
            interval: { type: [string, "null"], example: "month" }
            price_id: { type: [string, "null"], example: "price_1LDnBAKszEJd98nkp0nv1E7e" }
            free: { type: [boolean, "null"], example: true }
            custom:
              type: boolean
              description: A plan made for this account only; it has no `upgrade_url`.
              example: false
            status:
              type: [string, "null"]
              description: The status of the subscription, e.g. `active` or `past_due`.
              example: "active"
            renews_at: { type: [string, "null"], format: date-time, example: "2026-11-01T00:00:00+00:00" }
            scheduled:
              type: [object, "null"]
              description: A plan change that starts later, e.g. a downgrade at the end of the period.
              properties:
                name: { type: [string, "null"], example: "small" }
                interval: { type: [string, "null"], example: "month" }
                starts_at: { type: string, format: date-time }
            upgrade_url:
              type: [string, "null"]
              format: uri
              description: Opens the plans of this account. `null` for a custom plan.
            plans_url:
              type: string
              format: uri
              description: Every plan as JSON.
              example: "https://api.vatcheckapi.com/v1/agent/plans"
      required: [quotas]
    QuotaBucket:
      type: object
      properties:
        total: { type: integer, example: 150 }
        used: { type: integer, example: 72 }
        remaining: { type: integer, example: 78 }
    IbanResult:
      type: object
      properties:
        iban:
          type: string
          description: The IBAN in electronic format, with all whitespace removed and in upper case.
          example: "DE89370400440532013000"
        iban_print_format:
          type: [string, "null"]
          description: Groups of four characters. Null when `reason` is `invalid_characters`.
          example: "DE89 3704 0044 0532 0130 00"
        valid:
          type: boolean
          description: >-
            True when every check passed. A `national_checksum` of null does not
            make an IBAN invalid.
        reason:
          type: [string, "null"]
          description: >-
            The first check that failed; null when the IBAN is valid. One of
            `invalid_characters` (something other than A-Z and 0-9 once spaces
            are removed), `unsupported_country` (the first two characters are
            not a country of the IBAN Registry), `invalid_length` (wrong length
            for the country, also a partly typed IBAN such as `DE89`),
            `invalid_structure` (the check digits are not digits, or the BBAN
            does not match the country's structure), `invalid_checksum` (the
            ISO 7064 MOD 97-10 check digits are wrong; 00, 01 and 99 are never
            valid) or `invalid_national_checksum` (the country's own check
            digits inside the BBAN are wrong).
          example: null
        checks:
          type: object
          description: >-
            The checks run in order. After the first failure the remaining
            checks are not run and report false (`national_checksum` reports
            null).
          properties:
            length: { type: boolean, description: "The IBAN has the length of its country." }
            structure: { type: boolean, description: "The check digits are digits and the BBAN matches the country's structure in the IBAN Registry." }
            checksum: { type: boolean, description: "The ISO 7064 MOD 97-10 check digits are correct (02 to 98)." }
            national_checksum:
              type: [boolean, "null"]
              description: >-
                The country's own check digits inside the BBAN. Null when no
                algorithm is applied for the country (for example AT, CH, NL or
                GB), when the account has no check digit to verify, for a German
                IBAN whose bank code is not in the Bundesbank directory, or when
                an earlier check failed.
          required: [length, structure, checksum, national_checksum]
        country_code:
          type: [string, "null"]
          description: >-
            The first two characters, when they are letters. Null when the IBAN
            has characters other than A-Z and 0-9.
          example: "DE"
        sepa:
          type: [boolean, "null"]
          description: >-
            The country takes part in SEPA, according to the IBAN Registry. Null
            when the country is not in the registry or the IBAN has invalid
            characters.
          example: true
        bban:
          type: [string, "null"]
          description: >-
            The Basic Bank Account Number: the IBAN without country code and
            check digits. Set once the length and structure checks pass, also
            when the check digits are wrong.
          example: "370400440532013000"
        bank_code:
          type: [string, "null"]
          description: The bank identifier as the IBAN Registry defines it for the country (in Germany the Bankleitzahl).
          example: "37040044"
        branch_code:
          type: [string, "null"]
          description: The branch identifier, for countries where the IBAN Registry defines one (for example ES, IT or GB).
          example: null
        account_number:
          type: [string, "null"]
          description: >-
            The BBAN without the bank and branch identifiers. In some countries
            it also holds national check digits: in IT and SM it starts with
            the CIN check character, which comes before the bank code in the
            BBAN, and in ES with the two control digits, which come before the
            10-digit account number.
          example: "0532013000"
        bank:
          description: >-
            The bank from the national bank code directory, for DE, AT, CH,
            LI, BE and CZ. Null for other countries, for bank codes that
            are not in the directory, and when the length or structure check
            failed. Sandbox keys get a placeholder instead.
          oneOf:
            - { $ref: '#/components/schemas/IbanBank' }
            - { type: "null" }
      required: [iban, iban_print_format, valid, reason, checks, country_code, sepa, bban, bank_code, branch_code, account_number, bank]
    IbanBank:
      type: object
      description: >-
        A bank as the national directory publishes it: Deutsche Bundesbank (DE),
        Oesterreichische Nationalbank (AT), SIX Interbank Clearing (CH and LI),
        National Bank of Belgium (BE) or Česká národní banka (CZ).
      properties:
        name: { type: string, example: "Commerzbank" }
        bic:
          type: [string, "null"]
          description: The BIC as the directory lists it; null when it lists none.
          example: "COBADEFFXXX"
        city:
          type: [string, "null"]
          description: The town as the directory lists it. Null for BE and CZ, whose directories list no town.
          example: "Köln"
        source:
          type: string
          description: >-
            The source, worded as the directory's terms of use require. Keep it
            with the bank data when you pass that data on.
          example: "Quelle: Deutsche Bundesbank"
      required: [name, bic, city, source]
    IbanCheckResponse:
      allOf:
        - { $ref: '#/components/schemas/IbanResult' }
        - type: object
          properties:
            notice:
              type: string
              description: States that a valid IBAN does not prove that the account exists or who holds it.
              example: "A valid IBAN is well formed and has correct check digits. It does not prove that the account exists, is open, or who holds it."
          required: [notice]
    IbanBatchRequest:
      type: object
      properties:
        ibans:
          type: array
          description: >-
            Up to 100 IBANs in electronic or print format. Duplicates (after
            removing spaces and upper-casing) count once. One comma-separated
            string is accepted too.
          minItems: 1
          maxItems: 100
          items: { type: string, minLength: 1, maxLength: 64 }
      required: [ibans]
    IbanBatchResponse:
      type: object
      properties:
        data:
          type: object
          description: One result per unique IBAN, keyed by the normalised IBAN, in the order of first occurrence.
          additionalProperties: { $ref: '#/components/schemas/IbanResult' }
        notice:
          type: string
          description: States that a valid IBAN does not prove that the account exists or who holds it.
      required: [data, notice]
    Error:
      type: object
      properties:
        message: { type: string }
        error:
          type: object
          description: A stable machine-readable error code and the message. Sent with 401, 403, 404 and 429.
          properties:
            code: { type: string, example: "quota_exceeded" }
            message: { type: string }
          required: [code, message]
        quota:
          type: object
          description: The current quota state. Sent with quota errors (429) only.
          properties:
            limit: { type: integer, example: 1000 }
            used: { type: integer, example: 998 }
            remaining: { type: integer, example: 2 }
            resets_at: { type: [string, "null"], format: date-time, example: "2026-11-01T00:00:00+00:00" }
            required:
              type: integer
              description: >-
                What the rejected request would have cost. Present when a
                request that costs more than what your quota still allows is
                refused before it runs (e.g. a PDF e-invoice, which costs 2).
              example: 2
        actions:
          type: object
          description: >-
            Next steps as absolute URLs, keyed by action. A key is only
            present when it applies to this error and is available for this
            product right now, so read the keys you know and ignore the
            others. `sign_up`: create an account with a free API key.
            `upgrade`: the plans of the API key's account (quota and plan
            errors). `complete_payment`: pay the open invoice (grace quota).
            `verify_email`: confirm the account's email address. `docs`: the
            documentation (always present). `openapi`: this specification.
            `pricing`: the plans as JSON. `agent_setup`: setup steps for AI
            coding agents. `get_free_api_key`, `get_trial_key`, `get_api_key`:
            endpoints that issue API keys to agents; `agent_setup` explains
            them.
            `enable_overage`: turn on overage for the account, so requests past
            the monthly quota are served and billed per request up to a budget
            (quota_exceeded of a paid plan that has overage, while it is off).
          additionalProperties: { type: string, format: uri }
      required: [message]
    ValidationError:
      type: object
      properties:
        message: { type: string, example: "Validation error" }
        errors:
          type: object
          additionalProperties: { type: array, items: { type: string } }
        info: { type: string }
      required: [message, errors]
    EinvoiceUpload:
      type: object
      description: The invoice file, base64-encoded, for clients that send JSON only (such as MCP tools).
      properties:
        content_base64:
          type: string
          contentEncoding: base64
          description: >-
            The whole invoice file (XML or PDF), base64-encoded. A data URL
            (`data:application/pdf;base64,...`) is accepted too. At most 10 MB
            after decoding.
          example: "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPEludm9pY2UgeG1sbnM9InVybjpvYXNpczpuYW1lczpzcGVjaWZpY2F0aW9uOnVibDpzY2hlbWE6eHNkOkludm9pY2UtMiIvPgo="
        filename:
          type: string
          maxLength: 255
          description: The original file name. Optional; the file type is detected from the content, not from the name.
          example: "invoice.xml"
      required: [content_base64]
    EinvoiceFinding:
      type: object
      description: One error, warning or information message.
      properties:
        rule_id:
          type: [string, "null"]
          description: >-
            The rule id: from a rule set (e.g. `BR-DE-15`, `BR-CO-10`, the XML
            schema's `cvc-complex-type.2.4.a`, the PDF/A rule `PDFA-6.6.2.1-1`)
            or one of the API's own codes (e.g. `NO_EINVOICE_XML`,
            `UNSUPPORTED_PROFILE`, `PDF_TOO_COMPLEX`, `HYBRID_AF_RELATIONSHIP`;
            see https://vatcheckapi.com/docs/einvoice). Null when a rule set
            reports a message without an id.
          example: "BR-DE-15"
        severity:
          type: string
          enum: [error, warning, information]
        message:
          type: string
          example: "Das Element \"Buyer reference\" (BT-10) muss übermittelt werden."
        message_language:
          type: string
          enum: [en, de]
          description: >-
            The language of `message`. Rule set messages keep their original
            language: the EN 16931 rules, XML schema and PDF/A messages are
            English, the national XRechnung rules (BR-DE-*, BR-DEX-*,
            BR-TMP-*) German. The API's own codes follow the `language`
            parameter.
        source:
          type: string
          enum: [input, xml, schema, business_rules, container, pdfa]
          description: >-
            Which check reported it: the request itself (`input`), XML
            well-formedness (`xml`), the XML schema (`schema`), the business
            rules of EN 16931 and XRechnung (`business_rules`), the PDF
            container with its embedded file and XMP metadata (`container`),
            or PDF/A conformance (`pdfa`).
        location:
          type: [string, "null"]
          description: >-
            XPath of the element in the invoice XML (e.g.
            `/ubl:Invoice[1]/cac:LegalMonetaryTotal[1]`), or the PDF object
            path for PDF/A findings. Null when there is none.
          example: "/ubl:Invoice[1]"
        line:
          type: [integer, "null"]
          description: Line in the invoice XML, for well-formedness and schema errors.
        column:
          type: [integer, "null"]
          description: Column in the invoice XML, for well-formedness and schema errors.
      required: [rule_id, severity, message, message_language, source, location, line, column]
    EinvoiceValidation:
      type: object
      properties:
        valid:
          type: boolean
          description: >-
            True when the rule sets accepted the invoice and no check reported
            an error; for a PDF, PDF/A conformance is required too. Warnings and
            information messages do not make an invoice invalid.
        format:
          type: [string, "null"]
          enum: [xrechnung, zugferd, en16931, peppol-bis, null]
          description: >-
            The format the invoice declares. `zugferd` covers ZUGFeRD and
            Factur-X, including a PDF whose CII invoice has the EN 16931 or
            XRECHNUNG profile. `en16931` is plain EN 16931 or another EN 16931
            specification. Null when the file is not an e-invoice the API
            recognises.
        syntax:
          type: [string, "null"]
          enum: [UBL, CII, null]
        profile:
          type: [string, "null"]
          description: >-
            XRECHNUNG, XRECHNUNG-EXTENSION, XRECHNUNG-CVD, EN 16931, MINIMUM,
            BASIC WL, BASIC, EXTENDED, EXTENDED-CTC-FR, BILLING (Peppol BIS),
            or BASIC, COMFORT or EXTENDED for ZUGFeRD 1.0. Null when unknown.
          example: "XRECHNUNG"
        version:
          type: [string, "null"]
          description: The version the invoice declares, e.g. `3.0` for XRechnung 3.0 or `2017` for EN 16931.
          example: "3.0"
        container:
          type: string
          enum: [xml, pdf]
          description: Whether the file sent was an XML file or a PDF.
        specification_identifier:
          type: [string, "null"]
          description: The specification identifier (BT-24) exactly as declared; null when there is none.
          example: "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0"
        scenario:
          type: [string, "null"]
          description: The validation scenario (rule set) that was applied; null when no rule set ran.
          example: "EN16931 XRechnung (UBL Invoice)"
        ruleset_version:
          type: [string, "null"]
          description: >-
            The pinned versions of the rule sets and engines that ran
            (XRechnung, EN 16931, KoSIT validator, veraPDF); `sandbox` for
            sandbox keys; null when no rule set ran.
          example: "xrechnung-3.0.2+cfg-2026-08-31;en16931-1.3.16;xrechnung-schematron-2.6.0;kosit-1.6.3;verapdf-1.30.2"
        pdfa:
          type: [object, "null"]
          description: Null for an XML file. For a PDF, the PDF/A-3 result.
          properties:
            compliant:
              type: [boolean, "null"]
              description: Null when PDF/A conformance was not checked (e.g. the PDF holds no invoice XML).
            profile:
              type: [string, "null"]
              description: The PDF/A profile checked against.
              example: "PDF/A-3B"
          required: [compliant, profile]
        errors:
          type: array
          description: Findings of severity `error`.
          items: { $ref: '#/components/schemas/EinvoiceFinding' }
        warnings:
          type: array
          description: Findings of severity `warning` and `information`.
          items: { $ref: '#/components/schemas/EinvoiceFinding' }
        summary:
          type: [object, "null"]
          description: >-
            Key facts read from the invoice XML, exactly as written there
            (amounts are strings in the invoice currency; CII dates are given
            as YYYY-MM-DD). Each value is null when the invoice does not have
            it; the whole summary is null when no UBL or CII invoice could be
            read.
          properties:
            invoice_number: { type: [string, "null"], description: Invoice number (BT-1). }
            issue_date: { type: [string, "null"], description: Issue date (BT-2). }
            type_code: { type: [string, "null"], description: "Invoice type code (BT-3), e.g. 380 for an invoice." }
            currency: { type: [string, "null"], description: Invoice currency (BT-5). }
            seller:
              type: object
              properties:
                name: { type: [string, "null"] }
                vat_id: { type: [string, "null"], description: Seller VAT identifier (BT-31). }
              required: [name, vat_id]
            buyer:
              type: object
              properties:
                name: { type: [string, "null"] }
              required: [name]
            totals:
              type: object
              properties:
                net_amount: { type: [string, "null"], description: Total without VAT (BT-109). }
                tax_amount: { type: [string, "null"], description: Total VAT in the invoice currency (BT-110). }
                gross_amount: { type: [string, "null"], description: Total with VAT (BT-112). }
                payable_amount: { type: [string, "null"], description: Amount due for payment (BT-115). }
              required: [net_amount, tax_amount, gross_amount, payable_amount]
          required: [invoice_number, issue_date, type_code, currency, seller, buyer, totals]
        language:
          type: string
          enum: [en, de]
          description: The `language` of the request.
        disclaimer:
          type: string
          description: Technical validation, not tax or legal advice, in the requested language.
      required: [valid, format, syntax, profile, version, container, specification_identifier, scenario, ruleset_version, pdfa, errors, warnings, summary, language, disclaimer]
