Name: EU VAT Validator API - Official VIES Check for 27+ Countries
Brand: viv-data
SKU: api-viv-data-vat-validator
Availability: InStock
Author: API Market

gia ly bui

# EU VAT Validator — Official VIES, 27 Countries

## Overview
The EU VAT Validator API provides a robust solution for validating European VAT numbers through the official EU VIES (VAT Information Exchange System). This API allows you to quickly check if a given VAT number is valid, and if so, retrieve the registered company name and address associated with it. This service is crucial for businesses engaged in B2B e-commerce, ensuring compliance with tax regulations, and verifying customer details.

## Features
*   **Official VIES Validation:** Utilizes the authoritative EU VAT Information Exchange System for accurate validation.
*   **Comprehensive Country Coverage:** Supports all 27 European Union member states plus the United Kingdom.
*   **Detailed VAT Information:** Returns validity status, country code, country name, company name, and company address.
*   **Real-time Checks:** Provides up-to-date validation results from the official source.
*   **Data Caching:** Results are cached for 24 hours to optimize performance and reduce redundant external calls.
*   **Simple Integration:** Easy-to-use API with clear, concise responses.

## Use Cases
*   **B2B E-commerce & Invoicing Compliance:** Automatically validate VAT numbers during checkout or invoice generation to ensure correct taxation, prevent fraud, and comply with EU VAT regulations for intra-community supply of goods and services.
*   **Customer Onboarding & KYC:** Verify the legitimacy of business customers during the onboarding process, enhancing Know Your Customer (KYC) procedures and maintaining accurate customer databases.
*   **Financial Auditing & Tax Reporting:** Streamline internal auditing processes by quickly cross-referencing VAT numbers against official records, simplifying tax reporting and reducing manual data entry errors.
*   **CRM & ERP System Integration:** Integrate the validator into Customer Relationship Management (CRM) or Enterprise Resource Planning (ERP) systems to automatically update and maintain verified business partner data.
*   **Supplier Validation & Procurement:** Validate VAT numbers of potential and existing suppliers to ensure they are registered businesses, reducing risk in procurement and supply chain operations.


## Pricing
1 API unit equals 1 VAT validation request made to the `/validate` endpoint. All other GET requests (e.g., `/health`, `/countries`) are free and do not count toward API unit usage. Different pricing tiers are available based on usage volume:
*   **Free:** 500 requests/month
*   **Pro $19.99:** 5,000 requests/month

## API Documentation

### Base URL
All API requests should be made to:
`https://prod.api.market/api/v1/viv-data/vat-validator`

### Authentication
Authentication is handled via API key. Include your API key in the request header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```
### Endpoints

#### 1. Validate VAT Number
Validate a European VAT number and retrieve associated company details.

*   **Endpoint:** `GET /api/v1/viv-data/vat-validator/validate`
*   **Summary:** Validate
*   **Operation ID:** `validate_validate_get`

**Parameters:**
*   `vat` (query parameter, required, string): Full VAT number, e.g., `DE814584193`

**Example Request:**
```bash
curl -X GET "https://prod.api.market/api/v1/viv-data/vat-validator/validate?vat=DE814584193" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response (200 OK):**
```json
{
  "vat_number": "DE814584193",
  "country_code": "DE",
  "country_name": "Germany",
  "valid": true,
  "company_name": "SAP SE",
  "company_address": "Walldorf",
  "request_date": "2023-10-27T10:00:00Z",
  "error": ""
}
```

**Example Response (Invalid VAT, 200 OK):**
```json
{
  "vat_number": "DE123456789",
  "country_code": "DE",
  "country_name": "Germany",
  "valid": false,
  "company_name": null,
  "company_address": null,
  "request_date": "2023-10-27T10:00:00Z",
  "error": ""
}
```

#### 2. Health Check
Check the health status of the API.

*   **Endpoint:** `GET /api/v1/viv-data/vat-validator/health`
*   **Summary:** Health
*   **Operation ID:** `health_health_head`

**Example Request:**
```bash
curl -X GET "https://prod.api.market/api/v1/viv-data/vat-validator/health" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response (200 OK):**
```json
{}
```

#### 3. Root Endpoint
A basic root endpoint, often used for general service information.

*   **Endpoint:** `GET /api/v1/viv-data/vat-validator/`
*   **Summary:** Root
*   **Operation ID:** `root__get`

**Example Request:**
```bash
curl -X GET "https://prod.api.market/api/v1/viv-data/vat-validator/" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response (200 OK):**
```json
{
  "message": "Welcome to the EU VAT Validator API!"
}
```
*(Note: The schema for this endpoint is empty, assuming a common simple response)*

#### 4. List Countries
Lists the countries supported by the VAT validation service.

*   **Endpoint:** `GET /api/v1/viv-data/vat-validator/countries`
*   **Summary:** List Countries
*   **Operation ID:** `list_countries_countries_get`

**Example Request:**
```bash
curl -X GET "https://prod.api.market/api/v1/viv-data/vat-validator/countries" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response (200 OK):**
```json
{
  "supported_countries": [
    "AT", "BE", "BG", "CY", "CZ", "DE", "DK", "EE", "EL", "ES", "FI", "FR",
    "HR", "HU", "IE", "IT", "LT", "LU", "LV", "MT", "NL", "PL", "PT", "RO",
    "SE", "SI", "SK", "UK"
  ]
}
```
*(Note: The schema for this endpoint is empty, assuming a common response format for country lists)*

## Status Codes
*   **200 OK:** Request successful. The API processed the request as expected and returned the requested data or confirmation.
*   **201 Created:** Resource successfully created. (Less common for this synchronous GET-based API, but may appear for other types of operations).
*   **400 Bad Request:** Invalid input parameters or malformed request. Check your request body, query parameters, or headers for errors.
*   **401 Unauthorized:** Missing or invalid API key. Ensure you are sending a valid `x-api-market-key` header with your request.
*   **403 Forbidden:** Valid API key but insufficient permissions. Your API key might not have the necessary access rights for the requested operation or your rate limit might be exceeded (refer to `429`).
*   **404 Not Found:** The requested resource was not found. Double-check the endpoint URL for typos.
*   **422 Unprocessable Entity:** Validation Error. The server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions. Often returned for invalid query parameters like a malformed VAT number.
*   **429 Too Many Requests:** Rate limit exceeded. You have sent too many requests in a given amount of time. Implement exponential backoff for retries.
*   **500 Internal Server Error:** A server-side error occurred. This indicates an unexpected issue on the API's side. If this persists, please contact support.
*   **503 Service Unavailable:** The service is temporarily unavailable, often due to maintenance or high load. Retry the request after a short delay.

## Rate Limits
The API has rate limits to ensure fair usage and system stability. If you exceed your allocated request limit within a given timeframe, you will receive a `429 Too Many Requests` status code. It is recommended to implement retry logic with exponential backoff when encountering this error. Refer to the pricing section for details on available request volumes per tier.

## Error Handling
Effective error handling is crucial for building resilient applications. When the API encounters an issue, it will return an appropriate HTTP status code along with a JSON response detailing the error.

**How to Interpret Error Responses:**
1.  **Check HTTP Status Code:** This is the primary indicator of the error type (e.g., 400 for bad input, 401 for authentication, 500 for server errors).
2.  **Parse JSON Response:** The response body will contain a JSON object providing more specific details about the error.

**Common Errors and How to Resolve Them:**
*   **401 Unauthorized:** Ensure your `x-api-market-key` header is present and contains a valid API key.
*   **400 Bad Request / 422 Unprocessable Entity:** Review the documentation for the specific endpoint you are calling. Check that all required query parameters are present and correctly formatted (e.g., the `vat` parameter for `/validate`).
*   **429 Too Many Requests:** You've hit your rate limit. Wait for the rate limit window to reset or upgrade your plan if you require higher throughput. Implement retry logic.
*   **5xx Server Errors:** These indicate issues on the API server's side. While rare, if you encounter them, retry the request after a short delay. If the problem persists, please contact support.

**Recommended Retry Strategies:**
For transient errors (like `429 Too Many Requests` or `503 Service Unavailable`), implement an exponential backoff strategy:
1.  Wait a short initial period (e.g., 1 second).
2.  If the error persists, double the wait time for the next retry.
3.  Continue retrying a fixed number of times (e.g., 3-5 times) or until a maximum wait time is reached.
4.  Avoid immediate retries as this can exacerbate the issue.

**Error Response Example (400 Bad Request):**
```json
{
  "error": {
    "code": "validation_error",
    "message": "The 'vat' parameter is required for validation.",
    "status": 400
  }
}
```

**Error Response Example (422 Unprocessable Entity, from schema):**
```json
{
  "detail": [
    {
      "loc": [
        "query",
        "vat"
      ],
      "msg": "value is not a valid VAT number format",
      "type": "value_error"
    }
  ]
}
```

## Implementation Guide

### Example Code
These examples demonstrate how to authenticate and make synchronous API requests to the EU VAT Validator API.

```javascript
// JavaScript example (Synchronous)
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/viv-data/vat-validator";

async function validateVatNumber(vatNumber) {
  try {
    const response = await fetch(`${baseUrl}/validate?vat=${vatNumber}`, {
      method: "GET",
      headers: {
        "x-api-market-key": apiKey,
        "Content-Type": "application/json"
      }
    });
    
    const data = await response.json();

    if (!response.ok) {
      console.error(`API Error: ${response.status} - ${JSON.stringify(data)}`);
      throw new Error(`Failed to validate VAT number: ${data.detail || data.error?.message || 'Unknown error'}`);
    }
    
    return data; // Returns the VATResult object
  } catch (error) {
    console.error("Error during VAT validation:", error);
    throw error;
  }
}

// Example usage:
validateVatNumber("DE814584193")
  .then(result => console.log("Validation Result:", result))
  .catch(error => console.error("Caught error:", error));

validateVatNumber("GB123456789") // Example with UK VAT
  .then(result => console.log("Validation Result (UK):", result))
  .catch(error => console.error("Caught error:", error));

validateVatNumber("ESN1234567A") // Example for Spain (starts with letter)
  .then(result => console.log("Validation Result (ES):", result))
  .catch(error => console.error("Caught error:", error));

validateVatNumber("XX123456789") // Example of invalid format
  .then(result => console.log("Validation Result (Invalid Format):", result))
  .catch(error => console.error("Caught error (Invalid Format):", error));
```

```python
# Python example (Synchronous)
import requests
import json

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/viv-data/vat-validator"

def validate_vat_number(vat_number):
    headers = {
        "x-api-market-key": API_KEY,
        "Content-Type": "application/json"
    }
    
    try:
        response = requests.get(
            f"{BASE_URL}/validate?vat={vat_number}",
            headers=headers
        )
        response.raise_for_status()  # Raise an exception for HTTP errors (4xx or 5xx)
        
        return response.json()
    
    except requests.exceptions.HTTPError as http_err:
        print(f"HTTP error occurred: {http_err}")
        print(f"Response content: {response.text}")
        raise
    except requests.exceptions.ConnectionError as conn_err:
        print(f"Connection error occurred: {conn_err}")
        raise
    except requests.exceptions.Timeout as timeout_err:
        print(f"Timeout error occurred: {timeout_err}")
        raise
    except requests.exceptions.RequestException as req_err:
        print(f"An unexpected error occurred: {req_err}")
        raise

# Example usage:
try:
    result = validate_vat_number("DE814584193")
    print("Validation Result:", json.dumps(result, indent=2))

    result_uk = validate_vat_number("GB123456789")
    print("Validation Result (UK):", json.dumps(result_uk, indent=2))

    result_es = validate_vat_number("ESN1234567A")
    print("Validation Result (ES):", json.dumps(result_es, indent=2))
    
    # Example of a known invalid VAT to demonstrate 'valid: false'
    result_invalid = validate_vat_number("DE999999999") 
    print("Validation Result (Invalid VAT):", json.dumps(result_invalid, indent=2))

except Exception as e:
    print("Caught error during validation:", e)
```

```bash
# cURL example (Synchronous)

# Example 1: Validate a valid German VAT number
curl -X GET "https://prod.api.market/api/v1/viv-data/vat-validator/validate?vat=DE814584193" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"

# Example 2: Validate a valid UK VAT number
curl -X GET "https://prod.api.market/api/v1/viv-data/vat-validator/validate?vat=GB123456789" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"

# Example 3: Validate a VAT number that is formally correct but invalid in VIES
curl -X GET "https://prod.api.market/api/v1/viv-data/vat-validator/validate?vat=DE999999999" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"

# Example 4: Check API health
curl -X GET "https://prod.api.market/api/v1/viv-data/vat-validator/health" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"

# Example 5: List supported countries
curl -X GET "https://prod.api.market/api/v1/viv-data/vat-validator/countries" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

### Performance Optimization
To ensure optimal performance and minimize costs when using the EU VAT Validator API:
*   **Client-Side Caching:** Since the API itself caches VIES results for 24 hours, if your application frequently validates the same VAT numbers, consider implementing a client-side cache with a similar or shorter expiry. This can reduce redundant API calls and improve response times for your users.
*   **Batch Processing (where applicable):** While this API processes one VAT number per request, if your application needs to validate a large list of VATs, consider processing them in batches. This means making multiple individual requests in parallel rather than sequentially, respecting your rate limits.
*   **Error Handling and Retries:** Implement robust error handling with exponential backoff for transient errors (e.g., `429 Too Many Requests`, `503 Service Unavailable`). This prevents your application from hammering the API during temporary disruptions and ensures successful processing when the service recovers.
*   **Asynchronous Request Handling:** In your application, make API calls asynchronously to avoid blocking the main thread, especially if you're making multiple requests.

## FAQ
**Q: What is the EU VIES system?**

A: VIES (VAT Information Exchange System) is an electronic means of validating VAT identification numbers of economic operators registered in the European Union for cross-border transactions of goods or services. It's maintained by the European Commission.


**Q: Which countries are supported by this API?**

A: The API supports all 27 EU member states plus the United Kingdom.

**Q: How accurate are the validation results?**

A: The API retrieves data directly from the official EU VIES system, ensuring the highest level of accuracy for VAT number validation.

**Q: Is there a limit to how many requests I can make?**

A: Yes, rate limits apply based on your subscription tier. Please refer to the Pricing section for details. Exceeding these limits will result in a `429 Too Many Requests` error.

**Q: What happens if a VAT number is valid but no company name/address is returned?**

A: While rare, this can sometimes occur if the official VIES system for a specific country does not publicly provide company details, or if there's a temporary data retrieval issue. The `valid` field will still accurately reflect the VAT number's status.

**Q: Does the API store any of my data?**

A: The API processes your requests to retrieve public VAT information. While results are cached for 24 hours to optimize performance, no personal or sensitive data from your requests is permanently stored or associated with your account beyond standard logging for operational purposes.

## 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.

Validate European VAT numbers instantly using the official EU VIES system. Retrieve company name and address for B2B e-commerce and tax compliance across all 27

EU VAT Validator API - Official VIES Check for 27+ Countries

Free

Viv Data

Instantly validate European VAT numbers and retrieve official company details for all 27 EU member states plus UK, ensuring compliance with rapid, reliable VIES