Name: EU VAT and IBAN Validation API with VIES | VatPulse
Brand: vatpulse
SKU: api-vatpulse-eu-vat-iban
Availability: InStock
Author: API Market

VatPulse

# VatPulse EU VAT and IBAN Validation API

## Overview

The VatPulse EU VAT and IBAN Validation API checks European VAT numbers and IBANs through one request. It has 3 endpoints. The validate endpoint does the work: send a VAT number, an IBAN, or both in a JSON body and get back a separate result block for each. VAT numbers are checked live against VIES, the European Commission's VAT Information Exchange System, and the provider states coverage of all 27 EU member states plus Northern Ireland (`XI`). Where the member state discloses it, the VAT result includes the registered company name and address. IBANs are checked offline: the provider runs the mod-97 checksum and per-country structure rules for 127 countries, splits the IBAN into bank code, branch code and account number, and looks up the bank name and BIC for 43 countries. The usage endpoint reports what VatPulse has counted for your key this month, and the health endpoint is a simple liveness check.

It is built for checkout and invoicing flows that must confirm a business customer's VAT number before applying the EU reverse charge, onboarding and KYB teams that want the registered name and address behind a VAT number, and payment or payroll systems that need to catch mistyped IBANs before a transfer goes out. Every validate response has the same shape: a `request_id`, a `vat` block and an `iban` block for whatever you sent, a `billable` flag and a `usage` block. Each block carries `valid` (`true`, `false`, or `null` when the answer could not be determined), the normalized input, and an `error` object with a `code` and a plain-English `message` when something is wrong. VAT results also tell you whether they came from cache (`cached`), whether they are a last-known-good copy served during an outage (`stale`), and when the authority confirmed them (`checked_at`).

## Features

*   **3 endpoints**: Validate a VAT number and/or an IBAN, get usage for your key, and a health check.
*   **Simple inputs**: A JSON body with `vat`, `iban`, or both. VAT numbers need their 2-letter country prefix; spaces, dots and dashes are ignored, so IBANs can be sent in print format with spaces.
*   **Live VIES checks**: VAT numbers are checked against the official EU VIES service, and the response includes the registered name and address when the member state provides them.
*   **EU and Northern Ireland coverage**: The provider covers the 27 EU member states plus Northern Ireland (`XI`). Greek numbers can use either `EL` or `GR`.
*   **Outage handling**: Successful VAT results are cached for 24 hours. When VIES or a member state is down, the API returns the last known good result with `stale: true` and a `warning`, or `valid: null` with an error code and a `Retry-After` header if nothing is cached, instead of failing the request.
*   **IBAN parsing and bank lookup**: Offline mod-97 checksum and structure checks for 127 countries, with the IBAN split into check digits, BBAN, bank code, branch code and account number, a SEPA flag, and bank name and BIC for 43 countries.
*   **Clear error codes**: Problems come back as codes such as `invalid_checksum`, `invalid_format`, `invalid_country`, `invalid_length` and `member_state_unavailable`, each with a readable message.
*   **Rate limit**: 10 requests per second on every plan.

## Use Cases

*   **EU reverse charge at checkout**: Confirm a B2B customer's VAT number is active in VIES before you drop VAT from the invoice, and store `checked_at` as evidence of the check.
*   **Customer onboarding and KYB**: Compare the company name and address returned by VIES with what the customer entered.
*   **Supplier and vendor master data**: Validate VAT numbers and IBANs when a supplier is added, so bad records never reach accounts payable.
*   **Payment and payout forms**: Catch mistyped IBANs with the checksum check and show the bank name back to the user before a SEPA transfer is sent.
*   **Bulk data cleanup**: Run existing CRM or ERP records through the validate endpoint to flag invalid VAT numbers and IBANs.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/vatpulse/eu-vat-iban
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Validate a VAT number and/or an IBAN

Validates a VAT number, an IBAN, or both in one call and returns a `vat` block and an `iban` block for whatever you sent. The VAT block includes the normalized number, country, validity, and the registered name and address when the member state discloses them. The IBAN block includes the electronic and print formats, the check digits, BBAN, bank code, branch code, account number, a SEPA flag and, where the bank code is in the provider's dataset, the bank name and BIC. Every validation outcome returns HTTP `200`, including invalid numbers and upstream outages, so always read `valid` and `error` in each block. `valid: null` means "not checked, retry later", never "invalid". UK `GB` VAT numbers are not checked yet and return `valid: null` with `error.code: service_unavailable`.

**Method:** `POST`

**Endpoint:** `/validate`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `vat` | body | VAT number with its 2-letter country prefix, for example `IE6388047V`, `DE123456789`, `EL...` or `GR...` for Greece, or `XI...` for Northern Ireland. Spaces, dots and dashes are ignored. | string | Yes, unless `iban` is sent | - | 40 characters |
| `iban` | body | IBAN, with or without spaces, for example `DE89370400440532013000` or `DE89 3704 0044 0532 0130 00`. | string | Yes, unless `vat` is sent | - | 60 characters |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/vatpulse/eu-vat-iban/validate" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vat": "IE6388047V", "iban": "DE89370400440532013000"}'
```

**Example Response (200 OK):**

```json
{
  "request_id": "a4cdb12848b814f4",
  "vat": {
    "input": "IE6388047V",
    "valid": true,
    "vat_number": "IE6388047V",
    "country_code": "IE",
    "country_name": "Ireland",
    "name": "GOOGLE IRELAND LIMITED",
    "address": "3RD FLOOR, GORDON HOUSE, BARROW STREET, DUBLIN 4",
    "source": "vies",
    "cached": false,
    "stale": false,
    "checked_at": "2026-10-19T06:23:06.101Z",
    "consultation_number": null,
    "error": null,
    "warning": null
  },
  "iban": {
    "input": "DE89370400440532013000",
    "valid": true,
    "iban": "DE89370400440532013000",
    "iban_formatted": "DE89 3704 0044 0532 0130 00",
    "country_code": "DE",
    "check_digits": "89",
    "bban": "370400440532013000",
    "bank_code": "37040044",
    "branch_code": null,
    "account_number": "0532013000",
    "sepa": true,
    "bank": {
      "bic": "COBADEFFXXX",
      "name": "Commerzbank Köln"
    },
    "source": "offline",
    "error": null,
    "cached": true
  },
  "billable": true,
  "usage": {
    "plan": "apimarket",
    "used": 1,
    "limit": null,
    "remaining": null,
    "reset_at": "2026-11-01T00:00:00.000Z",
    "note": "Quota and billing for API.market subscriptions are managed by API.market, the marketplace you subscribed through."
  }
}
```

When the inputs are not valid, the response is still `200`. In this example the VAT number is not registered in VIES, so `valid` is `false` with no error, and the IBAN fails the checksum, so its `error` explains why.

**Example Request (invalid inputs):**

```bash
curl -X POST "https://prod.api.market/api/v1/vatpulse/eu-vat-iban/validate" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vat": "DE000000000", "iban": "GB00WEST12345698765432"}'
```

**Example Response (200 OK, invalid inputs):**

```json
{
  "request_id": "a4cdb13978e77b57",
  "vat": {
    "input": "DE000000000",
    "valid": false,
    "vat_number": "DE000000000",
    "country_code": "DE",
    "country_name": "Germany",
    "name": null,
    "address": null,
    "source": "vies",
    "cached": false,
    "stale": false,
    "checked_at": "2026-10-19T06:23:08.289Z",
    "consultation_number": null,
    "error": null,
    "warning": null
  },
  "iban": {
    "input": "GB00WEST12345698765432",
    "valid": false,
    "iban": "GB00WEST12345698765432",
    "iban_formatted": "GB00 WEST 1234 5698 7654 32",
    "country_code": "GB",
    "check_digits": "00",
    "bban": "WEST12345698765432",
    "bank_code": "WEST",
    "branch_code": "123456",
    "account_number": "98765432",
    "sepa": true,
    "bank": null,
    "source": "offline",
    "error": {
      "code": "invalid_checksum",
      "message": "The IBAN check digits are wrong (mod-97 checksum failed). Likely a typo."
    },
    "cached": false
  },
  "billable": true,
  "usage": {
    "plan": "apimarket",
    "used": 2,
    "limit": null,
    "remaining": null,
    "reset_at": "2026-11-01T00:00:00.000Z",
    "note": "Quota and billing for API.market subscriptions are managed by API.market, the marketplace you subscribed through."
  }
}
```

#### 2. Get usage

Returns what VatPulse has counted for your key in the current month: `used` (validations it treated as billable), `requests_this_month` (all validate requests, including cache hits), the period start and reset dates, and its per-minute abuse-protection limit. For API.market subscriptions, `monthly_quota` and `remaining` are `null` because your quota and billing are managed by API.market; check your plan usage in your API.market dashboard.

**Method:** `GET`

**Endpoint:** `/usage`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| - | - | This endpoint takes no parameters. | - | - | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/vatpulse/eu-vat-iban/usage" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "plan": "apimarket",
  "plan_name": "API.market",
  "price_usd_per_month": 0,
  "monthly_quota": null,
  "used": 2,
  "remaining": null,
  "period_start": "2026-10-01T00:00:00.000Z",
  "reset_at": "2026-11-01T00:00:00.000Z",
  "rate_limit_per_minute": 600,
  "requests_this_month": 3,
  "key_id": null,
  "marketplace": "apimarket",
  "note": "Quota and billing for API.market subscriptions are managed by API.market, the marketplace you subscribed through."
}
```

#### 3. Health check

Returns a simple liveness signal for the service with the current server time. Use it in monitoring to confirm the API is reachable before sending validations.

**Method:** `GET`

**Endpoint:** `/health`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| - | - | This endpoint takes no parameters. | - | - | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/vatpulse/eu-vat-iban/health" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "ok": true,
  "service": "vat-iban-api",
  "time": "2026-10-19T06:23:13.077Z"
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded. The validate endpoint returns `200` for every validation outcome, including invalid numbers (`valid: false`) and VIES or member state outages (`valid: null` with an `error` and a `Retry-After` header). |
| 400 | Bad Request | The request body is malformed or empty, or the input cannot be parsed, for example an unknown country prefix or a value of the wrong length (`invalid_request`, `invalid_format`, `invalid_country`, `invalid_length`). |
| 401 | Unauthorized | The `x-api-market-key` value is missing, invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The endpoint path does not exist. Check the path against the base URL above. |
| 429 | Too Many Requests | You went over 10 requests per second, or you have used all the calls in your plan. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |

## Rate Limits

The Free, Starter and Pro plans each allow 10 requests per second. They include 100, 2,000 and 10,000 calls respectively. Requests above the per-second limit, or after the plan's calls are used up, return `429 Too Many Requests`. Back off before retrying and honour any `Retry-After` header. The provider also applies its own abuse-protection limit of 600 requests per minute per key, which is the same 10 requests per second. Separately from rate limiting, a validate response with `valid: null` may carry a `Retry-After` header that tells you how many seconds to wait before checking that VAT number again. In our tests a fresh VIES lookup with an IBAN took about 1.1 to 2.0 seconds, and the usage and health endpoints answered in under 0.8 seconds.

## FAQ

**What does `valid: null` mean?**

It means the number could not be checked right now, not that it is invalid. This happens when VIES or the member state's database is unavailable and there is no cached result, or for UK `GB` VAT numbers. The `error.code` tells you why (`service_unavailable`, `member_state_unavailable` or `upstream_rate_limited`), and the `Retry-After` header tells you when to try again.

**What happens if VIES is down?**

Successful VAT results are cached for 24 hours. If VIES or a member state is down and the number was checked before, the API returns the last known good result with `stale: true`, the original `checked_at` date and a `warning` explaining the outage. If nothing is cached, you get `valid: null` with an error code and a `Retry-After` header.

**Can I validate UK VAT numbers?**

Northern Ireland numbers with the `XI` prefix are checked through VIES. Great Britain `GB` numbers are not supported yet; the provider lists HMRC checks as coming soon. Until then a `GB` number returns `200` with `valid: null` and `error.code: service_unavailable`.

**Does a valid IBAN mean the bank account exists?**

No. IBAN checks are done offline: the checksum, length and country structure are verified, and the bank name and BIC are looked up from a bundled registry. A `valid: true` IBAN is correctly formed, but the API does not contact the bank to confirm the account is open. `bank` is `null` when the bank code is not in the provider's dataset, which covers 43 countries.

**Do I have to send both `vat` and `iban`?**

No. Send either one or both. The response only includes a block for each value you sent, and a request with neither returns `400`.

**What format should the VAT number be in?**

Include the 2-letter country prefix, for example `DE123456789` or `IE6388047V`. Use `EL` or `GR` for Greece and `XI` for Northern Ireland. Spaces, dots and dashes are stripped, and `vat_number` in the response is the normalized form.

**Why are `limit` and `remaining` null in the usage block?**

Your quota and billing are managed by API.market, not by VatPulse, so the provider does not track a limit for your key. Check your remaining calls in your API.market dashboard.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


EU VAT validation API that checks VAT numbers against VIES and returns company name and address, plus IBAN checksum validation with bank name and BIC.