Skip to content

Tools

Every tool returns the envelope. This page lists what each one accepts, which register answers, and what its statuses mean in practice. REST paths are on the REST API page; MCP tool names are identical.

check_vat — EU VAT number

vat, optional country_code, optional requester_vat.

Normalises the number (GR becomes EL, GB becomes XI, prefixes and separators stripped), checks its shape against the national format, then queries VIES. A number that cannot possibly be a VAT number for that country is rejected locally, without spending a call on the register.

Status When
valid Registered for intra-EU trade. data.name / data.address when the member state discloses them.
invalid Not registered, or the shape is wrong for the country, or the country is not in VIES.
upstream_unavailable The gateway or that one member state is down (MS_UNAVAILABLE, MS_MAX_CONCURRENT_REQ, TIMEOUT, HTTP 5xx).

Several member states return --- instead of a name and address. That is their choice, not a missing answer: the number is still valid.

Audit proof. Pass requester_vat with your own VAT number to use the authenticated consultation. VIES then returns data.request_identifier, which you can store to show when you checked a customer — the usual requirement for zero-rating an intra-EU supply. Those calls are never served from cache, since each one needs its own identifier.

lookup_siren — French business

q: a SIREN (9 digits), a SIRET (14 digits), or a company name.

Queries Recherche d'entreprises (DINUM: RNE + Sirene open data). A SIREN/SIRET whose checksum fails never reaches the register.

Returns the legal name, trade name, NAF code, legal form, size band, creation date, the establishment the query pointed at (SIRET, address, INSEE code, coordinates) and the VAT number. A name search also returns data.other_matches so you can disambiguate.

Status When
valid The legal unit exists and is active (etat_administratif = A).
invalid Nothing matches; or the SIREN exists but is closed; or the SIREN exists but carries no such SIRET.
upstream_unavailable The register is down, rate limited us, or we throttled ourselves to stay under its ceiling.

Records marked non-diffusible by their owner are absent from the open data, so a real one-person company can come back invalid. Check data.total_results before telling a user their company does not exist.

normalize_siret — SIREN / SIRET, offline

siret: 9 or 14 digits, any spacing.

Pure logic, no register: Luhn checksum (including the documented La Poste exception, where the digits must sum to a multiple of 5), split into SIREN + NIC, the spaced form, and the FR VAT number derived from the SIREN.

Status is normalized when it checks out, invalid with a reason when the checksum or the length is wrong. Never upstream_unavailable.

check_iban — IBAN and BIC

iban, optional bic.

mod-97 checksum, per-country BBAN structure, and the bank behind it when the country publishes a registry (bank name, BIC, branch code, SEPA membership).

Status When
valid Structurally correct. If a bic was given it is also a valid BIC.
invalid Bad checksum, wrong length for the country, unknown country, or a malformed bic.

A bic from a different country than the IBAN does not make the result invalid — group entities legitimately do this — but it is reported in reason so you can decide.

This checks the number, not the account. It cannot tell you whether the account is open or who owns it.

normalize_address_eu — postal address

address, optional country_code, postal_code, city.

France is geocoded against the Base Adresse Nationale: canonical street line, postcode, city, INSEE code, coordinates and a match score. Scores below 0.5 come back as normalized with a warning rather than valid.

Other member states get structural normalisation only in v1: ISO country code, the national postcode shape and its canonical spacing (1234 AB for NL, 12-345 for PL, 1234-567 for PT…), title-cased city. data.geocoded is false and no register was consulted. This limit is deliberate and stated in the answer.

Status When
valid Geocoded with confidence (FR only).
normalized Canonical form returned without a register match.
invalid Postcode does not fit the country, the country is not an EU member state, or no French address matches.
upstream_unavailable The BAN did not answer (FR only).

normalize_phone — phone number

phone, optional region.

libphonenumber metadata: E.164, international, national and RFC 3966 forms, calling code, region, line type (mobile, fixed_line, voip…). region is only needed for numbers written without a + prefix; without it a national number cannot be resolved and comes back invalid.

Status is valid when the number exists in that numbering plan, invalid otherwise. Never upstream_unavailable.

check_email — email address

email, optional mx (default true).

Syntax and canonical form (IDN aware), then the domain's MX records over DNS. A domain with no MX but an A record still accepts mail (RFC 5321), which is reported as data.implicit_mx.

Also flagged: data.disposable for known throwaway providers (checked before any DNS query), and data.role_account for shared mailboxes (info@, noreply@, facturation@…) — useful when onboarding needs a named human.

Status When
valid Syntax is good and the domain can receive mail.
invalid Bad syntax, disposable provider, domain does not exist, or no mail server.
normalized mx=false: syntax checked, nothing looked up.
upstream_unavailable The DNS resolver did not answer.

There is no SMTP probe, so a valid result means the domain accepts mail, not that the mailbox exists. Probing mailboxes gets servers blacklisted and is not something this service does.

check_eori — customs registration

eori.

The EU EOS validation service over SOAP. Returns the registered trader name and address, validity dates, and the service's own status description. Shape is checked locally first (two-letter country code plus up to 15 alphanumeric characters).

Status When
valid Registered (status 0).
invalid Not registered, or the shape is wrong.
upstream_unavailable SOAP fault, timeout, or an answer without a status.

Caching

Answers are cached so repeated checks of the same identifier are fast and do not hammer the registers. Default lifetimes: VIES 24 h when valid and 1 h when invalid, Sirene 24 h, EORI 24 h, addresses 7 days, MX 1 h. cached tells you which answer you got. upstream_unavailable is never cached, and authenticated VIES consultations are never served from cache.