EU VAT Number Validator (VIES)
Pricing
from $2.00 / 1,000 vat validateds
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.
Pricing
from $2.00 / 1,000 vat validateds
Rating
0.0
(0)
Developer
ryan clinton
Actor stats
0
Bookmarked
11
Total users
2
Monthly active users
2 days ago
Last modified
Categories
Share
recordType
Optional
Stable record-type discriminator. One of: validation (per-VAT result, success or VIES-said-invalid), error (input-side or skipped failure), fatal (actor-side fatal). Branch downstream automation on this.
vatNumber
Optional
Full VAT number including country code
countryCode
Optional
Two-letter EU country code
number
Optional
VAT number without country prefix
valid
Optional
Whether the VAT number is valid
name
Optional
Registered company name
address
Optional
Registered company address
traderName
Optional
Parsed trader name when VIES separates it from the merged name field
traderStreet
Optional
Trader street component of the registered address
traderPostalCode
Optional
Trader postal code component of the registered address
traderCity
Optional
Trader city component of the registered address
traderCompanyType
Optional
Trader company type / legal form when VIES provides it
requestDate
Optional
Date/time of the validation request
requestIdentifier
Optional
VIES consultation reference number (returned only when requesterVatNumber is set — audit evidence under VAT Directive Art 138)
error
Optional
Raw error code if validation failed (machine-stable enum)
failureType
Optional
Stable failure-mode classification — one of: invalid-input, no-data-temp, no-data-permanent, rate-limited, network-error, vies-error. Use this (not 'error') for downstream routing.
recommendation
Optional
Plain-English next step for failure rows. Null on success.
dataCompleteness
Optional
Fraction of optional success fields populated (0.0-1.0). Null on failure rows.
missingFields
Optional
Names of optional fields that came back null. Empty array on full rows, null on failure rows.
countryReliability
Optional
Country-level VIES reliability hint based on documented uptime + rate-limiting behaviour. One of: high, medium, low.
changeFlags
Optional
Stable change-detection enum array (only present when compareToPrevRun is set). Values: NEW_VAT, VALIDITY_LOST, VALIDITY_GAINED, NAME_CHANGED, ADDRESS_CHANGED, UNCHANGED.
changeSinceLastRun
Optional
Diff block against the previous run's state — previousValid, previousName, previousAddress, firstSeenAt, lastSeenAt, daysSinceLastSeen. Null on first run for a monitor key.
cacheHit
Optional
True when this row was served from the cross-run cache (cacheTTLHours) instead of a fresh VIES call. Cache hits are not charged.
nameMatch
Optional
Entity verification: true when VIES name matches expectedName (>=90 similarity). Null when no expectation supplied.
nameMatchScore
Optional
Entity verification: Levenshtein-based similarity score 0-100 against expectedName. Null when no expectation supplied.
countryMatch
Optional
Entity verification: true when countryCode matches expectedCountry. Null when no expectation supplied.
matchFlags
Optional
Entity verification stable enum array. Values: NAME_MATCHED, NAME_PARTIAL_MATCH, NAME_MISMATCHED, COUNTRY_MATCHED, COUNTRY_MISMATCHED, NO_EXPECTED_DATA.
cachedAgeHours
Optional
Age of the cached result in hours (only set on cache hits). Null on fresh VIES calls or when cache TTL is off.
severity
Optional
Severity tier derived from change + match + completeness signals. critical (VALIDITY_LOST), high (NAME_MISMATCHED, COUNTRY_MISMATCHED, currently invalid, VALIDITY_GAINED), medium (NAME_CHANGED, ADDRESS_CHANGED, NAME_PARTIAL_MATCH, completeness <30%), low (NEW_VAT, completeness <60%, transient infra failure), null (uneventful).
riskScore
Optional
Composite trust score 0.0-1.0 — combines validity (1.0 if invalid), name mismatch (+0.5), partial match (+0.25), VALIDITY_LOST (+1.0 — capped), NAME_CHANGED (+0.15), ADDRESS_CHANGED (+0.05), low completeness (+0.05 to +0.15), country reliability (+0.02 to +0.05). Capped at 1.0.
riskLevel
Optional
Coarse risk band: critical (≥0.75), high (≥0.5), medium (≥0.25), low (<0.25). Use this for filtering instead of riskScore when you want a step function.
group
Optional
Derived row-grouping for spreadsheet/dashboard filtering: changed, new, unchanged, invalid, failed.
explanation
Optional
Plain-English string array — what's notable about this row. Built deterministically from change + match + completeness + reliability signals. Empty array on uneventful rows.
retryEligible
Optional
True when this failure could benefit from re-running (transient infrastructure issue: no-data-temp, rate-limited, network-error). False on success rows and on permanent failures.
riskFactors
Optional
Stable enum array — machine-readable mirror of explanation[]. Codes: validity_lost, currently_invalid, name_mismatch, country_mismatch, name_partial_match, name_changed, address_changed, very_low_completeness, low_completeness, unreliable_country, medium_reliability_country. Empty array on low-risk rows. Branch downstream automation on these codes; use explanation for human-readable copy.
primaryRiskFactor
Optional
Top contributor from riskFactors[] (severity-ordered). Single-string convenience for low-code tools (Zapier, n8n, webhook routers) that filter on equality, not array-contains. Null on rows with no risk factors.
actionRequired
Optional
Convenience boolean — true when the row needs human or downstream action. Derived: riskLevel in (critical/high/medium) OR retryEligible. Lets non-technical users filter spreadsheets with =TRUE instead of stacking conditions.
recommendedAction
Optional
Stable enum: block_invoice (validity_lost, currently_invalid), hold_payment (name_mismatch, country_mismatch), review (name_partial_match, name_changed), retry_later (transient failures), monitor_only (low-signal data quality), none. Branch automation on this — same value across runs for the same condition.
actionPriority
Optional
Action priority: immediate (block_invoice), high (hold_payment), normal (review, retry_later), low (monitor_only, none). Sortable for triage queues.
actionPlaybook
Optional
2-4 step playbook for the recommended action — usable verbatim in tickets, Slack messages, or operator runbooks.
businessImpact
Optional
Plain-English board-level explanation of what this row means for the business. Template-based per primary risk factor; null when no impact.
financialRiskEstimate
Optional
Indicative VAT-liability exposure estimate when expectedInvoiceAmount is supplied per expectation AND the row has block_invoice / hold_payment recommendation. Object: { amount, currency, vatRateUsed, note }. Uses 21% EU average. NOT tax advice — actual liability depends on member-state rate (17–27%) and penalties. Override with your accounting system before filing or invoicing.
firstSeenAt
Optional
When this VAT first appeared in any prior run for this monitor key. Equals current run timestamp on first appearance.
daysSinceFirstSeen
Optional
Days since firstSeenAt. 0 on first appearance.
timesSeen
Optional
Total runs this VAT has appeared in (1 on first appearance, increments each subsequent run). Drives summary.repeatOffenders.
timesAlerted
Optional
Total runs this VAT has been alerted in (recommendedAction other than none / monitor_only). Drives summary.repeatOffenders.
firstAlertedAt
Optional
When the alert first fired. Sticky across runs while alerted; reset to null when the issue resolves.
daysOpen
Optional
Days the alert has been open since firstAlertedAt. Null when not currently alerted.
slaBreached
Optional
True when daysOpen >= slaTargetDays. Null when not alerted.
slaTargetDays
Optional
Echo of the input slaTargetDays for downstream filtering.
escalationLevel
Optional
Escalation tier: 0 (not alerted), 1 (within SLA), 2 (SLA breached), 3 (severely overdue ≥2× SLA).
escalationReason
Optional
Plain-English explanation of the escalation level — usable in alert payloads.
eventType
Optional
On recordType: 'change-event' records only. Stable enum: vat.validity_lost, vat.validity_gained, vat.name_changed, vat.address_changed, vat.name_mismatch, vat.country_mismatch.
timestamp
Optional
On recordType: 'change-event' records only. ISO 8601 timestamp when the event was emitted.
context
Optional
On recordType: 'change-event' records only. Before/after values relevant to the event type (previousValid, currentValid, previousName, currentName, daysSinceLastSeen, similarityScore, etc.).
sourceVatNumber
Optional
On recordType: 'change-event' records only. The VAT number the event was derived from — joinable back to the validation row by vatNumber.
