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: Falsewithreason: "invalid_syntax"and makes no request. - Normalises spaces, dots and dashes;
GRis sent asEL(Greece),XIis 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_vatslimits 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:
nameandaddressare only returned withinclude_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:
pyvathad its last release on 2024-01-25 and open issues aboutMS_UNAVAILABLEandMS_MAX_CONCURRENT_REQerrors.- The npm packages
validate-vat(last published 2022-08-22, repository no longer resolved) andjsvat(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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.