W System / Quickstart: your first W System API call

Quickstart: your first W System API call

Short answer: paste the first command into a terminal. No signup, no key: you get a live answer from the European Commission's VIES service in about a second. When you're ready to integrate, get a free API key (500 units a month, no card) and send it as X-API-Key.

1. Call it without a key (30 seconds)

curl "https://api.wsystem.dev/verify?vat=IE6388047V"

The answer has status (valid, invalid, invalid_format, member_state_unavailable or error), the registered name and address where the member state discloses them, and a consultation_number. Pass your own EU VAT number as requester to get consultation numbers issued in your company's name for your audit file:

curl "https://api.wsystem.dev/verify?vat=IE6388047V&requester=YOUR_EU_VAT_NUMBER"

2. Get a free key (2 minutes)

Open api.wsystem.dev/account/free-key, enter your work email and confirm the link we send. The key is shown once and emailed to you. It works from any server, includes 500 units per calendar month (UTC) and never needs a card.

export WSYSTEM_KEY=wsk_live_...
curl -H "X-API-Key: $WSYSTEM_KEY" "https://api.wsystem.dev/verify?vat=DE811193231"
curl -H "X-API-Key: $WSYSTEM_KEY" "https://api.wsystem.dev/billing/usage"   # free: plan, units used, units left

3. The calls most teams start with

Check a business customer (VAT + register + sanctions in one call)

curl -X POST https://api.wsystem.dev/kyb/check -H "X-API-Key: $WSYSTEM_KEY" \
  -H "Content-Type: application/json" -d '{"company": "FR40303265045"}'

Validate an e-invoice (XRechnung, ZUGFeRD / Factur-X, Peppol BIS UBL) against EN 16931

curl -X POST https://api.wsystem.dev/einvoice/validate -H "X-API-Key: $WSYSTEM_KEY" \
  -H "Content-Type: application/xml" --data-binary @invoice.xml

Every failed rule comes back as JSON with the official rule ID (for example BR-DE-15), the business term it concerns and a fix hint. Try it without code in the browser validator.

Find a buyer's Peppol ID from a VAT number

curl -H "X-API-Key: $WSYSTEM_KEY" "https://api.wsystem.dev/einvoice/route?id=BE0897290877"

Python

import os, requests
r = requests.get("https://api.wsystem.dev/verify", params={"vat": "DE811193231"},
                 headers={"X-API-Key": os.environ["WSYSTEM_KEY"]}, timeout=30)
r.raise_for_status()
d = r.json()
print(d["status"], d.get("name"), r.headers.get("X-Units-Remaining"))

JavaScript

const r = await fetch("https://api.wsystem.dev/verify?vat=DE811193231",
  { headers: { "X-API-Key": process.env.WSYSTEM_KEY } });
const d = await r.json();
console.log(d.status, d.name, r.headers.get("X-Units-Remaining"));

Status codes you should handle

HTTPMeaningWhat to do
200Answer (also for invalid numbers: read status)Store the JSON as evidence
401 invalid_api_keyUnknown or replaced keyCheck X-API-Key or omit it to use the keyless free tier
402Keyless free calls used up; x402 payment requirements in the bodySend X-API-Key, or pay per call with x402
422Missing or malformed inputFix the request; the body says which field
429 monthly_quota_exhaustedNot enough units left this month; nothing was chargedUpgrade, wait for the 1st (UTC), or use x402
member_state_unavailable (in a 200)The national VAT backend behind VIES is downRetry later; never treated as invalid

Where to go next

Questions and answers

Do I need an API key to try it?

No. Every REST endpoint gives 20 free calls a day per IP without a key. For server-side tests, CI or shared cloud IPs, get a free key (500 units a month, no card).

What is a unit?

Plans and keys count units, not requests: most calls cost 1 unit; /kyb/check 5, /einvoice/validate 3, /einvoice/create and /einvoice/send 8, /ddreport 50. Every keyed response carries X-Units-Used and X-Units-Remaining.

What happens when VIES is down?

You get status member_state_unavailable (never a false invalid), or a flagged fallback from an official national source or the last dated VIES result. Retry later; see /vies-status.

Can I send live Peppol invoices today?

Not yet. /einvoice/send runs in sandbox mode: every step is real except delivery, which is simulated or handed to a partner Peppol sandbox. Live sending through a certified access-point partner is being set up; email [email protected] to be one of the first.

Facts and competitor details checked 2026-10-17. W System is the maker of this product. Not affiliated with the European Commission. Not legal or tax advice.