Documentation

RapidAPI base URL: https://vatpulse1.p.rapidapi.com · Direct base URL (direct customers): https://api.vatpulse.workers.dev · OpenAPI: 3.1 / 3.0 · Interactive: /docs/reference

Quick start

1. Subscribe to the free plan (100 validations/month) on RapidAPI and copy your X-RapidAPI-Key.
2. Validate:

curl -X POST https://vatpulse1.p.rapidapi.com/validate \
  -H "X-RapidAPI-Key: $RAPIDAPI_KEY" \
  -H "X-RapidAPI-Host: vatpulse1.p.rapidapi.com" \
  -H "Content-Type: application/json" \
  -d '{"vat": "IE6388047V", "iban": "DE89 3704 0044 0532 0130 00"}'

JavaScript

const res = await fetch("https://vatpulse1.p.rapidapi.com/validate", {
  method: "POST",
  headers: {
    "X-RapidAPI-Key": process.env.RAPIDAPI_KEY,
    "X-RapidAPI-Host": "vatpulse1.p.rapidapi.com",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ vat: "NL004495445B01" }),
});
const { vat } = await res.json();
if (vat.valid === true) { /* registered */ }
else if (vat.valid === false) { /* not registered or malformed: vat.error.code */ }
else { /* unknown right now (upstream down): retry later */ }

Python

import requests
r = requests.post(
    "https://vatpulse1.p.rapidapi.com/validate",
    headers={"X-RapidAPI-Key": RAPIDAPI_KEY, "X-RapidAPI-Host": "vatpulse1.p.rapidapi.com"},
    json={"iban": "FR1420041010050500013M02606"},
    timeout=15,
)
print(r.json()["iban"])

Authentication

RapidAPI (default): call https://vatpulse1.p.rapidapi.com with your X-RapidAPI-Key and X-RapidAPI-Host: vatpulse1.p.rapidapi.com headers. RapidAPI handles keys, plans and billing.

Direct keys: direct customers receive a key (vk_live_…) from us and call https://api.vatpulse.workers.dev with it in the X-API-Key header (Authorization: Bearer <key> also works). Self-serve signup on this site is closed; use RapidAPI or ask via the RapidAPI listing.

POST /validate

JSON body with vat, iban, or both (strings). Spaces, dots and dashes are ignored. VAT numbers need their 2-letter prefix; Greece is EL (we also accept GR), Northern Ireland is XI (checked via VIES). UK GB numbers via HMRC are coming soon (built, not yet enabled); until then they return service_unavailable and are not billed.

HTTP 200 is returned whenever at least one component produced a definitive answer. If nothing could be answered, the status reflects the error (400 bad input, 503 upstream down with nothing cached).

Response fields

vat

iban

An IBAN check confirms the number is well-formed. It cannot confirm that the account exists or is open.

Error codes

* When the component is answered as valid:false the HTTP status is 200; 4xx is used when no component could be answered.

Caching & outages

• Valid VAT results are cached for 24h; valid:false results for 1h (so newly registered numbers show up quickly).
• Every successful answer is also kept as a last-known-good copy for 30 days. If VIES/HMRC or the member state is down, you get that copy with stale:true, its original checked_at, and a warning.
• If there is no copy, you get an explicit 503 (member_state_unavailable or service_unavailable) with Retry-After, never a false valid:false.
• IBAN results are computed offline and always available; repeat checks within 24h are free cache hits. We never store the IBAN itself, only a keyed hash (HMAC-SHA256) used as a 24h cache marker. See Privacy.

Billing & quotas

You pay only for successful validations: a request counts once if at least one component produced a fresh definitive result (VIES/HMRC answered, or the IBAN checksum ran). Free: cache hits, stale fallbacks, input rejected by format/length checks, upstream errors, auth and rate-limit errors. The response field billable tells you. On RapidAPI, usage is reported to RapidAPI as a custom Validations quota (header X-RapidAPI-Billing: Validations=1|0) and your balance is in the RapidAPI dashboard; direct keys get X-Quota-Limit, X-Quota-Remaining and X-Quota-Reset headers. Quotas reset on the 1st of each month (UTC). The per-minute limit applies to all requests.

GET /usage

curl https://vatpulse1.p.rapidapi.com/usage -H "X-RapidAPI-Key: $RAPIDAPI_KEY" -H "X-RapidAPI-Host: vatpulse1.p.rapidapi.com"
{
  "plan": "free", "monthly_quota": 100, "used": 12, "remaining": 88,
  "period_start": "2026-10-01T00:00:00.000Z", "reset_at": "2026-11-01T00:00:00.000Z",
  "rate_limit_per_minute": 10, "requests_this_month": 31
}

GET /status

Public. Live VIES availability per member state (cached 60s). Handy before batch jobs.

Coverage

VAT

IBAN

Checksum, length and structure validation for all 127 countries in the SWIFT IBAN registry (plus a few partial adopters).

Bank name / BIC lookup

Derived from openly published national bank directories (Deutsche Bundesbank, OeNB, NBB, Betaalvereniging, Banco de España, Banca d'Italia, SIX, NBP and others) via the MIT-licensed schwifty registry. Countries marked "major banks only" have curated lists rather than full official directories. Lookups are by bank code (and for some countries bank+branch); bank is null when not covered.