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

# VAT Validation

> Verify EU VAT numbers and obtain legal proof for audits

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

```json theme={null}
{
  "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

| Field                             | Description                                                                     |
| --------------------------------- | ------------------------------------------------------------------------------- |
| `type`                            | Tax ID type. Currently `eu_vat` for EU VAT numbers                              |
| `value`                           | VAT number **without** country prefix (e.g., `21932884117` not `FR21932884117`) |
| `country`                         | ISO 3166-1 alpha-2 country code (e.g., `FR`, `ES`)                              |
| `verification.status`             | Verification status: `verified`, `unverified`, or `unavailable`                 |
| `verification.verifiedAt`         | ISO 8601 timestamp of when the verification was performed                       |
| `verification.verifiedName`       | Company name as registered with VIES                                            |
| `verification.verifiedAddress`    | Company address as registered with VIES                                         |
| `verification.consultationNumber` | **The legal proof** - unique identifier from VIES for audit purposes            |

## Verification Statuses

| Status        | Meaning                                                                                                  |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| `verified`    | VAT number is valid and registered with VIES. The company can perform EU cross-border transactions.      |
| `unverified`  | VAT number format is valid but not registered with VIES. The company may not be registered for EU trade. |
| `unavailable` | Unable 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.

<Note>
  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.
</Note>

## Supported Countries

### Full taxId Support (VAT in profile + VIES verification)

| Country         | VAT Format       | Notes                                                  |
| --------------- | ---------------- | ------------------------------------------------------ |
| 🇫🇷 France     | FR + 11 digits   | VAT calculated from SIREN using official formula       |
| 🇪🇸 Spain      | ES + NIF         | VAT equals NIF. Requires ROI registration for EU trade |
| 🇸🇪 Sweden     | SE + 12 digits   | Organisationsnummer + "01" suffix                      |
| 🇮🇹 Italy      | IT + 11 digits   | Partita IVA from Infocamere                            |
| 🇵🇹 Portugal   | PT + 9 digits    | NIF (Número de Identificação Fiscal)                   |
| 🇵🇱 Poland     | PL + 10 digits   | NIP (Numer Identyfikacji Podatkowej)                   |
| 🇪🇪 Estonia    | EE + 9 digits    | VAT from registry API                                  |
| 🇦🇹 Austria    | ATU + 8 digits   | VAT via VIES reverse lookup                            |
| 🇧🇪 Belgium    | BE + 10 digits   | Enterprise Number (KBO/BCE)                            |
| 🇱🇺 Luxembourg | LU + 8 digits    | VAT via VIES reverse lookup                            |
| 🇩🇰 Denmark    | DK + 8 digits    | CVR number                                             |
| 🇨🇿 Czechia    | CZ + 8-10 digits | IČO for companies                                      |
| 🇷🇴 Romania    | RO + 2-10 digits | CUI (Cod Unic de Înregistrare)                         |
| 🇭🇺 Hungary    | HU + 8 digits    | First 8 digits of tax number                           |
| 🇫🇮 Finland    | FI + 8 digits    | Business ID without hyphen                             |
| 🇭🇷 Croatia    | HR + 11 digits   | OIB (Osobni Identifikacijski Broj)                     |

### VAT Search Only (VIES reverse lookup)

For these countries, you can search by VAT number, but the `taxId` field won't appear in company profiles because the VAT is neither algorithmically derivable from the registration number nor available in the registry API.

| Country      | VAT Format               | Notes                                |
| ------------ | ------------------------ | ------------------------------------ |
| 🇱🇻 Latvia  | LV + 11 digits           | Search via VIES, no taxId in profile |
| 🇨🇾 Cyprus  | CY + 8 digits + 1 letter | Search via VIES, no taxId in profile |
| 🇮🇪 Ireland | IE + 7-9 characters      | Search via VIES, no taxId in profile |
| 🇲🇹 Malta   | MT + 8 digits            | Search via VIES, no taxId in profile |

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

<Warning>
  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.
</Warning>

### Sweden

Swedish VAT is derived from the Organisationsnummer with a "01" suffix:

* Organisationsnummer: `5560360793`
* VAT: `556036079301`

### Belgium

Belgian VAT equals the Enterprise Number (KBO/BCE number):

* Enterprise Number: `0644911041`
* VAT: `0644911041`

### Countries with VIES Reverse Lookup Only

For Latvia, Cyprus, Ireland, and Malta, the VAT number cannot be derived from the registration number and is not available in the registry API. However, you can still:

1. **Search by VAT** - Enter a VAT number to find the company via VIES reverse lookup
2. **Verify VAT** - The search returns the company name from VIES, which is then matched to the local registry

<Note>
  VIES reverse lookup searches by VAT number and returns the company name, which is then used to search the local registry. This may return multiple results if the company name is common.
</Note>

## Searching by VAT Number

You can search for companies using their VAT number (with or without the country prefix):

```bash theme={null}
# With prefix
curl -G https://api.topograph.co/v2/search \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "country=FR" \
  --data-urlencode "query=FR21932884117"

# Without prefix (11 digits for France)
curl -G https://api.topograph.co/v2/search \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "country=FR" \
  --data-urlencode "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