Validate VAT Number

data.validate_vat_number

ProductionBounded custom (Class B)Deterministicstrictinstantv1.0.0

No network

Overview

You send a VAT identification number and the country it belongs to, and we check three things offline: that every character is an ASCII letter or digit, that the number matches one of that country's published structures, and that its check characters recompute under that country's own algorithm. Fifteen member states are covered, each transcribed from that state's publication and pinned as a rules version we echo back. We return a normalised form, the country's printed grouping, the structure we matched and the algorithm we ran. We do not call VIES or any national registry, so we cannot tell you the number is issued, active, or belongs to the trader on your invoice — every answer says so in validationLevel, and a stored true here is not evidence a company exists.

Most wrong VAT numbers are typing mistakes, and a checksum catches those without a registry round trip for every row in a supplier table.

Reliability

The same number and country always give the same verdict, on any machine and under any locale, time zone or default charset. Upper-casing uses the root locale, so a Turkish default locale cannot turn the i of an IE prefix into a dotted capital and break the match. A number that is merely wrong comes back as valid false with one finding, not as an error: VAT_CHARACTER_INVALID for a character outside ASCII letters and digits, including fullwidth and Arabic-Indic digits and Cyrillic look-alikes, which we report rather than fold; VAT_STRUCTURE_MISMATCH when nothing in that country's published set matches; VAT_CHECKSUM_FAILED when the check characters do not recompute. Coverage gaps that report VAT_STRUCTURE_MISMATCH rather than pretending: a French number whose two-character key is alphabetic, an Irish number in the transitional form with a letter or symbol as its second character, and the GB government-department and health-authority forms beginning GD or HA. Malformed, empty or over-128-code-point vatNumber values are structural TOOL_INPUT_INVALID refusals. Five domain refusals are not retryable unchanged: VAT_COUNTRY_REQUIRED when country is missing or is not a string; VAT_COUNTRY_UNSUPPORTED when it is outside the fifteen, which is a refusal rather than a false verdict because we hold no rule to judge it by; VAT_COUNTRY_PREFIX_MISMATCH when the number carries a different country's prefix, where we refuse rather than pick a side, since either the prefix or the country field could be the mistake; VAT_PREFIX_POLICY_VIOLATED when prefixPolicy requires a prefix that is absent or rejects one that is present; and VAT_OPTION_UNSUPPORTED for an unknown option key, a non-boolean switch or a prefixPolicy outside the three members.

Context footprint

Returns the verdict, the normalised and grouped forms, four check booleans and at most one finding — a fixed, small object. A successful call costs 1 execution credit.

When to use it

Before storing a VAT number, or to triage a table down to the numbers that are worth a registry lookup.

When the answer decides a tax treatment — that needs a registry, and this skill deliberately does not call one.

Scope

Note

Checks a VAT number's characters, national structure and national checksum.

Non-goals

Does not call VIES or any national registry
Does not tell you a number is issued, active or currently valid
Does not tell you the number belongs to the trader on your invoice
Does not resolve a country name to a code
Does not cover member states outside the fifteen in the table

Properties

IdempotentRetry safeStreaming supportedFile input supportedRequires external service

Capabilities

parsingvalidation

Cost & billing

Flat rate per invocation

MetercallsBillable onsuccessCost per call1 credit

File handling

Accepts file_refProduces file_refMax input1 KB

How we handle your data

Sensitive output possible

What this means

This skill may receive sensitive content and may return submitted, transformed, extracted, or reformatted content.

Squillify guarantees

Runs inside Squillify
This skill runs inside Squillify.
Payloads are not sent to an external service by this skill.
Squillify does not permanently store submitted payloads.
Telemetry records metadata only, not submitted content.
Submitted payloads are not used for training.
Submitted payloads are not reviewed by humans.
This skill does not target sensitive data.
The response may contain submitted or transformed content.

Your responsibility

Squillify does not determine whether submitted content is sensitive. Your application is responsible for deciding what data it is allowed to submit. Your application is responsible for securing the response.

Read the Microskill Data Handling Policy

Input schema

Field	Type	Required	Description
vatNumber	string	Yes	VAT identification number of 1 through 128 code points.
country	string	Yes	ISO-3166-1 alpha-2 country whose national rules are applied.
options	object	No	Closed optional VAT parsing switches; omit the object to keep the published defaults.

Output schema

Field	Type	Required	Description
valid	boolean	Yes	Whether characters, structure, and checksum all passed.
normalized	string	Yes	Compact prefixed uppercase form with separators removed.
formatted	string	Yes	National printed grouping of the same number.
country	string	Yes	Alpha-2 country whose rules were applied.
structure	string	No	Matched structure identifier, omitted when none matched.
algorithm	string	No	Named checksum family actually run, omitted when none was reached.
checks	object	Yes	Closed per-check booleans in run order: characters, country, structure, checksum.
validationLevel	string	Yes	Always FORMAT_AND_CHECKSUM so a stored true cannot be read as registry proof.
findings	array	Yes	Bounded array of 0 through 8 closed findings; empty when valid.
_meta	object	Yes	Closed provenance naming the pinned rule table and the countries it covers.

API contract

POST /v1/execute

curl

curl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"data.validate_vat_number","input":{"vatNumber":"BE 0776.091.951","country":"BE"}}'

Integrations

TypeScript SDK

import { Squillify } from "@squillify/sdk";

const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });

const { output } = await sq.execute("data.validate_vat_number", {"vatNumber":"BE 0776.091.951","country":"BE"});

Errors

Code	HTTP	Retryable	Description
VALIDATION_ERROR	400	No	The request payload failed schema validation.
UNAUTHORIZED	401	No	Missing or invalid API key.
SKILL_NOT_ACCESSIBLE	403	No	The API key is not granted access to this skill.
SKILL_NOT_AVAILABLE_FOR_PLAN	403	No	This skill is not included in your current plan.
PLAN_ELIGIBILITY_UNAVAILABLE	503	Yes	Plan eligibility could not be decided. Retry after backoff.
SKILL_NOT_FOUND	404	No	The requested skill or version does not exist.
TENANT_RATE_LIMITED	429	Yes	Request rate limit exceeded. Retry after backoff.
QUOTA_EXCEEDED	429	Yes	Plan quota exhausted. Retryable once the quota period resets.
EXECUTION_TIMEOUT	504	Yes	Execution exceeded the allowed time budget.
VAT_COUNTRY_REQUIRED	400	No	The request payload failed this skill's input validation.
VAT_COUNTRY_UNSUPPORTED	400	No	The skill does not support the requested variant.
VAT_COUNTRY_PREFIX_MISMATCH	400	No	The request payload failed this skill's input validation.
VAT_PREFIX_POLICY_VIOLATED	400	No	The request payload failed this skill's input validation.
VAT_OPTION_UNSUPPORTED	400	No	The skill does not support the requested variant.

Other limits

Limit	Value
Recommended inline bytes	32 KiB

Limitations

Does not call VIES or any national registry
Does not tell you a number is issued, active or currently valid
Does not tell you the number belongs to the trader on your invoice
Does not resolve a country name to a code
Does not cover member states outside the fifteen in the table
Deciding whether to apply a reverse-charge on an invoice
Proving a counterparty is VAT-registered
Any tax decision that needs the number to be live

How to call

POST /v1/execute (requires authentication)

Request bodyjson

{
  "skillKey": "data.validate_vat_number",
  "input": {
    "vatNumber": "BE 0776.091.951",
    "country": "BE"
  }
}

Examples

A Belgian number written the way it is printed

Inputjson

{
  "vatNumber": "BE 0776.091.951",
  "country": "BE"
}

Expected outputjson

{
  "normalized": "BE0776091951",
  "algorithm": "mod-97 complement",
  "validationLevel": "FORMAT_AND_CHECKSUM",
  "findings": [],
  "structure": "BE-10n",
  "formatted": "BE 0776.091.951",
  "checks": {
    "checksum": true,
    "countryKnown": true,
    "characters": true,
    "structure": true
  },
  "country": "BE",
  "valid": true,
  "_meta": {
    "countriesSupported": [
      "AT",
      "BE",
      "DE",
      "DK",
      "ES",
      "FI",
      "FR",
      "GB",
      "IE",
      "IT",
      "LU",
      "NL",
      "PL",
      "PT",
      "SE"
    ],
    "rulesVersion": "vat-rules-2026-07"
  }
}

One digit changed, so only the checksum fails