# Validation API — validate EU VAT numbers (VIES), IBAN bank accounts (offline) and email addresses (syntax + MX + disposable) in one call

> Validate an EU VAT number via VIES → validity + registered company name & address.
> ReefAPI engine `validate` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/validate/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /validate/v1/vat — 1 credit
Validate an EU VAT number via VIES → validity + registered company name & address.

**Parameters:**
- `vat_number` (string, required) — 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` (string, optional) — 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.

**Returns:** valid, format_valid, query, vat_number, full_vat_number, country_code, company_name, company_address, request_date, request_identifier, consultation_number, source ('vies')

**Example request body:**
```json
{
  "vat_number": "IE6388047V"
}
```

### POST /validate/v1/iban — 1 credit
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).

**Parameters:**
- `iban` (string, required) — 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` (boolean, optional, default false) — 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.

**Returns:** valid, iban, formatted, country_code, country_name, check_digits, bban, bank_code, branch_code, account_number, national_check, sepa, checksum{}, reason, bank{bic,name,zip,city} + enrich{attempted,source,bank_found} (enrich=true only)

**Example request body:**
```json
{
  "iban": "DE89 3704 0044 0532 0130 00"
}
```

### POST /validate/v1/email — 1 credit
Validate an email: syntax + live MX + disposable-domain + role-account flags.

**Parameters:**
- `email` (string, required) — The email address to validate: RFC-5322-pragmatic syntax + live MX lookup (DNS-over-HTTPS) + disposable-domain + role-account detection.
- `check_mx` (boolean, optional, default true) — Whether to perform the live MX/DNS lookup (default true). Set false for a pure offline syntax+disposable check (no network, faster).

**Returns:** valid, email, syntax_valid, local_part, domain, has_mx, mx_records[], is_disposable, is_role_account, is_free_provider, did_you_mean, deliverable, score (0-100), reason

**Example request body:**
```json
{
  "email": "jane.doe@google.com"
}
```

### POST /validate/v1/batch — 1 credit
Validate up to 100 mixed items ({type:vat|iban|email,value}) in one call.

**Parameters:**
- `items` (array, required) — 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` (boolean, optional, default true) — Whether to perform the live MX/DNS lookup (default true). Set false for a pure offline syntax+disposable check (no network, faster).

**Returns:** count, valid_count, results[] (each tagged with its type + the same record the single-action would return)

**Example request body:**
```json
{
  "items": [
    {
      "type": "iban",
      "value": "DE89370400440532013000"
    },
    {
      "type": "email",
      "value": "test@mailinator.com",
      "check_mx": false
    },
    {
      "type": "iban",
      "value": "bad"
    }
  ]
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=validate
- Human docs page: https://reefapi.com/docs/validate
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt