VIES REST vs SOAP API: Direct Calls, WSDL, Where Each Fails
20 Nov 2026

VIES answers over two protocols: a SOAP service, checkVatService, described by a WSDL, and a JSON REST endpoint. For the same input they gave us the same valid result; the Commission does not document how the two relate internally. Where they differ is field names, how each reports a failure, and what a generic HTTP client assumes about an error. Our suggestion for new code is REST; if you already have a client generated from the WSDL, keep it. Whichever you pick, read the body before the status code. Below are the two side by side, with calls we made on 16 Oct 2026. For the wrapped version, see vatnode as a VIES API.
The two VIES endpoints
| SOAP | REST | |
|---|---|---|
| Endpoint | https://ec.europa.eu/taxation_customs/vies/services/checkVatService | https://ec.europa.eu/taxation_customs/vies/rest-api |
| Description | WSDL | Swagger 2.0 file |
| Check | checkVat, checkVatApprox | POST /check-vat-number |
| Availability | none | GET /check-status |
| Test service | checkVatTestService | POST /check-vat-test-service |
Documented in the WSDL: the binding is document/literal with an empty soapAction, and the namespace is urn:ec.europa.eu:taxud:vies:services:checkVat:types. checkVat takes countryCode and vatNumber. checkVatApprox adds optional traderName, traderCompanyType, traderStreet, traderPostcode, traderCity, requesterCountryCode and requesterVatNumber.
The soap:address in the WSDL is a plain http:// address, so a client generated from it calls http by default. Override the endpoint to https. Plain http did answer a checkVat call when we tried it, but there is no reason to rely on that.
The REST side also has GET /rest-api/ms/{cc}/vat/{number}, which the VIES web page used when we looked. It is not in the Swagger file and returns a different shape (isValid, userError, a numeric viesApproximate). Do not build on it.
We found no official deprecation notice for either protocol, and this post makes no claim about either one’s future.
The same check over REST and SOAP
We checked DE123456789, a made-up number that fails the German checksum. SOAP first, with an empty soapAction header, as the WSDL says:
curl -s https://ec.europa.eu/taxation_customs/vies/services/checkVatService \
-H 'Content-Type: text/xml; charset=utf-8' \
-H 'SOAPAction: ""' \
--data '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:ec.europa.eu:taxud:vies:services:checkVat:types">
<soapenv:Header/>
<soapenv:Body>
<urn:checkVat>
<urn:countryCode>DE</urn:countryCode>
<urn:vatNumber>123456789</urn:vatNumber>
</urn:checkVat>
</soapenv:Body>
</soapenv:Envelope>'
Observed on 16 Oct 2026, HTTP 200, envelope removed and indented for reading. The reply uses its own ns2 prefix, so match elements by namespace, not by the prefix you sent:
<ns2:checkVatResponse xmlns:ns2="urn:ec.europa.eu:taxud:vies:services:checkVat:types">
<ns2:countryCode>DE</ns2:countryCode>
<ns2:vatNumber>123456789</ns2:vatNumber>
<ns2:requestDate>2026-10-16+02:00</ns2:requestDate>
<ns2:valid>false</ns2:valid>
<ns2:name>---</ns2:name>
<ns2:address>---</ns2:address>
</ns2:checkVatResponse>
Now REST, with a JSON body:
curl -s https://ec.europa.eu/taxation_customs/vies/rest-api/check-vat-number \
-H 'Content-Type: application/json' \
--data '{"countryCode":"DE","vatNumber":"123456789"}'
Observed, HTTP 200, trimmed:
{
"requestDate": "2026-10-16T14:18:23.573Z",
"valid": false,
"requestIdentifier": "",
"name": "---",
"address": "---"
}
In our calls an invalid number came back as a normal reply with valid set to false, in both protocols. The placeholder for ‘no data’ was the string --- in checkVat and REST, not a null. checkVatApprox mixed xsi:nil, empty elements and ---, so normalise all three before you store anything. The REST reply also carried match fields set to NOT_PROCESSED and trader* fields set to ---, which we trimmed.
In both calls countryCode and vatNumber are separate fields: send the number without its country prefix, and use the VIES country codes (Greece is EL, not GR). We did not test how VIES treats a prefixed number.
To ask for a requestIdentifier over REST, add the requester fields to the same body:
{
"countryCode": "DE",
"vatNumber": "123456789",
"requesterMemberStateCode": "FI",
"requesterNumber": "12345678"
}
The field names come from the Swagger file. This is the call documented to return a requestIdentifier. With our invalid target, it came back empty.
Field names that differ between SOAP and REST
If you port a client from one to the other, the names are where it breaks. Sources are the WSDL and the Swagger file, plus what we saw on 16 Oct 2026.
| What | SOAP | REST |
|---|---|---|
| Requester country | requesterCountryCode | requesterMemberStateCode |
| Requester VAT number | requesterVatNumber | requesterNumber |
| Postcode to match | traderPostcode | traderPostalCode |
Match result (trader*Match) | matchCode values "1", "2", "3" for valid, invalid, not processed | VALID, INVALID, NOT_PROCESSED |
requestDate | xsd:date; observed 2026-10-16+02:00, a date with an offset and no time | date-time; observed 2026-10-16T14:18:23.573Z |
| Name and address | checkVat returns name, address; checkVatApprox returns traderName, traderAddress, traderStreet, traderPostcode, traderCity | Both sets of fields in one response (observed) |
requestIdentifier | Only in the checkVatApprox response, where it is a mandatory string, so it can be empty | Optional string in the response |
The two requestDate formats matter if you store the value. One has no time at all, so it cannot prove when in the day the check ran. Record your own timestamp next to it.
requestIdentifier and the requester fields
The requestIdentifier is what VIES calls the consultation number: a reference tied to a check made with requester details. Whether it meets a tax authority’s evidence requirements depends on local rules; it is not a safe harbour. The consultation number explainer covers what it is evidence of. Here, only how to ask for one.
Per the Swagger description, you get it by supplying the requester: ‘the information about requesterMemberStateCode and requesterNumber have to be provided.’ On SOAP that means calling checkVatApprox, because checkVat has no such element in its response. That is the documented part.
What we saw is narrower. All our production calls used invented, invalid targets, so we did not see a real requestIdentifier issued in production, and we are not describing its format. The test services do not model production behaviour here: the SOAP test service returned a WAPI0000001 identifier even for an invalid number, and the REST one returned an empty string for a valid one. Do not copy identifier logic from them.
As for the requester itself: DE123456789 with the made-up requester FI12345678 was not rejected over SOAP or REST: HTTP 200, valid false, empty identifier. A requester from a non-EU country, US12345678, was refused in both, with different shapes (next section). Because the target failed anyway, these calls cannot show how VIES treats a malformed requester next to a valid target. A note in vatnode’s code records that a requester that was well formed but not registered still received an identifier, so we treat VIES as checking the requester for form, not registration. That is our observation, not a documented VIES rule.
How each one fails
Everything below was observed on 16 Oct 2026. These are our calls, not documented guarantees, and the VOW-ERR codes are not listed in the Swagger file.
| Call | HTTP | What came back |
|---|---|---|
SOAP, countryCode XX | 200 | <env:Fault> with faultstring INVALID_INPUT |
SOAP checkVatApprox, requester US12345678 | 200 | Fault with faultstring Invalid Requester member state (text, not a code) |
| SOAP, malformed XML | 400 | Empty body |
REST, countryCode XX | 200 | {"actionSucceed":false,"errorWrappers":[{"error":"INVALID_INPUT"}]} |
REST, requester US12345678 | 400 | errorWrappers with VOW-ERR-2500 and the message The requester member state code is invalid. |
| REST, malformed JSON | 500 | errorWrappers with VOW-ERR-1 and An unexpected error occurred. Please retry later or contact the support team. |
REST, GET on /check-vat-number | 405 | Plain text: Request method 'GET' not supported |
The Swagger file documents the error body only under 400 and 500, yet the INVALID_INPUT call arrived with 200. The test services behaved the same way: SERVICE_UNAVAILABLE and GLOBAL_MAX_CONCURRENT_REQ came back as HTTP 200 on REST (in errorWrappers) and SOAP (as faults).
The malformed JSON line is the one to remember. A client-side bug produced a 500 with a message that says ‘retry later’, and a plain retry-on-5xx loop would keep retrying that request without ever succeeding. Read the body first: in SOAP, look for a <faultstring>; in REST, for errorWrappers or actionSucceed set to false. Only then look at the status, and treat a 500 whose input never changes with suspicion.
For what each SOAP faultstring means and what to retry, see VIES SOAP fault strings explained. The codes vatnode returns are in the error reference, and handling VIES errors in code covers the calling side.
Timeouts and availability
Choose your own timeout budget, set it on every call, and treat expiry as ‘not checked yet’, never as invalid. For reference, vatnode’s budgets are 12 seconds for SOAP and 6 seconds for the REST retry. Those are vatnode’s choices, not limits set by VIES.
GET /check-status returns vow.available and a per-member-state list with Available, Unavailable or Monitoring Disabled. On 16 Oct 2026 every country listed was Available. Use it as a hint, for example to delay a batch. It is not a promise that your next call will succeed. For how often VIES fails in practice, see VIES uptime, measured, the live VIES status page, and the downtime guide.
Which one to call
- New code: REST (our recommendation; we found no official guidance that prefers either). JSON, a plain POST, no envelope and no generated client. The field names are also what the Swagger file says, so you can read the spec instead of a WSDL.
- Existing generated SOAP client: keep it, but override the endpoint to https and add the body-first check for a fault.
- Either way: both protocols can deliver a failure with HTTP 200, so switching protocol does not save you the body check.
Owning this is a fair amount of work: two failure shapes, --- placeholders, a retry policy, a cache and a record of what you checked. For occasional checks you can skip all of it. The free plan is 100 checks a month at €0, with no SOAP or REST client to maintain. vatnode’s response uses the same fields whichever VIES protocol answered, and with your own EU VAT number set as requester, valid results carry the consultation number. The full trade-off is in build vs buy for VAT validation.
If you do call VIES yourself, the checklist is: https endpoint, body before status, a timeout you chose, --- to null, and your own timestamp saved with the result.
How vatnode uses both
SOAP is the primary path: checkVat when no requester VAT is set, checkVatApprox when it is. The requester VAT is set once in the dashboard’s Account details. With it set, a valid result carries a consultation number; if VIES sends an empty one twice, vatnode returns an error instead of a verdict without it. The SOAP-first order is a design choice in vatnode’s code, not a measured ranking: we have no data showing either protocol is more reliable.
After a SOAP network error, SERVICE_UNAVAILABLE or an unparseable reply, vatnode makes one retry through REST POST /check-vat-number with a 6-second budget, carrying the requester over so the retry can still return a requestIdentifier. There is no REST retry after MS_UNAVAILABLE or TIMEOUT. If REST fails too, the caller gets the original SOAP error.
On both paths vatnode reads the body before the status: errorWrappers for REST, the faultstring for SOAP, so a recognised fault delivered with 200 is mapped before parsing. An unrecognised fault string is treated as an unparseable reply, which triggers the REST retry. The --- placeholders and empty strings become null. The fault mapping is in VIES SOAP fault strings explained, and the countries with extra register data are listed in the coverage docs.
To hand this to vatnode instead, create a free API key (100 checks a month, €0), set your own EU VAT number as requester in the dashboard to get consultation numbers, then follow the quickstart. To try one number first, use the checker.
FAQ
Does VIES have a REST API?
Yes. The Commission publishes a Swagger 2.0 description (https://ec.europa.eu/assets/taxud/vow-information/swagger_publicVAT.yaml) of a JSON endpoint at https://ec.europa.eu/taxation_customs/vies/rest-api, with POST /check-vat-number for the check itself and GET /check-status for availability. It sits alongside the SOAP checkVatService, which also answered our calls on 16 Oct 2026.
Is the VIES SOAP API still available, and where is the WSDL?
On 16 Oct 2026 the SOAP endpoint at https://ec.europa.eu/taxation_customs/vies/services/checkVatService answered our calls. The WSDL is at https://ec.europa.eu/taxation_customs/vies/checkVatService.wsdl. We found no official deprecation notice for SOAP or REST. The WSDL points at a plain http address, so override it to https if you generate a client.
What is the difference between checkVat and checkVatApprox in VIES?
checkVat takes a country code and a VAT number. checkVatApprox adds optional trader name and address fields to match against, and optional requester country code and requester VAT number. According to the Commission’s REST description, the requestIdentifier (the consultation number) is retrieved by supplying the requester details. We did not see a real one issued in our tests, and the field is allowed to be empty, so check it before you store it.
Why does VIES return HTTP 200 for an error?
In our calls on 16 Oct 2026, several failures came back as HTTP 200: a SOAP fault, and a REST body with actionSucceed set to false. Other failures came back as 400 or 500. The status code is not a reliable signal, so read the body first, then the status.