Skip to navigation
Data models

Taxes

The person’s yearly fiscal data and income-tax return, from the Spanish tax agency (AEAT)

View as Markdown

Where it lives: in the Spain Public Administration results, at data.tax.individual_yearly. APIs with dedicated per-product results endpoints return this model directly.

One entry per fiscal year: what the Agencia Tributaria holds about the person for that year, read in their name from the AEAT’s own site with their consent.

Two documents, and why both matter

For each year the AEAT keeps two different things, and this model carries both:

The fiscal data (datos fiscales)The income-tax return (Modelo 100)
Who writes itThird parties: employers, banks, lenders, brokers, charities — whoever is obliged to report to the AEAT about the person.The person, when they file.
What it holdsEvery payer and every entity, line by line: who paid them and what was withheld, which bank account earned interest, which lender holds their mortgage and how much they paid off.The totals the person declared, the deductions they applied and the result.
Where it is hereThe structured fields: income, liabilities, deductions, the fiscal address.An attachment: the official PDF, attachment:es-aeat-model-100.

The fiscal data is the part a PDF of the return never shows. A return says the person declared mortgage interest; the fiscal data says which bank lent the money, since when, the person’s share of the loan and how much capital they paid back that year. The same goes for income: the return has a total, the fiscal data has every employer and every account behind it.

How many years

The session reads the last closed fiscal years, counting back from last year, as many as last_n_years asks: from 1 to 5, 3 by default. A session opened in 2026 with the default reads 2025, 2024 and 2023.

{
  "executions_features": [
    { "code": "yearly_individual_tax", "configurations": { "last_n_years": 5 } }
  ]
}

A year whose fiscal data the AEAT does not publish is left out, and the other years are delivered: a fiscal year’s data usually appears in the spring after it closes.

What a year says

  • status — submitted when the person’s return for that year was filed and processed by the AEAT; data when only the fiscal data was found.
  • Income, by kind: employment (every employer, with gross pay, withholding and social security contributions), economic activities (each with its activity code), interest from every bank account, savings income, and sales of shares and funds.
  • liabilities.real_estate_loans — every loan linked to a home: the lender, the date it was signed, the person’s participation in it, and the capital and interest paid that year.
  • Deductions: donations, entity by entity.
  • The fiscal address for the year, with the cadastral reference of the main home in address_reference.
product"tax_information"Required
sub_family"tax_information:persons_yearly_fiscal_data"Required
fetch_datestringRequiredformat: "datetime"
Date this product was fetched
primary_taxpayerstringRequired
National identifier of the taxpayer
addressobjectRequired
Fiscal address for the exercise
address_referencestringRequired
Cadastral reference for the main home
country_codestringRequiredformat: "country"
Country code for the tax declaration
currencystringRequiredformat: "currency"
Currency for the tax declaration
tax_agencystringRequired
Tax agency for the tax declaration
fiscal_year_startdateRequired
Start date of the fiscal year
fiscal_year_enddateRequired
End date of the fiscal year
statusenumRequired
Status of the fiscal data
filing_categoryenumRequired
Category of the tax filing
Allowed values:
taxable_basemap from strings to stringsRequired
Total taxable base
total_tax_paidmap from strings to stringsRequired
Total tax paid or withheld
final_tax_resultmap from strings to stringsRequired

Final tax result (to be paid or refunded)

incomeobjectRequired
Detailed breakdown of income
deductionsobjectRequired
Detailed breakdown of deductions
liabilitiesobjectRequired
Detailed breakdown of liabilities
joint_taxpayerslist of stringsOptional
List of national identifiers for joint taxpayers
attachmentslist of objectsOptionalDefaults to []
List of attached supporting documents

The breakdown

Income, deductions and liabilities, each with its own detail:

employmentobjectRequired
Employment income details
capitalobjectRequired
Capital income details
capital_gainsobjectRequired
Capital gains and losses details
businessobjectRequired
Business activity income details
real_estateobjectRequired

Real estate/rental income details

donationslist of objectsRequired
List of donations
total_donationsobjectRequired
Total donations
personal_allowanceobjectRequired

Personal tax-free allowance

family_allowanceobjectRequired

Family tax-free allowances (children, ascendants)

regional_deductionsobjectRequired
Total deductions applied at regional level
state_deductionsobjectRequired
Total deductions applied at state level
total_deductionsobjectRequired
Grand total of all deductions
real_estate_loanslist of objectsOptionalDefaults to []
List of real estate loans

The return, as the AEAT issued it

When the person filed a return for the year, its official PDF travels as an attachment of that year’s entry, attachment:es-aeat-model-100. Its metadata carries the document’s secure verification code (csv-code) and the address at the AEAT’s site where anyone can check it (csv-url): the copy you keep can be proven authentic years later, without asking the person again.