> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bunny.build/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /vat-validator

> Validate EU VAT numbers and retrieve registered business name and address.

## Endpoint

```
POST https://api.bunny.build/api/v1/vat-validator
```

## Authentication

| Header         | Required | Value                    |
| -------------- | -------- | ------------------------ |
| `X-API-Key`    | Yes      | Your API key (`bun_...`) |
| `Content-Type` | Yes      | `application/json`       |

## Overview

Validate European Union VAT numbers against the official VIES (VAT Information Exchange System) database and retrieve the registered business name and address. Use this API to automate B2B tax compliance checks and keep your invoicing data accurate.

## Use cases

* Verify customer VAT numbers during B2B checkout
* Auto-fill company name and address from a VAT number
* Gate zero-rate tax treatment on confirmed valid VAT IDs
* Detect fraudulent or expired VAT numbers

## Details

Covers all EU member states. The `vat` field should include the two-letter country prefix (e.g. `DE123456789`, `FR12345678901`). Validation queries the live VIES service; occasional timeouts from the VIES system are propagated as errors.

## Request body

| Field     | Type   | Required | Description                                                                                  |
| --------- | ------ | -------- | -------------------------------------------------------------------------------------------- |
| `vat`     | string | Yes      | VAT number, with or without the two-letter country prefix (e.g. `DE123456789`)               |
| `country` | string | No       | Two-letter EU country code (e.g. `DE`). Required only when `vat` does not include the prefix |

### Example

```json theme={null}
{
  "vat": "DE123456789"
}
```

## Response

### 200 OK

| Field          | Type         | Description                                                   |
| -------------- | ------------ | ------------------------------------------------------------- |
| `country_code` | string       | Two-letter EU country code                                    |
| `vat_number`   | string       | VAT number with the country prefix stripped                   |
| `valid`        | boolean      | Whether the VAT number is registered and active               |
| `name`         | string\|null | Registered business name (`null` if not disclosed by VIES)    |
| `address`      | string\|null | Registered business address (`null` if not disclosed by VIES) |
| `request_date` | string\|null | Date the VIES lookup was performed                            |

**Example**

```json theme={null}
{
  "country_code": "DE",
  "vat_number": "123456789",
  "valid": true,
  "name": "Example GmbH",
  "address": "Musterstraße 1, 10115 Berlin",
  "request_date": "2024-01-15+01:00"
}
```

### 401 Unauthorized

```json theme={null}
{
  "detail": "Missing API key. Include X-API-Key header."
}
```

### 402 Payment Required

```json theme={null}
{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}
```

### 422 Unprocessable Entity

```json theme={null}
{
  "detail": "Invalid VAT number format"
}
```

### 429 Too Many Requests

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}
```

## cURL example

```bash theme={null}
curl -X POST https://api.bunny.build/api/v1/vat-validator \
  -H "X-API-Key: bun_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"vat": "DE123456789"}'
```