Three checks that are usually three vendors
The Validation API checks business and contact identifiers as clean JSON.
4 active endpoints. Every call is 1 credit.
- POST/validate/v1/vat
- POST/validate/v1/iban
- POST/validate/v1/email
- POST/validate/v1/batch
What Validation endpoints does ReefAPI ship?
4 live read endpoints. Read-only data API: no writes, no account actions, no dashboard access on the target site.
Validation API
3 of 4 endpoints, ready to run
A live VIES lookup: whether the number is registered, and when it is, the company name and address the tax authority holds for it.
{ "ok": true, "meta": { "api": "validate", "endpoint": "vat", "mode": "live", "latency_ms": 1191.8, "record_count": 1, "cache_hit": false }, "data": { "valid": true, "format_valid": true, "query": "IE6388047V", "vat_number": "6388047V", "full_vat_number": "IE6388047V", "country_code": "IE", "vies_country_code": "IE", "company_name": "GOOGLE IRELAND LIMITED", "company_address": "3RD FLOOR, GORDON HOUSE, BARROW STREET, DUBLIN 4", "request_date": "2026-08-29T13:35:16.250Z", "request_identifier": null, "consultation_number": null, "user_error": "VALID", "source": "vies" } }
How the Validation API works
Validation is a normal ReefAPI surface — the same four rules that hold for every other engine on the key.
No OAuth app, no request signing, no per-site account. One key covers all 184 engines.
Every route is a POST with a JSON body. Parameters are validated against the published schema before anything is charged.
Credits, not seats. Failed and blocked calls are never charged, and cache hits cost nothing.
One envelope everywhere. meta carries latency_ms, record_count and the endpoint that answered.
Screening a B2B signup at the point of entry
A business signup form gives you three fields that each lie in a different way. The order matters: do the free offline check first and only spend a network call once the input is worth one.
{"email": "[email protected]"}Rejects typo domains and disposable mail before anything else runs. Returns did_you_mean when the domain is a near-miss.
{"iban": "DE89370400440532013000"}Arithmetic, not a lookup — it answered in tens of milliseconds. Fails give a reason, not just false.
{"vat_number": "IE6388047V"}The only one that leaves the building. A registered number comes back with the company name and address, which is the field you actually wanted.
The VAT response is the useful one: it turns a self-declared company name on your form into the name the tax authority has on file, which is a different claim entirely.
curl -X POST https://api.reefapi.com/validate/v1/vat \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"vat_number":"IE6388047V"}'{
"ok": true,
"data": { … },
"meta": {
"api": "validate",
"endpoint": "vat",
"mode": "live",
"latency_ms": …,
"record_count": …
},
"error": null
}What `valid` actually asserts in each of the three checks
The three checks answer three different questions, and a single boolean hides that. Read this before you branch on valid. Each check also keeps reporting the parts it did establish when the overall verdict is false, so a failure is diagnosable rather than opaque.
| Check | `valid: true` means | What you still get when it is false |
|---|---|---|
| iban | the ISO 13616 mod-97 checksum passes — computed locally, no bank is contacted | country_code, country_name, check_digits, length, sepa and the full checksum object; bban, bank_code, branch_code and account_number all go null and reason names the failure |
| vat | VIES answered that the number is registered at the moment you asked | format_valid reports the syntax verdict separately, so you can tell a malformed number from a well-formed but unregistered one; company_name and company_address are the VIES record when there is one |
| syntax parses, the domain has MX, and the address is not disposable | syntax_valid, has_mx, mx_records, is_disposable, is_role_account, is_free_provider, did_you_mean and a 0–100 score are each returned independently | |
| batch | n/a — the wrapper | count and valid_count plus every item's own record; a bad item comes back valid:false and never fails the batch |
A measured bad-checksum IBAN (DE89370400440532013001) returned valid:false, reason 'checksum_failed' and checksum {remainder: 28, expected: 1}. The remainder is exposed on purpose — if you are reconciling against another validator, that number tells you whether you disagree about the math or about the input.
Which of these three is authoritative, and which is a heuristic
Measured with a good input, a bad input and an edge case on each endpoint. Two of these go against us.
A registered Irish number came back valid with the company name and street address the registry holds. An unregistered German number with a perfectly legal format came back valid false with format_valid still true — the two are reported separately, so you can tell a typo from a number that simply is not registered. The response also carries the request timestamp, because a VAT check is evidence and evidence needs a date.
GB numbers are no longer in the EU system. Ask for one and the country_code stays GB while the answering registry comes back as XI — Northern Ireland — and the number reads as unregistered even when the business is trading normally. That is the registry's post-Brexit behaviour, not a fault we can fix, and it means this endpoint is not a UK VAT check. The XI code is in the payload so you can detect the case rather than trusting the boolean.
Changing one digit of a valid German IBAN returned valid false with reason checksum_failed, plus the checksum block naming the algorithm and the remainder it computed. The valid version splits into bank code, account number and a printable grouped form. It answered in tens of milliseconds against roughly a second for the VAT call, because nothing leaves the building.
A Turkish IBAN validated cleanly and came back with sepa false. The account is real and the number is correct; it is simply outside the single-payments area. Treating valid as payable is the mistake this field exists to prevent.
An address that does not exist at a real domain looks identical to one that does — both return syntax valid with the domain's live MX records. What is genuinely checked is the domain, not the person: a disposable-mail domain was flagged, and the mail servers returned are the ones DNS is actually publishing. Mailbox-level verification is a different act with different deliverability consequences, and this endpoint does not claim it.
With MX checking on, the check took about twice as long and returned the mail servers. With it off, it stayed a pure string check and has_mx came back null rather than false — an unknown that reads as unknown, instead of a negative you might act on.
What people build with Validation
The jobs this data is most often used for.
endpoints
credit per call
Billing systems call vat and iban to validate a customer's tax and bank details.
Onboarding forms use email validation to catch typos and undeliverable addresses.
Compliance pipelines use batch to validate a list of records.
What Validation data costs
The cheapest call here is 1 credit, so $15/mo (Pro) buys 10,000 of them — $1.50 per 1,000 credits. Credits roll over and never expire, and failed or blocked calls are not charged.
Full pricing →- 1,000 free credits on signup, no card
- One key, all 184 APIs, one credit pool
- Failed and blocked calls are never charged
- Credits roll over and never expire
Call it in two lines
Sign up, get 1,000 credits and one key that works on every engine. Then this is the whole protocol.
curl -X POST https://api.reefapi.com/validate/v1/vat \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"vat_number":"IE6388047V"}'import requests
r = requests.post(
"https://api.reefapi.com/validate/v1/vat",
headers={"x-api-key": REEF_KEY},
json={
"vat_number": "IE6388047V"
},
)
print(r.json()["data"])Have a question? We got answers.
The questions people actually ask before wiring up Validation.
Get a free key →Why is an address at a disposable domain valid:false when has_mx is true?▾
Because MX presence and usefulness are different questions. A measured check on [email protected] returned syntax_valid true, has_mx true with two real MX hosts, is_disposable true, and then valid false, deliverable false and score 10. Mail sent there really would be accepted — it just lands in a throwaway inbox. If you want the raw DNS answer rather than our verdict, read has_mx and mx_records and ignore valid.
Why did a perfectly real corporate address score 85 instead of 100?▾
A measured check on [email protected] came back valid true, deliverable true, is_disposable false, has_mx true across five Google MX hosts — and score 85, because is_role_account was true. Role addresses (info@, support@, sales@) are shared mailboxes: deliverable, but a poor signal for a signup form or a lead record. The score is there so you can set your own threshold instead of accepting our binary.
Does the IBAN check contact the bank or go over the network?▾
No. IBAN validation is pure local arithmetic — ISO 7064 MOD-97-10 over the rearranged string — so it works for every IBAN-adopting country and cannot be rate-limited or return a stale answer. The one optional network step is enrich, which looks up BIC and bank name/city and is off by default. Enrichment never changes the validity verdict; the mod-97 result is computed before it runs. Bank-directory coverage there is proven live for DE, NL, LU and LI, and thinner elsewhere.
Why is bank_code numeric for a German IBAN and letters for a British one?▾
Because the BBAN layout is defined per country, not globally, and the parser reports whatever that country's format specifies. Measured: DE89 3704 0044 0532 0130 00 yields bank_code '37040044' (8 digits), branch_code null, account_number '0532013000'. GB29 NWBK 6016 1331 9268 19 yields bank_code 'NWBK' (the 4-letter bank identifier), branch_code '601613' (the sort code) and account_number '31926819'. Both are 22 characters long, which is coincidence, not a rule — IBAN length varies by country. Store bank_code as a string.
What does the VAT response tell me beyond a yes/no?▾
A measured VIES lookup on IE6388047V returned valid true, format_valid true, the normalized split (country_code 'IE', vat_number '6388047V', full_vat_number 'IE6388047V'), company_name 'GOOGLE IRELAND LIMITED' and company_address, plus request_date as an ISO-8601 UTC timestamp. request_identifier and consultation_number came back null in that lookup, so do not build an audit trail on them — log request_date and the response instead. VIES uses EL for Greece and XI for Northern Ireland; GR and GB are accepted and mapped for you.
Can I validate a mixed list in one request?▾
Yes — batch takes up to 100 items shaped {type: vat|iban|email, value: ...}, mixing all three types freely, and VAT items may carry their own country. Each item is validated independently and tagged with its type in results[], and count plus valid_count give you the tally without walking the array. It is the right call for cleaning an imported customer table.
How do I make the email check offline and fast?▾
Set check_mx to false. You then get syntax parsing, the disposable-domain verdict, the role-account and free-provider flags and did_you_mean, with no DNS-over-HTTPS lookup at all. has_mx will be unresolved rather than false, so branch on mx_checked, not on has_mx, when you run in that mode.
What is the Validation API?▾
Validation API is a ReefAPI endpoint group for validation It returns live JSON through POST requests under /validate/v1.
Is the Validation API free to try?▾
Yes. ReefAPI starts with 1,000 free credits, no card required. Validation calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Validation login or account?▾
No login to Validation is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Validation data?▾
The page example is captured from a live vat call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the Validation API use?▾
Validation actions currently cost 1 credit per successful call. Failed or blocked calls are free, and all APIs draw from one credit pool.
Can I call Validation from an AI assistant or MCP client?▾
Yes. Connect ReefAPI once through MCP and your assistant can call validate actions with the same key, credit pool and JSON envelope used by normal REST requests.
Is the Validation API a Validation scraper?▾
It is the managed alternative to a DIY Validation scraper. Instead of building and maintaining your own scraper — proxies, headless browsers, captcha and constant breakage — you call one ReefAPI endpoint and get the same validation back as clean JSON.
19 Utilities & AI APIs on the same key
One key, one credit pool, one response envelope. If you are pulling Validation, you are one call away from the rest of the category — no second contract, no second integration.
Need something this API does not do?
Name the endpoint, the field, or a source we do not carry yet. We ship new APIs every week and you would be first to get the key. Real people read every message and reply the same day.
Try it on your own data before you pay anything
The call above is the real endpoint, not a recording. A free key gives you 1,000 credits, the other 183 APIs, and the same envelope everywhere.
Endpoints, parameters and credit costs on this page are read from the live catalog and cannot drift from what the API accepts. Field notes were captured on 2026-08-30.