{ "openapi": "3.0.1", "info": { "title": "EU VAT Number Validator (VIES)", "description": "Compliance Operations System for EU VAT — detect deregistered or mismatched counterparties, escalate by SLA, auto-generate ticket-ready actions. Bulk-validate against the official VIES API across all 27 EU countries + XI. Audit-grade consultation references, change detection, risk scoring.", "version": "1.0", "x-build-id": "F8aQwCpeUSlCUup2H" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/ryanclinton~eu-vat-validator/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-ryanclinton-eu-vat-validator", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/ryanclinton~eu-vat-validator/runs": { "post": { "operationId": "runs-sync-ryanclinton-eu-vat-validator", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/ryanclinton~eu-vat-validator/run-sync": { "post": { "operationId": "run-sync-ryanclinton-eu-vat-validator", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "vatNumbers" ], "properties": { "vatNumbers": { "title": "VAT Numbers", "maxItems": 10000, "type": "array", "description": "List of EU VAT numbers to validate. Format: 2-letter country code + number (e.g. NL004495445B01, FR40303265045, IE6388047V). Spaces, dots, and dashes are stripped automatically. Use EL for Greece and XI for Northern Ireland.", "items": { "type": "string" }, "default": [ "NL004495445B01" ] }, "mode": { "title": "Mode", "enum": [ "auto", "quick", "audit", "monitoring" ], "type": "string", "description": "Workflow preset. `auto` (default) resolves from the rest of your input — quick if no requesterVatNumber, audit if requesterVatNumber is set, monitoring if compareToPrevRun is on. `quick` is the lightest path. `audit` enables audit-grade output (requires requesterVatNumber). `monitoring` turns on cross-run change detection. Explicit fields below always win over preset defaults.", "default": "auto" }, "requesterVatNumber": { "title": "Your VAT number (verified consultation — for audit-grade output)", "type": "string", "description": "Optional. When provided, VIES runs a 'verified consultation' and returns a consultation reference number (requestIdentifier) for every lookup. EU tax authorities accept this reference as audit evidence under VAT Directive Art 138 — it is the legal proof that you verified the counterparty before issuing a zero-rated B2B invoice. Format: 2-letter country code + number (e.g. NL123456789B01)." }, "compareToPrevRun": { "title": "Compare to previous run (change detection)", "type": "boolean", "description": "Compare results against the previous run's state to emit change flags (NEW_VAT, VALIDITY_LOST, VALIDITY_GAINED, NAME_CHANGED, ADDRESS_CHANGED, UNCHANGED) and a per-row diff block (previousValid, previousName, previousAddress, daysSinceLastSeen). State is keyed by `monitorStateKey` and stored in a named key-value store (`eu-vat-validator-state`). First run for a key produces NEW_VAT on every row. Auto-enabled in `monitoring` mode.", "default": false }, "monitorStateKey": { "title": "Monitor state key", "type": "string", "description": "Stable identifier for the change-detection state snapshot. Reuse the same key across scheduled runs to compare against the prior state. Leave blank to auto-derive a key from the input — useful for ad-hoc runs but means you can only compare against runs with the same input set." }, "emitChangeEvents": { "title": "Emit change-event records (for webhooks/alerts)", "type": "boolean", "description": "When set together with `compareToPrevRun`, the actor pushes additional dataset rows with `recordType: 'change-event'` for every material change — one per change. Each event carries `eventType` (`vat.validity_lost`, `vat.validity_gained`, `vat.name_changed`, `vat.address_changed`, `vat.name_mismatch`, `vat.country_mismatch`), `severity`, and a `context` block with the before/after values. Branch downstream automation (Slack, Zapier, Make, webhooks) on `recordType = 'change-event'` to act ONLY on changes instead of scanning every validation row. Auto-enabled in `monitoring` mode. Change-event records are NOT charged.", "default": false }, "emitOnlyChanges": { "title": "Suppress uneventful rows (changes-only mode)", "type": "boolean", "description": "When set together with `compareToPrevRun`, validation rows with no signal (UNCHANGED + valid + low risk + no match issues) are NOT pushed to the dataset. Cuts dataset noise to near-zero on stable customer databases. NOTE: VIES calls still happen and are still charged unless they hit the cache (set `cacheTTLHours` to skip the calls too). The run summary always includes the suppressed-row count for audit.", "default": false }, "emitOnlyNewEvents": { "title": "Only emit NEW change events (suppress repeats across runs)", "type": "boolean", "description": "When set together with `emitChangeEvents`, a `change-event` record is emitted only the first run a (vatNumber, eventType) pair appears. If the same combo fired in the prior run's state, it is suppressed. Prevents Slack/Zapier alert fatigue when a deregistered customer or persistent name mismatch lingers across many scheduled runs. Auto-enabled in `monitoring` mode. The run summary reports `eventsSuppressedAsRepeats` for audit.", "default": false }, "cacheTTLHours": { "title": "Cache TTL (hours) — skip recently-validated VATs", "minimum": 1, "maximum": 720, "type": "integer", "description": "When set together with `compareToPrevRun`, VAT numbers that were validated in a prior run within the last N hours are returned from the state snapshot instead of being re-validated against VIES. Cache hits are NOT charged. Useful for high-frequency scheduled runs where most numbers do not change daily. Pair with `emitOnlyChanges` for a no-noise no-cost monitoring loop. Leave blank to always hit VIES." }, "slaTargetDays": { "title": "SLA target (days) — when to escalate open issues", "minimum": 1, "maximum": 365, "type": "integer", "description": "How long an alert is allowed to stay open before it is considered SLA-breached. Drives `daysOpen`, `slaBreached`, `escalationLevel` (0 = not alerted, 1 = within SLA, 2 = SLA breached, 3 = severely overdue ≥2× SLA), and `escalationReason` per row. Plus `summary.slaBreaches` and `summary.escalationCounts`. Only meaningful with `compareToPrevRun`. Default: 7.", "default": 7 }, "expectations": { "title": "Entity verification expectations", "type": "object", "description": "Optional per-VAT entity verification. Accepts EITHER an array of `{ vatNumber, expectedName, expectedCountry, expectedInvoiceAmount, expectedCurrency }` (recommended — easier to write) OR an object map of VAT → `{ expectedName, expectedCountry, expectedInvoiceAmount, expectedCurrency }`. When provided, the actor compares the VIES-returned company name and country against your expectations and emits `nameMatch` / `nameMatchScore` / `countryMatch` / `matchFlags`. If `expectedInvoiceAmount` is also supplied AND the row has block_invoice / hold_payment recommendation, the actor computes `financialRiskEstimate` (conservative 21% EU VAT rate).\n\nArray form (recommended):\n[ { \"vatNumber\": \"FR40303265045\", \"expectedName\": \"Total Energies SE\", \"expectedCountry\": \"FR\", \"expectedInvoiceAmount\": 12000, \"expectedCurrency\": \"EUR\" } ]\n\nObject form (back-compat):\n{ \"FR40303265045\": { \"expectedName\": \"Total Energies SE\", \"expectedCountry\": \"FR\" } }" }, "deduplicate": { "title": "Deduplicate input", "type": "boolean", "description": "Skip duplicate VAT numbers in the input list (matched after normalisation — case-insensitive, whitespace and punctuation stripped). Saves cost and avoids redundant VIES calls. Disable if you need one output row per input row.", "default": true }, "validateFormatLocally": { "title": "Pre-validate country format", "type": "boolean", "description": "Check each VAT number against its country's expected format before calling VIES. Numbers that fail the local check are returned with error code INVALID_COUNTRY_FORMAT and never hit the VIES API — saves time and cost on obvious typos. Disable if you want every number sent to VIES regardless of format.", "default": true }, "includeUnreliableCountries": { "title": "Include unreliable countries (DE)", "type": "boolean", "description": "Germany's VIES node is frequently offline and will return MS_UNAVAILABLE errors. Enable this to attempt DE validation anyway. When disabled (default), DE numbers are skipped with a warning.", "default": false }, "includeAddress": { "title": "Include company name, address, and trader fields", "type": "boolean", "description": "Include the registered company name, address, and parsed trader fields (traderName, traderStreet, traderPostalCode, traderCity, traderCompanyType) in results. Disable for privacy-sensitive workflows where you only need a validity flag.", "default": true } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } }