{
  "openapi": "3.1.0",
  "info": {
    "title": "Validitool API",
    "version": "1.0.0",
    "description": "EU VAT (VIES) and EORI validation, UK EORI via HMRC, IBAN validation, sanctions screening (EU, UN, UK, US OFAC), email domain fraud checks, Peppol, LEI and company registers, VAT rates and reverse-charge guidance, bulk jobs, monitoring and webhooks, with a PDF certificate for checks. Each call counts as one request against your plan's monthly quota (shown in the X-RateLimit-Limit and X-RateLimit-Remaining response headers). A 503 means the official registry couldn't answer; it is never a result.",
    "contact": {
      "email": "support@validitool.com",
      "url": "https://validitool.com/docs"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://validitool.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://validitool.com/api/v1"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Create a key in your dashboard at https://validitool.com/dashboard"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      }
    }
  },
  "tags": [
    {
      "name": "Account",
      "description": "Your key and plan"
    },
    {
      "name": "VAT and EORI",
      "description": "Live checks against VIES, the EU EORI service and HMRC"
    },
    {
      "name": "Compliance",
      "description": "Several checks in one call with a verdict"
    },
    {
      "name": "Other checks",
      "description": "IBAN, email domain, VAT rates, reverse charge, Peppol, LEI and company registers"
    },
    {
      "name": "Bulk",
      "description": "Asynchronous jobs for many numbers"
    },
    {
      "name": "Monitoring",
      "description": "Watched VAT numbers, re-checked daily and re-screened for sanctions"
    },
    {
      "name": "Certificates",
      "description": "PDF proof of a check"
    },
    {
      "name": "Webhooks",
      "description": "Event subscriptions"
    }
  ],
  "paths": {
    "/me": {
      "get": {
        "summary": "The API key's account and plan",
        "tags": [
          "Account"
        ],
        "responses": {
          "200": {
            "description": "Account details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "operationId": "getAccount"
      }
    },
    "/validate": {
      "post": {
        "summary": "Validate a VAT number (VIES)",
        "tags": [
          "VAT and EORI"
        ],
        "responses": {
          "200": {
            "description": "The registry's answer",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "source": {
                      "type": "string",
                      "enum": [
                        "live_vies",
                        "cache",
                        "stale_cache"
                      ]
                    },
                    "valid": {
                      "type": "boolean"
                    },
                    "countryCode": {
                      "type": "string"
                    },
                    "vatNumber": {
                      "type": "string"
                    },
                    "name": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "address": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "consultationNumber": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "validatedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "stale": {
                      "type": "boolean"
                    },
                    "registryError": {
                      "type": "string"
                    },
                    "nameCheck": {
                      "type": "object",
                      "description": "Present when companyName was sent",
                      "properties": {
                        "result": {
                          "type": "string",
                          "enum": [
                            "match",
                            "partial",
                            "mismatch",
                            "no_registered_name"
                          ]
                        },
                        "givenName": {
                          "type": "string"
                        },
                        "registeredName": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "source": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      }
                    },
                    "certificateId": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                },
                "example": {
                  "source": "live_vies",
                  "valid": true,
                  "countryCode": "IE",
                  "vatNumber": "6388047V",
                  "name": "GOOGLE IRELAND LIMITED",
                  "address": "3RD FLOOR, GORDON HOUSE, BARROW STREET, DUBLIN 4",
                  "consultationNumber": null,
                  "validatedAt": "2026-10-06T09:00:00.000Z",
                  "stale": false,
                  "certificateId": "8b1d4f2e-6c3a-4e9b-9f7d-2a5c8e1b3d6f"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not available on your plan",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly quota or plan limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "The official registry couldn't answer right now (not a result: retry later)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "vatNumber": {
                    "type": "string",
                    "description": "With its country prefix, e.g. IE6388047V; spaces and punctuation are ignored"
                  },
                  "countryCode": {
                    "type": "string",
                    "description": "Two-letter country code, if vatNumber has no prefix"
                  },
                  "requesterCountryCode": {
                    "type": "string",
                    "description": "Your own country code; with requesterVatNumber, some member states return a consultation number"
                  },
                  "requesterVatNumber": {
                    "type": "string"
                  },
                  "allowStale": {
                    "type": "boolean",
                    "description": "Scale plan: during an outage, return the last successful result (up to 30 days old), marked stale"
                  },
                  "companyName": {
                    "type": "string",
                    "description": "The name you have for this company; adds nameCheck to the response"
                  }
                },
                "required": [
                  "vatNumber"
                ]
              }
            }
          }
        },
        "operationId": "validateVat"
      }
    },
    "/validate-eori": {
      "post": {
        "summary": "Validate an EORI number (EU service; HMRC for GB)",
        "tags": [
          "VAT and EORI"
        ],
        "responses": {
          "200": {
            "description": "The registry's answer",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "valid": {
                      "type": "boolean"
                    },
                    "eoriNumber": {
                      "type": "string"
                    },
                    "name": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "address": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "validatedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "stale": {
                      "type": "boolean"
                    },
                    "registryError": {
                      "type": "string"
                    },
                    "nameCheck": {
                      "type": "object",
                      "description": "Present when companyName was sent",
                      "properties": {
                        "result": {
                          "type": "string",
                          "enum": [
                            "match",
                            "partial",
                            "mismatch",
                            "no_registered_name"
                          ]
                        },
                        "givenName": {
                          "type": "string"
                        },
                        "registeredName": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "source": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      }
                    },
                    "certificateId": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not available on your plan",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly quota or plan limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "The official registry couldn't answer right now (not a result: retry later)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "eoriNumber": {
                    "type": "string",
                    "description": "e.g. DE123456789012345"
                  },
                  "allowStale": {
                    "type": "boolean",
                    "description": "Scale plan outage fallback"
                  },
                  "companyName": {
                    "type": "string",
                    "description": "Adds nameCheck to the response"
                  }
                },
                "required": [
                  "eoriNumber"
                ]
              }
            }
          }
        },
        "operationId": "validateEori"
      }
    },
    "/compliance-check": {
      "post": {
        "summary": "Counterparty compliance check",
        "tags": [
          "Compliance"
        ],
        "responses": {
          "200": {
            "description": "A clear or review_needed verdict with the reasons and each check's result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "overallStatus": {
                      "type": "string",
                      "enum": [
                        "clear",
                        "review_needed"
                      ]
                    },
                    "reasons": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "vat": {
                      "type": "object"
                    },
                    "eori": {
                      "type": "object"
                    },
                    "sanctions": {
                      "type": "object"
                    },
                    "emailDomain": {
                      "type": "object"
                    },
                    "peppol": {
                      "type": "object"
                    },
                    "lei": {
                      "type": "object"
                    },
                    "nameCheck": {
                      "type": "object",
                      "description": "Present when companyName was sent",
                      "properties": {
                        "result": {
                          "type": "string",
                          "enum": [
                            "match",
                            "partial",
                            "mismatch",
                            "no_registered_name"
                          ]
                        },
                        "givenName": {
                          "type": "string"
                        },
                        "registeredName": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "source": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      }
                    },
                    "checkedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "certificateId": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not available on your plan",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly quota or plan limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "At least one of vatNumber, eoriNumber, companyName, email, lei or ukCompanyNumber is required. Paid plans.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "vatNumber": {
                    "type": "string"
                  },
                  "countryCode": {
                    "type": "string"
                  },
                  "eoriNumber": {
                    "type": "string"
                  },
                  "lei": {
                    "type": "string",
                    "description": "Legal Entity Identifier (GLEIF)"
                  },
                  "ukCompanyNumber": {
                    "type": "string",
                    "description": "UK Companies House number, when enabled"
                  },
                  "companyName": {
                    "type": "string",
                    "description": "Screened against sanctions lists and compared with registered names"
                  },
                  "email": {
                    "type": "string",
                    "description": "A contact email address; its domain is checked for fraud signals"
                  },
                  "knownDomain": {
                    "type": "string",
                    "description": "The domain you already know the company uses (with email)"
                  },
                  "allowStale": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "operationId": "complianceCheck"
      }
    },
    "/email-domain-check": {
      "post": {
        "summary": "Email domain fraud signals",
        "tags": [
          "Other checks"
        ],
        "responses": {
          "200": {
            "description": "Risk level and signals",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly quota or plan limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Send email or domain.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string"
                  },
                  "domain": {
                    "type": "string"
                  },
                  "knownDomain": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "operationId": "checkEmailDomain"
      }
    },
    "/validate-iban": {
      "post": {
        "summary": "Validate an IBAN",
        "tags": [
          "Other checks"
        ],
        "responses": {
          "200": {
            "description": "Validity, bank and country",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly quota or plan limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "iban": {
                    "type": "string"
                  }
                },
                "required": [
                  "iban"
                ]
              }
            }
          }
        },
        "operationId": "validateIban"
      }
    },
    "/vat-rate": {
      "post": {
        "summary": "VAT rates for a country",
        "tags": [
          "Other checks"
        ],
        "responses": {
          "200": {
            "description": "Standard and reduced rates",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly quota or plan limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "countryCode": {
                    "type": "string",
                    "description": "EU or other European country code"
                  }
                },
                "required": [
                  "countryCode"
                ]
              }
            }
          }
        },
        "operationId": "getVatRate"
      }
    },
    "/reverse-charge": {
      "post": {
        "summary": "Does the reverse charge apply?",
        "tags": [
          "Other checks"
        ],
        "responses": {
          "200": {
            "description": "Determination, reason, legal basis, suggested invoice note and assumptions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly quota or plan limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "The official registry couldn't answer right now (not a result: retry later)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "transactionType": {
                    "type": "string",
                    "enum": [
                      "goods",
                      "services"
                    ]
                  },
                  "sellerCountryCode": {
                    "type": "string"
                  },
                  "buyerCountryCode": {
                    "type": "string"
                  },
                  "buyerVatNumber": {
                    "type": "string"
                  },
                  "serviceCategory": {
                    "type": "string",
                    "description": "For services with special place-of-supply rules; 'general' otherwise",
                    "enum": [
                      "general",
                      "real_estate",
                      "admission_events",
                      "restaurant_catering",
                      "short_term_vehicle_hire",
                      "other_exception"
                    ]
                  },
                  "buyerIsBusiness": {
                    "type": "boolean"
                  },
                  "fixedEstablishment": {
                    "type": "boolean"
                  },
                  "goodsTransported": {
                    "type": "boolean"
                  },
                  "thirdPartyInvolved": {
                    "type": "boolean"
                  },
                  "installedOrAssembled": {
                    "type": "boolean"
                  },
                  "deliveredDutyPaid": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "transactionType",
                  "sellerCountryCode",
                  "buyerCountryCode",
                  "buyerVatNumber"
                ]
              }
            }
          }
        },
        "operationId": "checkReverseCharge"
      }
    },
    "/peppol-lookup": {
      "post": {
        "summary": "Peppol e-invoicing registration",
        "tags": [
          "Other checks"
        ],
        "responses": {
          "200": {
            "description": "Registrations and document types",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly quota or plan limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "The official registry couldn't answer right now (not a result: retry later)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "vatNumber": {
                    "type": "string"
                  },
                  "countryCode": {
                    "type": "string"
                  },
                  "participantId": {
                    "type": "string",
                    "description": "e.g. 9925:BE0123456789"
                  }
                }
              }
            }
          }
        },
        "operationId": "lookupPeppol"
      }
    },
    "/lei-lookup": {
      "post": {
        "summary": "Legal Entity Identifier (GLEIF)",
        "tags": [
          "Other checks"
        ],
        "responses": {
          "200": {
            "description": "LEI record",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly quota or plan limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "The official registry couldn't answer right now (not a result: retry later)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "lei": {
                    "type": "string"
                  }
                },
                "required": [
                  "lei"
                ]
              }
            }
          }
        },
        "operationId": "lookupLei"
      }
    },
    "/company-lookup": {
      "post": {
        "summary": "Company register lookup (CH, NO, GB)",
        "tags": [
          "Other checks"
        ],
        "responses": {
          "200": {
            "description": "Company record",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly quota or plan limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "The official registry couldn't answer right now (not a result: retry later)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "country": {
                    "type": "string",
                    "enum": [
                      "CH",
                      "NO",
                      "GB"
                    ]
                  },
                  "number": {
                    "type": "string"
                  }
                },
                "required": [
                  "country",
                  "number"
                ]
              }
            }
          }
        },
        "operationId": "lookupCompany"
      }
    },
    "/batch/validate": {
      "post": {
        "summary": "Submit a bulk VAT validation job",
        "tags": [
          "Bulk"
        ],
        "responses": {
          "201": {
            "description": "Job created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jobId": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "totalItems": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not available on your plan",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly quota or plan limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Growth and Scale plans. Each item counts as one request.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "countryCode": {
                          "type": "string"
                        },
                        "vatNumber": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "required": [
                  "items"
                ]
              }
            }
          }
        },
        "operationId": "createVatBatch"
      }
    },
    "/batch/validate-eori": {
      "post": {
        "summary": "Submit a bulk EORI validation job",
        "tags": [
          "Bulk"
        ],
        "responses": {
          "201": {
            "description": "Job created"
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not available on your plan",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly quota or plan limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "eoriNumber": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "required": [
                  "items"
                ]
              }
            }
          }
        },
        "operationId": "createEoriBatch"
      }
    },
    "/batch/{jobId}": {
      "get": {
        "summary": "Bulk job status",
        "tags": [
          "Bulk"
        ],
        "responses": {
          "200": {
            "description": "pending or completed, with progress",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "From the submit response"
          }
        ],
        "operationId": "getBatch"
      }
    },
    "/batch/{jobId}/results": {
      "get": {
        "summary": "Bulk job results",
        "tags": [
          "Bulk"
        ],
        "responses": {
          "200": {
            "description": "One result per item",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "From the submit response"
          }
        ],
        "operationId": "getBatchResults"
      }
    },
    "/certificate/{certificateId}": {
      "get": {
        "summary": "Download a check's PDF certificate",
        "tags": [
          "Certificates"
        ],
        "responses": {
          "200": {
            "description": "PDF",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly quota or plan limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "certificateId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "From a check's response"
          }
        ],
        "operationId": "getCertificate"
      }
    },
    "/watchlist": {
      "get": {
        "summary": "List watched VAT numbers",
        "tags": [
          "Monitoring"
        ],
        "responses": {
          "200": {
            "description": "Watched numbers with their latest VAT status and sanctions screening",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "operationId": "listWatchlist"
      },
      "post": {
        "summary": "Watch a VAT number",
        "tags": [
          "Monitoring"
        ],
        "responses": {
          "201": {
            "description": "Added"
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not available on your plan",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly quota or plan limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Paid plans. Re-checked daily; re-screened when sanctions lists change.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "countryCode": {
                    "type": "string"
                  },
                  "vatNumber": {
                    "type": "string"
                  },
                  "companyName": {
                    "type": "string",
                    "description": "Also screened against sanctions lists"
                  }
                },
                "required": [
                  "countryCode",
                  "vatNumber"
                ]
              }
            }
          }
        },
        "operationId": "addToWatchlist"
      }
    },
    "/watchlist/{id}": {
      "delete": {
        "summary": "Stop watching a VAT number",
        "tags": [
          "Monitoring"
        ],
        "responses": {
          "200": {
            "description": "Removed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Watched entry id"
          }
        ],
        "operationId": "removeFromWatchlist"
      }
    },
    "/webhooks": {
      "get": {
        "summary": "List webhook subscriptions",
        "tags": [
          "Webhooks"
        ],
        "responses": {
          "200": {
            "description": "Subscriptions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "operationId": "listWebhooks"
      },
      "post": {
        "summary": "Subscribe to an event",
        "tags": [
          "Webhooks"
        ],
        "responses": {
          "201": {
            "description": "Subscribed"
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly quota or plan limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "targetUrl": {
                    "type": "string",
                    "format": "uri",
                    "description": "https:// URL"
                  },
                  "event": {
                    "type": "string",
                    "enum": [
                      "vat_number.status_changed",
                      "batch_job.completed"
                    ]
                  },
                  "source": {
                    "type": "string"
                  }
                },
                "required": [
                  "targetUrl",
                  "event"
                ]
              }
            }
          }
        },
        "operationId": "createWebhook"
      }
    },
    "/webhooks/{id}": {
      "delete": {
        "summary": "Remove a webhook subscription",
        "tags": [
          "Webhooks"
        ],
        "responses": {
          "200": {
            "description": "Removed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Subscription id"
          }
        ],
        "operationId": "deleteWebhook"
      }
    }
  }
}