{
  "openapi": "3.1.0",
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "info": {
    "title": "VATFind API",
    "version": "1.1.0",
    "description": "Check business tax identifiers, resolve company records, schedule company-record monitoring, retrieve change events, and read usage. VATFind keeps format, registry match, tax-authority status, and company legal status separate. The current monitor contract does not monitor authority-reported VAT-registration status.",
    "contact": { "name": "VATFind", "url": "https://vatfind.com/contact" },
    "license": { "name": "VATFind API Terms", "url": "https://vatfind.com/terms" }
  },
  "servers": [
    { "url": "https://vatfind.com/v1", "description": "Environment is selected by the vf_test_ or vf_live_ key prefix" }
  ],
  "security": [{ "VatFindApiKey": [] }],
  "tags": [
    { "name": "Meta", "description": "Public API discovery and transport metadata." },
    { "name": "Checks", "description": "Independent format, registry, authority, and company-status findings." },
    { "name": "Companies", "description": "Company search and VATFind-scoped company snapshots." },
    { "name": "Countries", "description": "Public country and identifier capabilities." },
    { "name": "Usage", "description": "Environment-scoped API, MCP, and monitoring usage." },
    { "name": "Monitoring", "description": "Scheduled company-record rechecks, material change events, and signed webhook delivery. Monitoring does not imply live tax-authority status." }
  ],
  "paths": {
    "/": {
      "get": {
        "operationId": "getApiDiscovery", "tags": ["Meta"], "summary": "Discover the VATFind API", "security": [],
        "responses": { "200": { "description": "API version and documentation links", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["name", "version", "environment", "documentation", "openapi"], "properties": { "name": { "const": "VATFind API" }, "version": { "const": "v1" }, "environment": { "type": "string" }, "documentation": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" } } } } } }, "405": { "$ref": "#/components/responses/Problem" } }
      },
      "head": {
        "operationId": "headApiDiscovery", "tags": ["Meta"], "summary": "Read API discovery headers", "security": [],
        "responses": { "200": { "description": "The same headers as API discovery, without a response body" }, "405": { "$ref": "#/components/responses/Problem" } }
      },
      "options": {
        "operationId": "optionsApiDiscovery", "tags": ["Meta"], "summary": "Read API discovery methods", "security": [],
        "responses": { "204": { "description": "CORS preflight", "headers": { "Allow": { "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } }, "Access-Control-Allow-Methods": { "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } } }
      }
    },
    "/checks": {
      "post": {
        "operationId": "createCheck",
        "tags": ["Checks"],
        "summary": "Create a check",
        "description": "Idempotency-Key is required and retained for 24 hours. An invalid format or missing registry association is a successful check result, not an HTTP error.",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckCreateRequest" } } } },
        "responses": {
          "201": { "description": "Completed check", "headers": { "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Check" } } } },
          "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "402": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" }
        }
      },
      "get": {
        "operationId": "listChecks", "tags": ["Checks"], "summary": "List checks",
        "parameters": [{ "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }],
        "responses": { "200": { "description": "Checks newest first", "content": { "application/json": { "schema": { "type": "object", "required": ["object", "data", "pagination"], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Check" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }
      }
    },
    "/checks/{check_id}": {
      "get": {
        "operationId": "getCheck", "tags": ["Checks"], "summary": "Get a check",
        "parameters": [{ "name": "check_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^chk_[A-Za-z0-9_-]{16,80}$" } }],
        "responses": { "200": { "description": "Check", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Check" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }
      }
    },
    "/companies/search": {
      "post": {
        "operationId": "searchCompanies", "tags": ["Companies"], "summary": "Search company records", "description": "Idempotency-Key is required and retained for 24 hours. New company snapshots share the environment's daily storage allowance and 90-day sandbox or 730-day live retention window; refreshing an existing company ID does not consume another storage slot.",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySearchRequest" } } } },
        "responses": { "200": { "description": "Up to 100 company candidates", "headers": { "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySearchResponse" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "402": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "502": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } }
      }
    },
    "/companies/{company_id}": {
      "get": {
        "operationId": "getCompany", "tags": ["Companies"], "summary": "Get a company snapshot",
        "parameters": [{ "name": "company_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cmp_[A-Za-z0-9_-]{16,80}$" } }],
        "responses": { "200": { "description": "Company snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }
      }
    },
    "/countries": {
      "get": {
        "operationId": "listCountries", "tags": ["Countries"], "summary": "List country capabilities", "security": [],
        "parameters": [{ "name": "query", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } }],
        "responses": { "200": { "description": "Country capabilities", "content": { "application/json": { "schema": { "type": "object", "required": ["object", "data", "pagination"], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CountryCapability" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "422": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } }
      }
    },
    "/countries/{country_code}": {
      "get": {
        "operationId": "getCountry", "tags": ["Countries"], "summary": "Get country capabilities", "security": [],
        "parameters": [{ "name": "country_code", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/CountryCodeInput" } }],
        "responses": { "200": { "description": "Country capability record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryCapability" } } } }, "404": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } }
      }
    },
    "/monitors": {
      "post": {
        "operationId": "createMonitor", "tags": ["Monitoring"], "summary": "Create a company-record monitor",
        "description": "Creates a company-record monitor and runs its first usable baseline. It does not monitor authority-reported VAT-registration status. Idempotency-Key is required. A successful live baseline uses one check. A retry with the same key and body returns the exact completed response, including any webhook signing secret.",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorCreateRequest" } } } },
        "responses": { "201": { "description": "Active monitor and completed baseline", "headers": { "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorCreateResponse" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "402": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }
      },
      "get": {
        "operationId": "listMonitors", "tags": ["Monitoring"], "summary": "List company-record monitors",
        "parameters": [{ "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }],
        "responses": { "200": { "description": "Monitors most recently updated first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorList" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } }
      }
    },
    "/monitors/{monitor_id}": {
      "parameters": [{ "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^mon_[A-Za-z0-9_-]{16,80}$" } }],
      "get": { "operationId": "getMonitor", "tags": ["Monitoring"], "summary": "Get a company-record monitor", "responses": { "200": { "description": "Monitor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Monitor" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } },
      "patch": { "operationId": "updateMonitor", "tags": ["Monitoring"], "summary": "Update a company-record monitor", "description": "Supplying a non-null webhook_url returns the current signing secret. A retry with the same idempotency key and body returns the exact completed response, including that signing secret.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorUpdateRequest" } } } }, "responses": { "200": { "description": "Updated monitor and webhook signing secret when a non-null webhook_url was explicitly supplied", "headers": { "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorUpdateResponse" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } },
      "delete": { "operationId": "archiveMonitor", "tags": ["Monitoring"], "summary": "Archive a company-record monitor", "description": "Stops future checks and releases the monitor slot while retaining event evidence. A retry with the same idempotency key returns the exact completed archive response.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "responses": { "200": { "description": "Archived", "headers": { "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["archived"], "properties": { "archived": { "const": true } } } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } }
    },
    "/monitors/{monitor_id}/run": {
      "post": {
        "operationId": "runMonitor", "tags": ["Monitoring"], "summary": "Run a company-record monitor now", "description": "Runs a billable manual company-record recheck. Idempotency-Key is required and the JSON body must be empty.",
        "parameters": [{ "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^mon_[A-Za-z0-9_-]{16,80}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } },
        "responses": { "200": { "description": "Completed monitoring refresh", "headers": { "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorRunResponse" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "402": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } }
      }
    },
    "/monitoring-events": {
      "get": {
        "operationId": "listMonitoringEvents", "tags": ["Monitoring"], "summary": "List company-monitoring events",
        "parameters": [{ "name": "monitor_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^mon_[A-Za-z0-9_-]{16,80}$" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }],
        "responses": { "200": { "description": "Material changes and operational events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorEventList" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } }
      }
    },
    "/monitoring-events/{event_id}": {
      "get": {
        "operationId": "getMonitoringEvent", "tags": ["Monitoring"], "summary": "Get a company-monitoring event",
        "parameters": [{ "name": "event_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^evt_[A-Za-z0-9_-]{16,80}$" } }],
        "responses": { "200": { "description": "Monitoring event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorEvent" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } }
      }
    },
    "/usage": {
      "get": {
        "operationId": "getUsage", "tags": ["Usage"], "summary": "Get current-period usage",
        "responses": { "200": { "description": "Usage for the API key environment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSummary" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } }
      }
    }
  },
  "webhooks": {
    "monitorEvent": {
      "post": {
        "operationId": "receiveMonitorEvent",
        "summary": "Receive a signed company-monitoring event",
        "description": "VATFind sends events at least once. Verify HMAC-SHA256 over <VATFind-Timestamp>.<raw request body>, then deduplicate with VATFind-Event-Id. Redirects are not followed.",
        "security": [],
        "parameters": [
          { "name": "VATFind-Event-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^evt_[A-Za-z0-9_-]{16,80}$" } },
          { "name": "VATFind-Timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{10,}$" } },
          { "name": "VATFind-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^v1=[a-f0-9]{64}$" } }
        ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorWebhookEnvelope" } } } },
        "responses": { "2XX": { "description": "Event accepted. Other responses are retried up to the documented delivery limit." } }
      }
    }
  },
  "components": {
    "securitySchemes": { "VatFindApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "VATFind API key" } },
    "parameters": {
      "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable key for safe retries, scoped to workspace, environment, and operation.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._-]+$" } },
      "Limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } },
      "Cursor": { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2048 } }
    },
    "responses": {
      "Problem": { "description": "VATFind problem detail", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until retry when the problem is retryable.", "schema": { "type": "integer", "minimum": 1 } }, "WWW-Authenticate": { "schema": { "type": "string" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }
    },
    "schemas": {
      "CountryCode": { "type": "string", "pattern": "^[A-Z]{2}$", "examples": ["GB"] },
      "CountryCodeInput": { "type": "string", "pattern": "^[A-Za-z]{2}$", "examples": ["GB", "gb"] },
      "IdentifierType": { "type": "string", "enum": ["vat_number", "tax_identifier", "registration_number"] },
      "FormatStatus": { "type": "string", "enum": ["valid", "invalid", "not_supported", "not_checked"] },
      "RegistryMatchStatus": { "type": "string", "enum": ["matched", "not_matched", "ambiguous", "unavailable", "not_supported", "not_checked"] },
      "TaxAuthorityStatus": { "type": "string", "enum": ["valid", "invalid", "unavailable", "not_applicable", "not_supported", "not_checked"] },
      "CompanyLegalStatus": { "type": "string", "enum": ["active", "inactive", "dissolved", "liquidation", "insolvency", "unknown", "unavailable", "not_applicable", "not_supported", "not_checked"] },
      "CheckCreateRequest": {
        "type": "object", "additionalProperties": false, "required": ["identifier_type", "identifier", "country_code"],
        "properties": {
          "identifier_type": { "$ref": "#/components/schemas/IdentifierType" }, "identifier": { "type": "string", "minLength": 1, "maxLength": 128 }, "country_code": { "$ref": "#/components/schemas/CountryCodeInput" },
          "company_name": { "type": "string", "minLength": 1, "maxLength": 256 }, "client_reference": { "type": "string", "minLength": 1, "maxLength": 128 },
          "metadata": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 500 } }
        }
      },
      "Identifier": { "type": "object", "additionalProperties": false, "required": ["type", "input", "normalized", "country_code"], "properties": { "type": { "$ref": "#/components/schemas/IdentifierType" }, "input": { "type": "string" }, "normalized": { "type": "string" }, "country_code": { "$ref": "#/components/schemas/CountryCode" } } },
      "Source": { "type": "object", "additionalProperties": false, "required": ["source_type"], "properties": { "source_type": { "type": "string", "enum": ["government_registry", "official_public_record", "licensed_data_provider"] }, "source_name": { "type": "string" }, "source_url": { "type": "string", "format": "uri" } } },
      "Company": {
        "type": "object", "required": ["id", "object", "legal_name", "vat_numbers", "tax_identifiers", "country_code", "company_legal_status", "sources", "retrieved_at"],
        "properties": {
          "id": { "type": "string", "pattern": "^cmp_" }, "object": { "const": "company" }, "legal_name": { "type": "string" }, "registration_number": { "type": "string" }, "vat_numbers": { "type": "array", "items": { "type": "string" } }, "tax_identifiers": { "type": "array", "items": { "type": "string" } }, "country_code": { "$ref": "#/components/schemas/CountryCode" }, "company_legal_status": { "$ref": "#/components/schemas/CompanyLegalStatus" }, "raw_company_legal_status": { "type": "string" }, "legal_form": { "type": "string" }, "incorporation_date": { "type": "string", "format": "date" }, "registered_address": { "type": "object", "properties": { "formatted": { "type": "string" } }, "required": ["formatted"] }, "website": { "type": "string", "format": "uri" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "retrieved_at": { "type": "string", "format": "date-time" }
        }
      },
      "Evidence": { "type": "object", "additionalProperties": false, "required": ["dimension", "source_type", "retrieved_at"], "properties": { "dimension": { "type": "string", "enum": ["format", "registry_match", "tax_authority", "company_legal"] }, "source_type": { "type": "string", "enum": ["vatfind_rules", "government_registry", "tax_authority", "official_public_record", "licensed_data_provider"] }, "source_name": { "type": "string" }, "source_url": { "type": "string", "format": "uri" }, "raw_status": { "type": "string" }, "retrieved_at": { "type": "string", "format": "date-time" } } },
      "Warning": { "type": "object", "additionalProperties": false, "required": ["dimension", "code", "message", "retryable"], "properties": { "dimension": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } } },
      "Check": {
        "type": "object", "required": ["id", "object", "processing_status", "source", "identifier", "format_status", "registry_match_status", "tax_authority_status", "company_legal_status", "evidence", "warnings", "credits_used", "created_at", "completed_at"],
        "properties": {
          "id": { "type": "string", "pattern": "^chk_" }, "object": { "const": "check" }, "processing_status": { "const": "completed" }, "source": { "type": "string", "enum": ["api", "mcp", "dashboard", "monitoring"] }, "identifier": { "$ref": "#/components/schemas/Identifier" }, "format_status": { "$ref": "#/components/schemas/FormatStatus" }, "registry_match_status": { "$ref": "#/components/schemas/RegistryMatchStatus" }, "tax_authority_status": { "$ref": "#/components/schemas/TaxAuthorityStatus" }, "company_legal_status": { "$ref": "#/components/schemas/CompanyLegalStatus" }, "company_name": { "type": "string" }, "client_reference": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "company": { "$ref": "#/components/schemas/Company" }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/Evidence" } }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Warning" } }, "credits_used": { "type": "integer", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }
        }
      },
      "CompanySearchRequest": {
        "type": "object", "additionalProperties": false, "required": ["country_code"], "anyOf": [{ "required": ["name"] }, { "required": ["registration_number"] }, { "required": ["vat_number"] }, { "required": ["tax_identifier"] }], "allOf": [{ "not": { "required": ["vat_number", "tax_identifier"] } }, { "if": { "properties": { "country_code": { "pattern": "^[Uu][Ss]$" } }, "required": ["country_code"] }, "then": { "not": { "required": ["vat_number"] } }, "else": { "not": { "required": ["tax_identifier"] } } }],
        "properties": { "country_code": { "$ref": "#/components/schemas/CountryCodeInput" }, "name": { "type": "string", "minLength": 2, "maxLength": 256 }, "registration_number": { "type": "string", "minLength": 1, "maxLength": 128 }, "vat_number": { "type": "string", "minLength": 1, "maxLength": 128 }, "tax_identifier": { "type": "string", "minLength": 1, "maxLength": 128 }, "city_or_state": { "type": "array", "uniqueItems": true, "maxItems": 10, "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": ".*\\S.*" } } }
      },
      "Pagination": { "type": "object", "required": ["limit", "has_more"], "properties": { "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" } } },
      "CompanySearchResponse": { "type": "object", "required": ["object", "data", "pagination", "credits_used"], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "credits_used": { "type": "integer", "minimum": 0 } } },
      "MonitorCadence": { "type": "string", "enum": ["daily", "weekly", "monthly"] },
      "MonitorWatchedField": { "type": "string", "enum": ["registry_match_status", "company_legal_status", "legal_name", "registration_number", "vat_numbers", "registered_address"] },
      "MonitorSnapshot": {
        "type": "object", "additionalProperties": false,
        "required": ["check_id", "observed_at", "registry_match_status", "company_legal_status", "legal_name", "registration_number", "vat_numbers", "registered_address"],
        "properties": {
          "check_id": { "type": "string", "pattern": "^chk_[A-Za-z0-9_-]{16,80}$" },
          "observed_at": { "type": "string", "format": "date-time" },
          "registry_match_status": { "$ref": "#/components/schemas/RegistryMatchStatus" },
          "company_legal_status": { "$ref": "#/components/schemas/CompanyLegalStatus" },
          "legal_name": { "type": ["string", "null"] },
          "registration_number": { "type": ["string", "null"] },
          "vat_numbers": { "type": "array", "items": { "type": "string" } },
          "registered_address": { "type": ["string", "null"] }
        }
      },
      "Monitor": {
        "type": "object", "additionalProperties": false,
        "required": ["id", "object", "environment", "status", "health", "identifier", "cadence", "watched_fields", "baseline_check_id", "latest_check_id", "latest_snapshot", "last_checked_at", "next_check_at", "failure_count", "estimated_monthly_checks", "created_at", "updated_at"],
        "properties": {
          "id": { "type": "string", "pattern": "^mon_[A-Za-z0-9_-]{16,80}$" },
          "object": { "const": "vat_monitor" },
          "environment": { "type": "string", "enum": ["live", "sandbox"] },
          "status": { "type": "string", "enum": ["active", "paused", "attention"] },
          "health": { "type": "string", "enum": ["healthy", "source_degraded", "needs_credits"] },
          "identifier": { "$ref": "#/components/schemas/Identifier" },
          "company_name": { "type": "string" },
          "client_reference": { "type": "string" },
          "metadata": { "type": "object", "additionalProperties": { "type": "string" } },
          "cadence": { "$ref": "#/components/schemas/MonitorCadence" },
          "watched_fields": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/MonitorWatchedField" } },
          "webhook_url": { "type": "string", "format": "uri", "pattern": "^https://" },
          "baseline_check_id": { "type": "string", "pattern": "^chk_[A-Za-z0-9_-]{16,80}$" },
          "latest_check_id": { "type": "string", "pattern": "^chk_[A-Za-z0-9_-]{16,80}$" },
          "latest_snapshot": { "$ref": "#/components/schemas/MonitorSnapshot" },
          "last_checked_at": { "type": "string", "format": "date-time" },
          "next_check_at": { "type": "string", "format": "date-time" },
          "last_event_at": { "type": "string", "format": "date-time" },
          "failure_count": { "type": "integer", "minimum": 0 },
          "last_error_code": { "type": "string" },
          "estimated_monthly_checks": { "type": "integer", "enum": [1, 5, 30] },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "MonitorCreateRequest": {
        "type": "object", "additionalProperties": false, "required": ["identifier_type", "identifier", "country_code"],
        "properties": {
          "identifier_type": { "$ref": "#/components/schemas/IdentifierType" },
          "identifier": { "type": "string", "minLength": 1, "maxLength": 128 },
          "country_code": { "$ref": "#/components/schemas/CountryCodeInput" },
          "company_name": { "type": "string", "minLength": 1, "maxLength": 256 },
          "cadence": { "$ref": "#/components/schemas/MonitorCadence", "default": "daily" },
          "watched_fields": { "type": "array", "minItems": 1, "maxItems": 6, "uniqueItems": true, "items": { "$ref": "#/components/schemas/MonitorWatchedField" }, "default": ["registry_match_status", "company_legal_status", "legal_name", "registration_number", "vat_numbers", "registered_address"] },
          "webhook_url": { "type": "string", "format": "uri", "pattern": "^https://", "minLength": 12, "maxLength": 2048, "description": "Public HTTPS endpoint. Credentials, IP literals, and local, test, internal, or localhost names are rejected." },
          "client_reference": { "type": "string", "minLength": 1, "maxLength": 128 },
          "metadata": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 500 } }
        }
      },
      "MonitorCreateResponse": {
        "type": "object", "additionalProperties": false, "required": ["monitor", "baseline_check"],
        "properties": { "monitor": { "$ref": "#/components/schemas/Monitor" }, "baseline_check": { "$ref": "#/components/schemas/Check" }, "webhook_signing_secret": { "type": "string", "pattern": "^vfwhsec_", "readOnly": true } }
      },
      "MonitorUpdateRequest": {
        "type": "object", "additionalProperties": false, "minProperties": 1,
        "properties": {
          "status": { "type": "string", "enum": ["active", "paused"] },
          "cadence": { "$ref": "#/components/schemas/MonitorCadence" },
          "watched_fields": { "type": "array", "minItems": 1, "maxItems": 6, "uniqueItems": true, "items": { "$ref": "#/components/schemas/MonitorWatchedField" } },
          "webhook_url": { "description": "Public HTTPS endpoint, or null to disable delivery. Credentials, IP literals, and local, test, internal, or localhost names are rejected.", "anyOf": [{ "type": "string", "format": "uri", "pattern": "^https://", "minLength": 12, "maxLength": 2048 }, { "type": "null" }] }
        }
      },
      "MonitorUpdateResponse": {
        "type": "object", "additionalProperties": false, "required": ["monitor"],
        "properties": { "monitor": { "$ref": "#/components/schemas/Monitor" }, "webhook_signing_secret": { "type": "string", "pattern": "^vfwhsec_", "readOnly": true } }
      },
      "MonitorChange": {
        "type": "object", "additionalProperties": false, "required": ["field", "previous", "current"],
        "properties": {
          "field": { "$ref": "#/components/schemas/MonitorWatchedField" },
          "previous": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "null" }] },
          "current": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "null" }] }
        }
      },
      "MonitorRunResponse": {
        "type": "object", "additionalProperties": false, "required": ["monitor", "check", "changes", "event_id"],
        "properties": { "monitor": { "$ref": "#/components/schemas/Monitor" }, "check": { "$ref": "#/components/schemas/Check" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorChange" } }, "event_id": { "type": ["string", "null"], "pattern": "^evt_[A-Za-z0-9_-]{16,80}$" } }
      },
      "MonitorEvent": {
        "type": "object", "additionalProperties": false,
        "required": ["id", "object", "monitor_id", "type", "severity", "changes", "delivery", "created_at"],
        "properties": {
          "id": { "type": "string", "pattern": "^evt_[A-Za-z0-9_-]{16,80}$" },
          "object": { "const": "vat_monitor_event" },
          "monitor_id": { "type": "string", "pattern": "^mon_[A-Za-z0-9_-]{16,80}$" },
          "type": { "type": "string", "enum": ["vat.monitor.change_detected", "vat.monitor.source_degraded", "vat.monitor.source_restored", "vat.monitor.needs_credits", "vat.monitor.paused", "vat.monitor.resumed"] },
          "severity": { "type": "string", "enum": ["info", "warning", "high"] },
          "changes": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorChange" } },
          "check_id": { "type": "string", "pattern": "^chk_[A-Za-z0-9_-]{16,80}$" },
          "snapshot": { "$ref": "#/components/schemas/MonitorSnapshot" },
          "delivery": {
            "type": "object", "additionalProperties": false, "required": ["status", "attempts"],
            "properties": { "status": { "type": "string", "enum": ["not_configured", "pending", "delivered", "retrying", "failed"] }, "attempts": { "type": "integer", "minimum": 0 }, "delivered_at": { "type": "string", "format": "date-time" }, "response_status": { "type": "integer", "minimum": 100, "maximum": 599 } }
          },
          "acknowledged_at": { "type": "string", "format": "date-time" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "MonitorWebhookEnvelope": {
        "type": "object", "additionalProperties": false, "required": ["id", "type", "api_version", "created_at", "data"],
        "properties": {
          "id": { "type": "string", "pattern": "^evt_[A-Za-z0-9_-]{16,80}$" },
          "type": { "type": "string", "enum": ["vat.monitor.change_detected", "vat.monitor.source_degraded", "vat.monitor.source_restored", "vat.monitor.needs_credits", "vat.monitor.paused", "vat.monitor.resumed"] },
          "api_version": { "const": "2026-08-29" },
          "created_at": { "type": "string", "format": "date-time" },
          "data": {
            "type": "object", "additionalProperties": false, "required": ["monitor_id", "changes"],
            "properties": {
              "monitor_id": { "type": "string", "pattern": "^mon_[A-Za-z0-9_-]{16,80}$" },
              "changes": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorChange" } },
              "check_id": { "type": "string", "pattern": "^chk_[A-Za-z0-9_-]{16,80}$" },
              "snapshot": { "$ref": "#/components/schemas/MonitorSnapshot" }
            }
          }
        }
      },
      "MonitorList": { "type": "object", "additionalProperties": false, "required": ["object", "data", "pagination"], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Monitor" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } },
      "MonitorEventList": { "type": "object", "additionalProperties": false, "required": ["object", "data", "pagination"], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorEvent" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } },
      "CountryCapability": {
        "type": "object", "required": ["country_code", "name", "company_search", "identifier_capabilities", "updated_at"],
        "properties": { "country_code": { "$ref": "#/components/schemas/CountryCode" }, "name": { "type": "string" }, "company_search": { "type": "string", "description": "not_verified means the provider has not published a country-level coverage guarantee; searches remain best-effort.", "enum": ["supported", "partial", "not_verified", "not_supported"] }, "identifier_capabilities": { "type": "array", "items": { "type": "object", "required": ["identifier_type", "format_check", "registry_match", "tax_authority_check", "company_legal_status", "format"], "properties": { "identifier_type": { "$ref": "#/components/schemas/IdentifierType" }, "format_check": { "type": "string", "enum": ["supported", "partial", "not_supported"] }, "registry_match": { "type": "string", "enum": ["supported", "partial", "not_verified", "not_supported"] }, "tax_authority_check": { "type": "string", "enum": ["supported", "partial", "not_supported", "not_applicable"] }, "company_legal_status": { "type": "string", "enum": ["supported", "partial", "not_verified", "not_supported"] }, "format": { "type": "object", "required": ["description", "examples"], "properties": { "description": { "type": "string" }, "pattern": { "type": "string" }, "examples": { "type": "array", "items": { "type": "string" } } } } } } }, "updated_at": { "type": "string", "format": "date-time" } }
      },
      "UsageSummary": {
        "type": "object", "required": ["environment", "period", "totals", "allowance", "by_source", "by_operation", "as_of"],
        "properties": { "environment": { "type": "string", "enum": ["live", "sandbox"] }, "period": { "type": "object", "required": ["start", "end"], "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" } } }, "totals": { "type": "object", "required": ["requests", "billable_units"], "properties": { "requests": { "type": "integer", "minimum": 0, "description": "Completed VATFind usage events recorded for supported operations; not every HTTP transport attempt." }, "billable_units": { "type": "integer", "minimum": 0 } } }, "allowance": { "type": "object", "required": ["included_units", "used_units", "remaining_units"], "properties": { "included_units": { "type": ["integer", "null"], "minimum": 0 }, "used_units": { "type": "integer", "minimum": 0 }, "remaining_units": { "type": ["integer", "null"], "minimum": 0 } } }, "by_source": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["source", "requests", "billable_units"], "properties": { "source": { "type": "string", "enum": ["api", "mcp", "dashboard", "monitoring"] }, "requests": { "type": "integer", "minimum": 0, "description": "Recorded completed usage events for this delivery channel." }, "billable_units": { "type": "integer", "minimum": 0 } } } }, "by_operation": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["operation", "source", "requests", "billable_units"], "properties": { "operation": { "type": "string" }, "source": { "type": "string", "enum": ["api", "mcp", "dashboard", "monitoring"] }, "requests": { "type": "integer", "minimum": 0, "description": "Recorded completed usage events for this operation and channel." }, "billable_units": { "type": "integer", "minimum": 0 } } } }, "as_of": { "type": "string", "format": "date-time" } }
      },
      "Problem": {
        "type": "object", "required": ["type", "title", "status", "detail", "code", "request_id", "retryable"],
        "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" }, "retryable": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "required": ["pointer", "code", "message"], "properties": { "pointer": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }
      }
    }
  }
}