{"openapi":"3.0.3","info":{"title":"Validation API (ReefAPI)","version":"1.0.0","description":"Validation API — validate EU VAT numbers (VIES), IBAN bank accounts (offline) and email addresses (syntax + MX + disposable) in one call Call POST /validate/v1/{action} with an x-api-key header; every response is the { ok, data, meta, error } envelope.","contact":{"name":"ReefAPI","url":"https://reefapi.com/validate-api","email":"support@reefapi.com"},"license":{"name":"ReefAPI Terms","url":"https://reefapi.com/terms"},"termsOfService":"https://reefapi.com/terms"},"externalDocs":{"description":"Validation API documentation","url":"https://reefapi.com/docs/validate"},"servers":[{"url":"https://api.reefapi.com"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"validate","description":"Validation API — validate EU VAT numbers (VIES), IBAN bank accounts (offline) and email addresses (syntax + MX + disposable) in one call"}],"paths":{"/validate/v1/vat":{"post":{"operationId":"validate_vat","summary":"Validate an EU VAT number via VIES → validity + registered company name & address.","description":"Validate an EU VAT number via VIES → validity + registered company name & address.","tags":["validate"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vat_number":{"type":"string","example":"IE6388047V","description":"The VAT number to validate against EU VIES. Either a full VAT incl. the 2-letter country prefix (e.g. 'IE6388047V', 'DE811569869') or just the digits when you also pass `country`. Spaces/dots/dashes are ignored."},"country":{"type":"string","example":"IE","description":"ISO-3166 / VIES country code for the VAT number (e.g. DE, FR, IE, NL). Optional if `vat_number` already starts with the prefix. VIES uses EL for Greece and XI for Northern Ireland; GR/GB are accepted and mapped."}},"required":["vat_number"]},"example":{"vat_number":"IE6388047V"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/validate/v1/iban":{"post":{"operationId":"validate_iban","summary":"Validate + parse an IBAN offline (ISO 13616 mod-97) → country, BBAN, bank/branch/account","description":"Validate + parse an IBAN offline (ISO 13616 mod-97) → country, BBAN, bank/branch/account. Optional enrich=true adds BIC + bank name/city (openiban.com, proxied).","tags":["validate"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"iban":{"type":"string","example":"DE89370400440532013000","description":"The IBAN to validate + parse (offline, ISO 13616 mod-97). Spaces and dashes are ignored; case-insensitive. Returns country, check-digits, BBAN, bank/branch/account, and the checksum math."},"enrich":{"type":"boolean","default":false,"example":false,"description":"If true and the IBAN is valid, also fetch BIC + bank name/city from openiban.com (free, proxied). Bank-directory coverage is openiban's supported set (proven live: DE/NL/LU/LI; AT/BE/CH listed but their directory may miss codes). Never changes the validity verdict — the mod-97 result is ours, offline. Default false keeps iban 100% offline."}},"required":["iban"]},"example":{"iban":"DE89 3704 0044 0532 0130 00"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/validate/v1/email":{"post":{"operationId":"validate_email","summary":"Validate an email: syntax + live MX + disposable-domain + role-account flags.","description":"Validate an email: syntax + live MX + disposable-domain + role-account flags.","tags":["validate"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","example":"jane.doe@google.com","description":"The email address to validate: RFC-5322-pragmatic syntax + live MX lookup (DNS-over-HTTPS) + disposable-domain + role-account detection."},"check_mx":{"type":"boolean","default":true,"example":true,"description":"Whether to perform the live MX/DNS lookup (default true). Set false for a pure offline syntax+disposable check (no network, faster)."}},"required":["email"]},"example":{"email":"jane.doe@google.com"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/validate/v1/batch":{"post":{"operationId":"validate_batch","summary":"Validate up to 100 mixed items ({type:vat|iban|email,value}) in one call.","description":"Validate up to 100 mixed items ({type:vat|iban|email,value}) in one call.","tags":["validate"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"},"example":[{"type":"iban","value":"DE89370400440532013000"},{"type":"email","value":"info@stripe.com"},{"type":"vat","value":"IE6388047V"}],"description":"Up to 100 mixed validation items. Each is an object {type: vat|iban|email, value: <string>} (vat items may also carry a `country`). Each item is validated independently — a bad entry yields valid:false, it never fails the whole batch."},"check_mx":{"type":"boolean","default":true,"example":true,"description":"Whether to perform the live MX/DNS lookup (default true). Set false for a pure offline syntax+disposable check (no network, faster)."}},"required":["items"]},"example":{"items":[{"type":"iban","value":"DE89370400440532013000"},{"type":"email","value":"test@mailinator.com","check_mx":false},{"type":"iban","value":"bad"}]}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Envelope":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean"},"data":{"description":"Action result (shape varies per action)"},"meta":{"type":"object","description":"api, endpoint, mode, latency_ms, record_count, completeness_pct"},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}