Export Your VAT Check History as a CSV for an Audit

You can download your whole vatnode check history as one CSV from the dashboard: Usage, then Check History, then Download CSV. Each row is one check with the VAT number, the answer, where it came from, a UTC timestamp and, for live VIES answers with your own VAT number set, the consultation number. The export comes with every plan, the free plan included.

What an auditor wants from your VAT checks

For a zero-rated or reverse-charged B2B invoice, the question is whether the customer’s VAT number was valid when you supplied the goods or services, and whether you can show it. Auditors generally prefer to see a check made at or around the time of supply or invoicing – that is practitioner expectation, not a statutory rule. A dated record per check is what answers that question. The wider picture is in what auditors look for in VAT documentation and in the guide to the VIES consultation number audit trail.

The consultation number is the reference VIES issues for a requester-qualified check. It has its own write-ups for finance teams and developers, so it only gets a column here.

How to download your check history

1. Sign in and open Usage in the dashboard.
2. Scroll to the Check History section.
3. Press Download CSV. The button is disabled while you have no checks.

You get one file, the whole history, newest first. There are no filters, no date range and no pagination. The filename is vatnode-checks-YYYY-MM-DD.csv, with the date of the download. The export needs a signed-in dashboard session; an API key does not work for it.

What the 11 columns mean

Three rows, newest first as in the real file, with invented companies and numbers that fail the checksum. The bottom row is from before the account had a requester VAT number set, which is why it could be served from cache:

"checkId","vatId","countryCode","valid","companyName","source","errorCode","cacheHit","createdAt","keyLabel","consultationNumber"
"0192f3b0-5d12-7e44-b6c1-93a0d7e5f814","NL857301442B01","NL","","","VIES","VIES_UNAVAILABLE","false","2026-10-14T11:02:19.907Z","billing-prod",""
"0192f3a1-7c4e-7b21-9d3a-5e8f1a2b3c4d","DE284716395","DE","true","Mustermann Handels GmbH","VIES","","false","2026-10-14T09:12:44.381Z","billing-prod","WAPIAAAAZ1Q9Q7K2"
"01923a4c-1b9a-7c05-8a77-2d4e6f708192","DE284716395","DE","true","Mustermann Handels GmbH","CACHE","","true","2026-09-28T14:20:03.120Z","billing-prod",""

Every field is double-quoted, the encoding is UTF-8 and lines end in CRLF. Values starting with =, +, -, @, a tab or a carriage return get an apostrophe in front so a spreadsheet does not run them as formulas; company names come from external data. The apostrophe is part of the stored value, so strip a leading ' before comparing company names in a script.

What is and isn’t in the file

• Live checks only. Test-key checks write nothing, so they never appear. Bulk validation checks appear too, one row each.
• Failed calls appear. valid is empty, errorCode is set and source is VIES. Their checkId never appeared in an API response, because error responses carry none. Without a requester VAT number set, a repeat of a transient VIES failure within about a minute is answered from a short failure cache, with cacheHit set to true and no new VIES call.
• One request can produce two rows. If VIES fails and, with no requester VAT number set, a national registry answers instead, you get a VIES row with an errorCode and an empty valid, plus an answer row with the registry as source.
• createdAt is vatnode’s timestamp for your request. On a CACHE row it is when your call was answered from cache; the cached answer behind it can be up to 15 minutes older.
• Revoked keys stay. Checks run with a key you later revoked are still in the export.

Only a row with a consultationNumber is tied to a VIES consultation. A row with a national-registry source, an errorCode or an empty consultationNumber is not a VIES confirmation, and a registry’s valid should not be presented as one. checkId is vatnode’s own ID, not an EU reference, and the CSV is vatnode’s record, not an official EU document.

Making sure valid rows carry a consultation number

Set your own VAT number once under Account details. From then on every single check, and every bulk job you submit after that, is requester-qualified: the cache is skipped, the national fallback is not used, and a valid answer that comes back without a consultation number is withheld rather than returned, so it does not count against your quota. Valid rows after that point carry a number. Checks run before you set it do not, and the export will not add one afterwards. A bulk job keeps the requester setting it was submitted with. Invalid rows are not promised a number.

No EU rule says a VIES record is the required proof, but you do have to be able to show your customer’s status, and what evidence your tax authority expects depends on your member state. A dated record of each check is common practice.

Finding the rows for one invoice

In a spreadsheet, open the CSV, filter vatId to the customer’s number, then sort or filter createdAt around the invoice date. Look at source and consultationNumber on the rows that remain. The file is UTF-8 without a byte-order mark; if accented company names look garbled after a double-click, import it instead (in Excel, Data > From Text/CSV) and pick UTF-8.

If you prefer a script, this Python standard-library snippet prints the timestamp, checkId and consultation number of every row for one VAT number that has a consultation number:

import csv, sys

with open(sys.argv[1], newline="", encoding="utf-8") as f:
    for row in csv.DictReader(f):
        if row["vatId"] == sys.argv[2] and row["consultationNumber"]:
            print(row["createdAt"], row["checkId"], row["consultationNumber"])

Run against the sample above with DE284716395, it prints 2026-10-14T09:12:44.381Z 0192f3a1-7c4e-7b21-9d3a-5e8f1a2b3c4d WAPIAAAAZ1Q9Q7K2.

For automated billing, also store checkId and consultationNumber from each /v1/vat response next to the invoice at call time – see the VAT validation reference. The dashboard export then works as the full cross-check.

Keep your own copy

vatnode anonymises each check 5 years after it was run: the VAT number, company name and consultation number are removed, and the row no longer appears in your export. If you delete your account, you lose dashboard access straight away, and the account purge that follows (30 days later by default) de-links your check records and clears their consultation numbers. They then no longer appear in any export of yours, so download the file before you close the account.

Your own obligation is a different question. The VAT Directive (2006/112/EC, Article 247(1)) leaves the storage period for invoices to each member state, and national bookkeeping rules cover the evidence behind them; there is no single EU-wide period. Periods can differ by record type and can be extended while an assessment is still open. Check yours with your adviser. If it may run past 5 years from the check, or you might close the account, archive the CSV in your own storage – after each period close or quarterly, say.

A VAT number can be personal data. A sole trader’s number identifies a person, in some member states it is built on a personal ID number, and companyName can be their own name. Once you download the CSV, you are the controller of that archive, so keep it behind access control and on the retention you set for other personal data – more in VAT data and GDPR.

This is general information, not tax or legal advice.

Your history starts with the first live check – test keys write none. Create a free account, set your own VAT number under Account details, then run a live check: every valid row from then on carries a consultation number. The free plan covers 100 checks a month; see pricing.

FAQ

How do I export my VAT validation history from vatnode?

Sign in, open Usage in the dashboard and press Download CSV in the Check History section. You get one file with your whole history, newest first, named vatnode-checks-YYYY-MM-DD.csv.

What columns does the vatnode check history CSV contain?

Eleven, in this order: checkId, vatId, countryCode, valid, companyName, source, errorCode, cacheHit, createdAt, keyLabel and consultationNumber.

Does the export include test-mode checks or failed checks?

Failed checks are included, with an empty valid value and an errorCode. Test-mode checks are not, because test keys write no history.

How long does vatnode keep my VAT check records, and do I need my own copy?

Each check is anonymised 5 years after it was run and then drops out of your export. Your own retention period is set by your member state, so check it with your adviser and archive the CSV yourself if you need it longer.

Why do some rows in the export have no consultation number?

A consultation number exists only when VIES answered live, your own VAT number was set in Account details and VIES returned one. Cached answers, national-registry answers, errors and checks run before you set it have none.