Check AEAT notifications and live observations

Use this guide to download and review read-only information from AEAT: official notifications, declaration history, filed returns, and your IVA compensation balance. All commands in this section download data and save it locally. None of them file anything or change your AEAT records.

Before you start

You need:

  • an active profile. Create one non-interactively with aeat config profile create me --quiet --tax-id <NIF/CIF/DNI/NIE> --name "Ana" --surnames "Garcia Lopez".

  • the taxpayer’s fiscal ID (generalized as NIF, CIF, DNI, NIE, or NII) saved in that profile

  • the master-key passphrase that protects your local store. The tool prompts for it, or set AEAT_SECRET_PASSPHRASE to run without a prompt.

  • AEAT live-read authentication configured; see Authenticate with AEAT

1. Official AEAT notifications (DEHu)

DEHu is the official AEAT electronic inbox for notifications (comunicaciones and notificaciones). Download your notifications and save them locally:

aeat app live notifications pull

Download your current DEHu notifications:

aeat app live notifications list

View a specific saved download by its reference number:

aeat app live notifications view <snapshot-id>

Show the most recent snapshot in the active profile:

aeat app live notifications latest

2. Declaration history (expedientes)

Expedientes are the official AEAT record of your past declarations — each filed return for each modelo and year, with its status and filing date.

Download the declaration history for a specific form and year:

aeat app live expedientes pull --modelo 100 --year 2026

Download history for a range of years:

aeat app live expedientes pull --from-year 2020 --to-year 2026 --modelo 303

Leave out --modelo to download history for all your registered forms.

List saved downloads:

aeat app live expedientes list

View a specific download’s details (individual declarations, status, dates, and links to justificantes):

aeat app live expedientes view <snapshot-id>

Show the most recent expedientes snapshot:

aeat app live expedientes latest

3. Filed declaration detail

Download the box-by-box values from a return you have already filed with AEAT.

List the filed returns AEAT holds, without saving their full box values. This still reads from AEAT live, so it needs configured authentication like any other live command:

aeat app live filed list --modelo 303 --from-year 2020 --to-year 2026

Download and save the full box values from a specific filed return:

aeat app live filed pull --modelo 303 --year 2026 --period 1T

Download all filed returns across a year range:

aeat app live filed pull --from-year 2020 --to-year 2026

Download the source declarations that a target filing depends on (for example, download the Modelo 303 returns that a Modelo 390 annual summary needs):

aeat app live filed pull-sources --modelo 303 --year 2026 --period 1T

4. NIF and EU VAT verification

Verify whether a NIF is registered for intra-EU VAT purposes (the VIES register), or check a Spanish NIF in the Spanish ROI register.

Check whether a foreign EU VAT number is valid:

aeat app live verify nif-iva ESB12345678

Check whether a Spanish NIF or NIE appears in the Spanish ROI register:

aeat app live verify tgvi 12345678A

Use --expected valid|invalid|unknown to compare against an expected result.

List past verifications you have run:

aeat app live verify list --surface tgvi

View details of a specific verification:

aeat app live verify view <observation-id>

Show the latest verification observation for a NIF:

aeat app live verify latest --surface nif_iva --nif ESB12345678

5. Official AEAT portal catalogue

View the list of official AEAT online portals the tool knows about and their authentication requirements:

aeat app live portals list

Narrow the list to the portals for one form with --modelo:

aeat app live portals list --modelo 303

Or narrow it to one category with --category. The accepted categories are auth, filing, censo, consultation, borrador, payment, and calendar_reference:

aeat app live portals list --category filing

Use --modelo or --category, not both — they are mutually exclusive.

View portal details

aeat app live portals view <portal-id>

6. Borrador (draft Modelo 100)

The borrador is the pre-calculated Modelo 100 IRPF draft that AEAT makes available to wage earners. Download and view borrador snapshots:

aeat app live borrador 100 list --state active

View a specific borrador’s box values:

aeat app live borrador 100 view <snapshot-id>

Show the latest active draft for a filing year:

aeat app live borrador 100 latest --filing-year 2026

7. IVA compensation balance

Your IVA compensation balance (saldo a compensar) is the amount of overpaid IVA from prior quarters that can be deducted from future Modelo 303 filings. Download and track your current balance:

aeat app live iva-wallet pull --year 2026 --period 4T

Reconstruct the history of past IVA compensation decisions from prior Modelo 303 filings:

aeat app live iva-wallet pull-history --from-year 2020 --to-year 2026

Capture past returns and pull the current IVA evidence in a single read-only run:

aeat app live iva-wallet pull-evidence --from-year 2020 --to-year 2026 --target-year 2026 --target-period 4T

View local history

List persisted compensation balances and decisions:

aeat app live iva-wallet history --as-of-year 2026

Next steps