Skip to navigation
Fetching the resultsPublic administration

Yearly personal tax

View as Markdown

Your customer’s income-tax situation, year by year, from the Spanish tax agency (AEAT).

One entry per fiscal year: declared income, deductions and the resulting liability, as filed. It is the reference for verified income when a payslip is not enough — the same document a lender or a landlord would ask for. Field by field in Taxes.

The filed declarations travel with it, as documents of the execution: the figures and the paper they came from, together.

Requires the yearly_individual_tax feature

Features are chosen when the execution starts, not here. An execution that did not ask for yearly_individual_tax answers 204, and the only way to get the data is to run another one.

Which years come back is set in that feature’s configuration and bounded by what the administration still publishes.

StatusMeaning
200The years retrieved, most recent first.
202feature_not_ready — yearly_individual_tax is still running. Only this family waits: the ones that already closed answer now.
204The execution never asked for yearly_individual_tax. No body.
404No execution with that id for your application, or it has been deleted.

Server to server only. This call is authorised with your application secret: it belongs in your backend, never in a browser, a mobile app or anything your customer can read.

Authentication

X-APP-SECRETstring
Application Secret

Path parameters

execution_idstringRequiredformat: "object-id"
The execution, as the acceptance response returned it.

Response

200 OK
One entry per fiscal year the source published: declared income, withholdings, the result, and the status of the declaration. Which years come back is decided by the feature settings and by what the administration keeps.

An empty list is an answer, not a gap: the feature ran and the source reported none.

product"tax_information"
sub_family"tax_information:persons_yearly_fiscal_data"
fetch_datestringformat: "datetime"
Date this product was fetched
primary_taxpayerstring
National identifier of the taxpayer
addressobject
Fiscal address for the exercise
address_referencestring
Cadastral reference for the main home
country_codestringformat: "country"
Country code for the tax declaration
currencystringformat: "currency"
Currency for the tax declaration
tax_agencystring
Tax agency for the tax declaration
fiscal_year_startdate
Start date of the fiscal year
fiscal_year_enddate
End date of the fiscal year
statusenum
Status of the fiscal data
filing_categoryenum
Category of the tax filing
Allowed values:
taxable_basemap from strings to strings
Total taxable base
total_tax_paidmap from strings to strings
Total tax paid or withheld
final_tax_resultmap from strings to strings

Final tax result (to be paid or refunded)

incomeobject
Detailed breakdown of income
deductionsobject
Detailed breakdown of deductions
liabilitiesobject
Detailed breakdown of liabilities
joint_taxpayerslist of stringsOptional
List of national identifiers for joint taxpayers
attachmentslist of objectsOptionalDefaults to []
List of attached supporting documents

Errors

404
Not Found Error
422
Unprocessable Entity Error