VAT ID Validator - Node.js Client

Official Node.js client for the VAT ID Validator API. Validate EU VAT numbers using the VIES (VAT Information Exchange System) database.

Installation

npm install vat-id-validator

Quick Start

import { VatValidatorClient } from 'vat-id-validator';

// Initialize with API key
const client = new VatValidatorClient({
  apiKey: 'your-rapidapi-key'
});

// Validate a VAT number
const result = await client.validateVat({
  countryCode: 'IT',
  vatNumber: '00743110157'
});

if (result.valid) {
  console.log(`Valid VAT for: ${result.name}`);
  console.log(`Address: ${result.address}`);
} else {
  console.log('Invalid VAT number');
}

Features

✅ TypeScript Support - Full type definitions included
✅ Environment Variables - API key via RAPIDAPI_KEY env var
✅ Configurable Endpoint - Change base URL for testing or custom deployments
✅ Error Handling - Comprehensive error handling with custom error types
✅ Modern ES Modules - Full ESM support

Configuration

Constructor Options

const client = new VatValidatorClient({
  apiKey: 'your-rapidapi-key',        // RapidAPI key (or use RAPIDAPI_KEY env var)
  baseUrl: 'https://custom-url.com',  // Optional: Override API endpoint
  timeout: 15000                      // Optional: Request timeout in ms (default: 10000)
});

Environment Variable

Instead of passing the API key in the constructor, you can set it via environment variable:

export RAPIDAPI_KEY=your-rapidapi-key

// API key will be read from environment
const client = new VatValidatorClient();

Runtime Configuration

You can update the API key or base URL at runtime:

client.setApiKey('new-api-key');
client.setBaseUrl('https://new-endpoint.com');

API Reference

validateVat(request)

Validate a VAT number (basic validation).

Parameters:

• countryCode (string) - 2-letter ISO country code (e.g., 'DE', 'IT', 'FR')
• vatNumber (string) - VAT number without country prefix

Returns: Promise<ValidateVatResponse>

const result = await client.validateVat({
  countryCode: 'DE',
  vatNumber: '169838187'
});

console.log(result);
// {
//   countryCode: 'DE',
//   vatNumber: '169838187',
//   requestDate: '2025-12-30T10:00:00.000Z',
//   valid: true,
//   name: 'Google Germany GmbH',
//   address: 'ABC Street 123, Berlin'
// }

validateVatApprox(request)

Validate a VAT number with approximate matching (advanced validation with trader details).

Parameters:

• countryCode (string) - 2-letter ISO country code
• vatNumber (string) - VAT number without country prefix
• traderName (string, optional) - Company name for matching
• traderStreet (string, optional) - Street address for matching
• traderPostalCode (string, optional) - Postal code for matching
• traderCity (string, optional) - City for matching
• requesterCountryCode (string, optional) - Your company's country code
• requesterVatNumber (string, optional) - Your company's VAT number

Returns: Promise<ValidateVatApproxResponse>

const result = await client.validateVatApprox({
  countryCode: 'DE',
  vatNumber: '169838187',
  traderName: 'Google Germany',
  traderCity: 'Berlin'
});

console.log(result);
// {
//   countryCode: 'DE',
//   vatNumber: '169838187',
//   requestDate: '2025-12-30T10:00:00.000Z',
//   valid: true,
//   traderName: 'Google Germany GmbH',
//   traderStreet: 'ABC Street 123',
//   traderPostalCode: '10115',
//   traderCity: 'Berlin'
// }

health()

Check API health status (no authentication required).

Returns: Promise<HealthResponse>

const health = await client.health();
console.log(health); // { status: 'healthy' }

getConfig()

Get current configuration (API key is masked for security).

Returns: Config object

const config = client.getConfig();
console.log(config);
// {
//   apiKey: '***abc123',
//   baseUrl: 'https://vies-vat-validator.p.rapidapi.com',
//   timeout: 10000
// }

Error Handling

The client throws VatValidatorError for API errors:

import { VatValidatorError } from 'vat-id-validator';

try {
  const result = await client.validateVat({
    countryCode: 'DE',
    vatNumber: '123456789'
  });
} catch (error) {
  if (error instanceof VatValidatorError) {
    console.error('Status:', error.statusCode);
    console.error('Message:', error.message);
    console.error('Response:', error.response);
  }
}

Common Errors

• 401 Unauthorized - Invalid or missing API key
• 500 Internal Server Error - VIES service error or network issue
• Network Error - Connection timeout or no response from server

TypeScript

Full TypeScript support with comprehensive type definitions:

import {
  VatValidatorClient,
  ValidateVatRequest,
  ValidateVatResponse,
  VatValidatorError
} from 'vat-id-validator';

const request: ValidateVatRequest = {
  countryCode: 'IT',
  vatNumber: '00743110157'
};

const response: ValidateVatResponse = await client.validateVat(request);

Examples

Basic Usage

import { VatValidatorClient } from 'vat-id-validator';

const client = new VatValidatorClient({
  apiKey: process.env.RAPIDAPI_KEY
});

// Validate Italian VAT
const result = await client.validateVat({
  countryCode: 'IT',
  vatNumber: '00743110157'
});

console.log(`Valid: ${result.valid}`);
console.log(`Company: ${result.name}`);

With Trader Details

// Validate with approximate matching
const result = await client.validateVatApprox({
  countryCode: 'DE',
  vatNumber: '169838187',
  traderName: 'Google Germany GmbH',
  traderCity: 'Berlin',
  requesterCountryCode: 'IT',
  requesterVatNumber: '00743110157'
});

Batch Validation

const vatNumbers = [
  { countryCode: 'IT', vatNumber: '00743110157' },
  { countryCode: 'DE', vatNumber: '169838187' },
  { countryCode: 'FR', vatNumber: '123456789' }
];

const results = await Promise.all(
  vatNumbers.map(vat => client.validateVat(vat))
);

results.forEach((result, index) => {
  console.log(`${vatNumbers[index].countryCode}${vatNumbers[index].vatNumber}: ${result.valid ? '✓' : '✗'}`);
});

Custom Endpoint for Testing

// Use a custom endpoint (e.g., for local testing)
const client = new VatValidatorClient({
  apiKey: 'test-key',
  baseUrl: 'http://localhost:8787'
});

Supported Countries

All EU member states are supported:

• AT (Austria), BE (Belgium), BG (Bulgaria), CY (Cyprus)
• CZ (Czech Republic), DE (Germany), DK (Denmark), EE (Estonia)
• ES (Spain), FI (Finland), FR (France), GR (Greece)
• HR (Croatia), HU (Hungary), IE (Ireland), IT (Italy)
• LT (Lithuania), LU (Luxembourg), LV (Latvia), MT (Malta)
• NL (Netherlands), PL (Poland), PT (Portugal), RO (Romania)
• SE (Sweden), SI (Slovenia), SK (Slovakia)

License

MIT

Support

• API Documentation: Full API Docs
• Issues: GitHub Issues
• RapidAPI: Get your API key at RapidAPI