Skip to main content

​
Overview

Topograph automatically validates VAT numbers for EU companies via the EU VIES (VAT Information Exchange System) service. This validation provides legally admissible proof of VAT verification for audit purposes.

​
How It Works

When you request a company profile for supported EU countries, Topograph:
  1. Calculates the VAT number from the company’s registration number (e.g., SIREN in France, NIF in Spain)
  2. Performs a qualified VIES check using Topograph’s own VAT number as the requester
  3. Returns verification details including the consultation number (legal proof)

​
Response Structure

The taxId field is included in company profile responses: 
{
  "company": {
    "id": "932884117",
    "countryCode": "FR",
    "identifiers": {
      "siren": "932884117",
      "VAT": "21932884117"
    },
    "taxId": {
      "type": "eu_vat",
      "value": "21932884117",
      "country": "FR",
      "verification": {
        "status": "verified",
        "verifiedAt": "2026-02-04T15:30:00.000Z",
        "verifiedName": "TOPOGRAPH SAS",
        "verifiedAddress": "1 RUE EXAMPLE 75001 PARIS",
        "consultationNumber": "WAPIAAAAW1234567890"
      }
    }
  }
}

​
Fields

FieldDescription
typeTax ID type. Currently eu_vat for EU VAT numbers
valueVAT number without country prefix (e.g., 21932884117 not FR21932884117)
countryISO 3166-1 alpha-2 country code (e.g., FR, ES)
verification.statusVerification status: verified, unverified, or unavailable
verification.verifiedAtISO 8601 timestamp of when the verification was performed
verification.verifiedNameCompany name as registered with VIES
verification.verifiedAddressCompany address as registered with VIES
verification.consultationNumberThe legal proof - unique identifier from VIES for audit purposes

​
Verification Statuses

StatusMeaning
verifiedVAT number is valid and registered with VIES. The company can perform EU cross-border transactions.
unverifiedVAT number format is valid but not registered with VIES. The company may not be registered for EU trade.
unavailableUnable to verify (VIES service unavailable, invalid format, etc.)

​
The Consultation Number

The consultationNumber is the critical piece for legal compliance. This is the official receipt from the EU VIES system that proves you validated the VAT number at a specific point in time.
Store the consultationNumber along with the verifiedAt timestamp in your records. This is the legally admissible proof that you performed due diligence when validating a customer’s VAT number.

​
Supported Countries

VAT validation is currently available for:
CountryNotes
🇫🇷 FranceVAT calculated from SIREN using the official formula
🇪🇸 SpainVAT value equals NIF. Note: Requires ROI registration for EU trade
More EU countries will be added in future updates.

​
Country-Specific Notes

​
France

The French VAT number (TVA Intracommunautaire) is calculated mathematically from the SIREN: 
Key = (12 + 3 × (SIREN mod 97)) mod 97
VAT = Key (2 digits) + SIREN (9 digits)
Example: SIREN 932884117 → VAT 21932884117

​
Spain

In Spain, the VAT number equals the NIF (Número de Identificación Fiscal):
  • NIF: A82511361
  • VAT: A82511361 (same value)
Having a Spanish NIF does not guarantee the company is VAT-registered for EU trade. Companies must be enrolled in the ROI (Registro de Operadores Intracomunitarios) to perform intra-community transactions. VIES will return unverified for companies not in ROI.

​
Searching by VAT Number

You can search for companies using their VAT number (with or without the country prefix): 
# With prefix
curl -X POST https://api.topograph.com/search \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"countryCode": "FR", "query": "FR21932884117"}'

# Without prefix (11 digits for France)
curl -X POST https://api.topograph.com/search \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"countryCode": "FR", "query": "21932884117"}'
The search will automatically extract the underlying company identifier (SIREN/NIF) and return the matching company.

​
Best Practices

  1. Always store the consultation number - This is your legal proof of verification
  2. Re-validate periodically - VAT registrations can change; consider re-validating before significant transactions
  3. Handle unverified gracefully - Not all companies are VAT-registered, especially in Spain where ROI enrollment is separate
  4. Use the identifiers.VAT field - This is always present and contains the calculated VAT value without prefix