vatnode

Quick Start Guide

Get started with vatnode in just a few minutes.

1. Create an Account

Sign in or create a free account at vatnode.dev/dashboard. No credit card required.

2. Get Your API Key

Go to Dashboard > API Keys. You'll see two sections:

  • Test Key — created automatically when you signed up. Use it with XX fixture VAT numbers during development.
  • Live Keys — click Create Key, enter a label (e.g. "Production"), and copy the key immediately. It is shown only once.

Live keys look like vat_live_xxxxxxxxxxxx, test keys like vat_test_xxxxxxxxxxxx.

3. Make Your First Request

Use your API key to validate a VAT number:

Using cURL

Terminal
curl https://api.vatnode.dev/v1/vat/IE6388047V \
  -H "Authorization: Bearer vat_live_your_key_here"

Using JavaScript (fetch)

JavaScript
const response = await fetch('https://api.vatnode.dev/v1/vat/IE6388047V', {
  headers: {
    'Authorization': 'Bearer vat_live_your_key_here'
  }
});

const data = await response.json();

if (data.valid) {
  console.log(`Valid VAT: ${data.companyName}`);
} else {
  console.log('Invalid VAT number');
}

Using Python

Python
import requests

response = requests.get(
    'https://api.vatnode.dev/v1/vat/IE6388047V',
    headers={'Authorization': 'Bearer vat_live_your_key_here'}
)

data = response.json()

if data['valid']:
    print(f"Valid VAT: {data['companyName']}")
else:
    print('Invalid VAT number')

Using PHP

PHP
<?php
$ch = curl_init('https://api.vatnode.dev/v1/vat/IE6388047V');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer vat_live_your_key_here'
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

if ($data['valid']) {
    echo "Valid VAT: " . $data['companyName'];
} else {
    echo "Invalid VAT number";
}

Using Go

Go
package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

type VatResponse struct {
    Valid       bool   `json:"valid"`
    CompanyName string `json:"companyName"`
}

func main() {
    req, _ := http.NewRequest("GET", "https://api.vatnode.dev/v1/vat/IE6388047V", nil)
    req.Header.Set("Authorization", "Bearer "+os.Getenv("VATNODE_API_KEY"))

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var data VatResponse
    json.NewDecoder(resp.Body).Decode(&data)

    if data.Valid {
        fmt.Println("Valid VAT:", data.CompanyName)
    } else {
        fmt.Println("Invalid VAT number")
    }
}

Get a Consultation Number (Audit Proof)

A consultation numberis the EU Commission's official receipt that you checked a VAT number against VIES at a specific point in time. Store it with your transaction to prove you performed the validation — the evidence tax authorities expect for reverse-charge and zero-rated cross-border invoices.

Set your VAT once in Dashboard > Account. From then on every validation automatically includes the consultation number — no per-request configuration, no extra parameters. Same call as before:

Terminal
curl https://api.vatnode.dev/v1/vat/IE6388047V \
  -H "Authorization: Bearer vat_live_your_key_here"

Once your VAT is set in dashboard Settings, the response carries the consultation number issued by VIES:

Response
{
  "valid": true,
  "vatId": "IE6388047V",
  "companyName": "GOOGLE IRELAND LIMITED",
  "consultationNumber": "WAPIAAAAWkl0O7mn",
  "verifiedAt": "2026-03-26T14:25:57.209Z",
  "checkId": "019d2a89-a5d9-7b97-b710-57b84604de2b"
}

4. Understanding the Response

A successful validation returns:

Response
{
  "valid": true,
  "vatId": "IE6388047V",
  "countryCode": "IE",
  "countryName": "Ireland",
  "companyName": "GOOGLE IRELAND LIMITED",
  "companyAddress": "3RD FLOOR, GORDON HOUSE, BARROW STREET, DUBLIN 4",
  "companyRegistrationDate": null,
  "companyForm": null,
  "industryDescription": null,
  "registryCode": null,
  "registryCodeName": null,
  "commercialName": null,
  "companyStatus": null,
  "secondaryActivities": [],
  "companyAgeYears": null,
  "consultationNumber": null,
  "verifiedAt": "2026-03-26T14:25:57.209Z",
  "checkId": "019d2a89-a5d9-7b97-b710-57b84604de2b",
  "source": "VIES",
  "specialTerritory": null,
  "countryVat": {
    "vatName": "Value Added Tax",
    "vatAbbr": "VAT",
    "currency": "EUR",
    "standardRate": 23,
    "reducedRates": [13.5, 9],
    "superReducedRate": null,
    "parkingRate": null,
    "vatNumberFormat": "IE + 7 digits + 1–2 letters",
    "vatNumberPattern": "^IE\d{7}[A-W][A-IW]?$|^IE\d[A-Z+*]\d{5}[A-W]$",
    "countryVatUpdatedAt": "2026-03-27"
  }
}
FieldDescription
validWhether the VAT number is valid and active
vatIdThe normalized VAT number
countryCodeTwo-letter EU country code
countryNameFull country name (e.g. "Finland")
companyNameCompany name (may be null for some countries)
companyAddressCompany address (may be null for some countries)
companyRegistrationDateRegistration date from national registry (ISO 8601 date, or null)
companyFormLegal form (e.g. "GmbH", "AB", "SAS"), or null
industryDescriptionBusiness activity description from national registry, or null
registryCodeNational company registry identifier (e.g. Y-tunnus, SIREN, CVR), or null
registryCodeNameName of the registry identifier type (e.g. "Y-tunnus", "SIREN"), or null
commercialNameTrade name where the registry provides one distinct from the legal companyName, or null
companyStatusNormalized operational status (e.g. "active", "ceased"), or null. Enrichment only — it never overrides valid
secondaryActivitiesAdditional activity descriptions from the registry (main activity is industryDescription). Empty array when none
companyAgeYearsFull years since companyRegistrationDate, or null when the date is unknown
checkIdUnique ID for this validation (for audit trails)
consultationNumberVIES consultation number — the EU Commission's proof that this check was performed against VIES. Populated when a requester VAT is configured, otherwise null
verifiedAtISO timestamp of when the check was performed
sourceWhich system produced the result — VIES, CACHE, or a national registry code (e.g. BZST, MF_PL) when VIES was down and vatnode fell back
specialTerritoryEU special-VAT territory inferred from the trader address (e.g. Canary Islands, Åland), or null for mainland traders. Address-inferred, not a tax determination

5. Test VAT Numbers

Use test mode with your vat_test_ key and XX fixture numbers for integration testing. If you want to verify live behaviour with real VIES responses, these known-good VAT numbers work with your live key:

VAT NumberCountryNotes
IE6388047VIrelandReturns full company details
LU20260743LuxembourgReturns full company details
DE134214316GermanyValid, but no name/address returned (DE limitation)

Next Steps