|Documentation
Sign Up

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/login. No credit card required.

2. Get Your API Key

After signing in, go to your Dashboard and create a new API key.

  • Click "Create Key"
  • Give it a descriptive label (e.g., "Production API Key")
  • Choose the environment (live or test)
  • Copy the key immediately - you won't be able to see it again!

Your API key will look like: vat_live_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")
    }
}

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",
  "checkedAt": "2026-03-26T14:25:57.209Z",
  "source": "VIES",
  "checkId": "019d2a89-a5d9-7b97-b710-57b84604de2b",
  "countryVat": {
    "vatName": "Value Added Tax",
    "vatAbbr": "VAT",
    "currency": "EUR",
    "standardRate": 23,
    "reducedRates": [13.5, 9],
    "superReducedRate": null,
    "parkingRate": null,
    "ratesUpdatedAt": "2026-03-27"
  },
  "cache": {
    "hit": false,
    "ttlSeconds": 900
  }
}
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)
checkIdUnique ID for this validation (for audit trails)
checkedAtISO timestamp of when the check was performed
sourceData source (always "VIES")
cache.hitWhether this response came from cache
cache.ttlSecondsHow long until the cache expires

5. Test VAT Numbers

Use these real VAT numbers for testing:

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

Next Steps