Skip to main content

ambolt-vies

Check EU VAT numbers against the official VIES REST API. Standard library only (urllib), Python 3.9+, type hints.

pip install ambolt-vies
from ambolt_vies import check_vat, check_vats

print(check_vat("DK10150817"))
# {'valid': True, 'countryCode': 'DK', 'vatNumber': '10150817', 'checkedAt': '...', 'source': 'EU VIES'}

proof = check_vat("DE811128135", requester="DK10150817")  # adds consultationNumber
many = check_vats(["DK10150817", "FR40303265045"], concurrency=2)

What it does

  • Offline syntax validation per member state (format only, no checksums; VIES decides validity). Invalid syntax returns valid: False with reason: "invalid_syntax" and makes no request.
  • Normalises spaces, dots and dashes; GR is sent as EL (Greece), XI is Northern Ireland (goods).
  • Retries with exponential backoff and full jitter on MS_UNAVAILABLE, MS_MAX_CONCURRENT_REQ, TIMEOUT, SERVICE_UNAVAILABLE, GLOBAL_MAX_CONCURRENT_REQ, HTTP 429/5xx and network errors (default 4 retries).
  • check_vats limits requests in flight (default 2) and keeps input order. One failed number does not raise for the batch.
  • With requester (your own EU VAT number) it uses the POST endpoint and returns VIES' consultation number as proof of the check.
  • Privacy default: name and address are only returned with include_details=True. For sole traders they are personal data. Nothing is stored or logged.

Result keys: valid, countryCode, vatNumber, consultationNumber?, checkedAt, source ("EU VIES"), name?, address?, reason? (same as the npm package @ambolt/vies). A failed batch item is {input, valid: None, error: {code, message, retryable}, checkedAt, source}.

Keyword options: country_code, requester, include_details, retries, base_delay_ms, max_delay_ms, timeout (seconds, 15), concurrency (batch).

Errors

check_vat raises ViesError (code, retryable, attempts, status) only when the check could not be completed.

code meaning retried
MS_UNAVAILABLE member state's service is down yes
MS_MAX_CONCURRENT_REQ member state is at its request limit yes
GLOBAL_MAX_CONCURRENT_REQ VIES is at its request limit yes
SERVICE_UNAVAILABLE VIES unavailable yes
TIMEOUT VIES or the member state timed out yes
NETWORK your connection failed yes
INVALID_REQUESTER requester is not a valid VAT number no
IP_BLOCKED, VAT_BLOCKED, HTTP_4xx, BAD_RESPONSE, others VIES refused or answered unexpectedly no

Why not pyvat or validate-vat

Facts as checked on 2026-10-05, from PyPI, npm and GitHub:

  • pyvat had its last release on 2024-01-25 and open issues about MS_UNAVAILABLE and MS_MAX_CONCURRENT_REQ errors.
  • The npm packages validate-vat (last published 2022-08-22, repository no longer resolved) and jsvat (deprecated as unmaintained) are the JavaScript equivalents.

This package targets the current VIES REST API, retries exactly those errors, and its tests mock HTTP only.

Respect VIES' terms of use and keep concurrency low.

Not legal or tax advice. VIES is a service of the European Commission; not affiliated. MIT. Contact: hello@ambolt.dev. https://ambolt.dev

Metadata

Release files for ambolt-vies 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ambolt-vies 0.1.0
File Size Uploaded Provenance Actions
ambolt_vies-0.1.0.tar.gz 6.6 kB Without provenance Details for ambolt_vies-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ambolt-vies 0.1.0
File Interpreter ABI Platform Actions
ambolt_vies-0.1.0-py3-none-any.whl Python 3 none any Details for ambolt_vies-0.1.0-py3-none-any.whl

Total release size: 13.9 kB

Release files / ambolt_vies-0.1.0.tar.gz

Download URL ambolt_vies-0.1.0.tar.gz
Size 6.6 kB
Tags Source
SHA-256 checksum
How to use checksums
de942adc47c189377c9e6a046f5d0c34dacb233e287ebf6124ae9f4fc7b85d01
BLAKE2b-256 checksum
How to use checksums
d97edc5b5ec57d86e8d565942a692ba4a9d6b526731f902ef8de2aa32a171d92
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Release files / ambolt_vies-0.1.0-py3-none-any.whl

Download URL ambolt_vies-0.1.0-py3-none-any.whl
Size 7.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a866e7e83e0306e6509bdb563cb0d1cf24fb23bceb7b14ad228b15490b94fcdb
BLAKE2b-256 checksum
How to use checksums
e89d199db1124d7ffea853c7e897f29052063d7e4d43e6e999ef68890692dd81
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Security for ambolt-vies 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page