> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://infonite.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://infonite.dev/_mcp/server.
# On Flow Ended
POST
Triggered when the verification flow finishes. If an `aes_key` was provided during [Create Session](api:POST/es-public-administration/v1/manager/init), the extraction results inside the `data` payload will be delivered encrypted in `aes::Base64(IV + Ciphertext + Tag)` format.
If you configured an `aes_key`, this payload is encrypted. View step-by-step decryption walkthrough and code templates in the **Payload Encryption** guide.
If no `aes_key` was specified, the `data` payload is omitted (null), and you must retrieve the results manually using the session API.
The payload of this event carries **`is_closed: true`**. That field — not the arrival of any webhook, not the widget closing, not a `WAITING` status — is what tells you a session is over and its results are final.
If you also subscribe to [On Partial Results](api:POST/es-public-administration:partial), you will have seen the same session earlier with `is_closed: false`. Branch on that field and you cannot get it wrong.
Reference: https://infonite.dev/api-reference/spain-public-administration/spain-public-administration-api/webhooks/webhook-es-public-administration-ended
## OpenAPI 3.1 Webhook Specification
```yaml
openapi: 3.1.0
info:
title: es-public-administration-v1-0-0-openapi
version: 1.0.0
paths: {}
webhooks:
subpackage_webhooks.webhook:es-public-administration:ended:
post:
operationId: subpackage_webhooks.webhook:es-public-administration:ended
summary: On Flow Ended
description: >
Triggered when the verification flow finishes. If an `aes_key` was
provided during [Create
Session](api:POST/es-public-administration/v1/manager/init), the
extraction results inside the `data` payload will be delivered encrypted
in `aes::Base64(IV + Ciphertext + Tag)` format.
If you configured an `aes_key`, this payload is encrypted. View step-by-step decryption walkthrough and code templates in the **Payload Encryption** guide.
If no `aes_key` was specified, the `data` payload is omitted (null), and
you must retrieve the results manually using the session API.
The payload of this event carries **`is_closed: true`**. That field — not the arrival of any webhook, not the widget closing, not a `WAITING` status — is what tells you a session is over and its results are final.
If you also subscribe to [On Partial Results](api:POST/es-public-administration:partial), you will have seen the same session earlier with `is_closed: false`. Branch on that field and you cannot get it wrong.
responses:
'200':
description: Webhook received successfully
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndedPayload'
components:
schemas:
WebhookEndedPayloadStatusCode:
type: string
enum:
- READY
- WAITING
- COMPLETED
- FAILED
- SYSTEM_CANCELLED
- CLIENT_CANCELLED
- CUSTOMER_CANCELLED
- TIMED_OUT
- CONFIGURATION_ERROR
description: >-
Base status codes for widget flows
Allowed values are:
- `READY`: The flow is waiting for an input
- `WAITING`: Flow is waiting for an external event
- `COMPLETED`: The flow has finalized successfully
- `FAILED`: The flow has failed
- `SYSTEM_CANCELLED`: The flow has ben cancelled by the system
- `CLIENT_CANCELLED`: The flow has been cancelled by the client
- `CUSTOMER_CANCELLED`: The flow has been cancelled by the customer
- `TIMED_OUT`: The flow has timed out
- `CONFIGURATION_ERROR`: The flow has been rejected due to a
configuration error
title: WebhookEndedPayloadStatusCode
FlowResultsSchemaStatusCode:
type: string
enum:
- READY
- WAITING
- COMPLETED
- FAILED
- SYSTEM_CANCELLED
- CLIENT_CANCELLED
- CUSTOMER_CANCELLED
- TIMED_OUT
- CONFIGURATION_ERROR
description: The final execution status code of the session.
title: FlowResultsSchemaStatusCode
FlowResultsSchemaCursor:
type: string
enum:
- es-public-administration:welcome:init
- es-public-administration:welcome:consent
- es-public-administration:connect:source
- es-public-administration:connect:wait
- es-public-administration:bye:completed
- es-public-administration:bye:failure
description: The last screen of the widget experience where the user interacted.
title: FlowResultsSchemaCursor
ConsentOutputAcceptedFeaturesItems:
type: string
enum:
- accounts_read
- cards_read
- deposits_read
- loans_read
- credits_read
- investment_accounts_read
- funds_read
- stocks_read
- pensions_read
- accounts_certificates
- direct_debits_read
- customer_information_read
- source_contracts_read
- cloud_resource_read
- supplier_invoices_read
- client_invoices_read
- labor_check
- public_pensions
- public_document_verification
- yearly_individual_tax
- vehicles_data
- driver_data
- academic_data
- properties_data
- credit_registry_data
description: |-
Features allowed by an engine
Allowed values are:
- `accounts_read`: Financial Accounts Read
- `cards_read`: Financial Cards Read
- `deposits_read`: Financial Deposits Read
- `loans_read`: Financial Loans Read
- `credits_read`: Financial Credits Read
- `investment_accounts_read`: Investment Accounts Read
- `funds_read`: Investment Funds Read
- `stocks_read`: Investment Stocks Read
- `pensions_read`: Pension Plans Read
- `accounts_certificates`: Account Certificates Read
- `direct_debits_read`: Direct Debits Read
- `customer_information_read`: Customer Information Read
- `source_contracts_read`: Source Contracts Read
- `cloud_resource_read`: Cloud Provider Resource Read
- `supplier_invoices_read`: Supplier Invoices Read
- `client_invoices_read`: Client Invoices Read
- `labor_check`: Labor Check
- `public_pensions`: Public Pensions
- `public_document_verification`: Public Document Verification
- `yearly_individual_tax`: Yearly Taxes for Individuals
- `vehicles_data`: Vehicles Data
- `driver_data`: Driver Data
- `academic_data`: Academic Data
- `properties_data`: Properties Data
- `credit_registry_data`: Credit Registry Data
title: ConsentOutputAcceptedFeaturesItems
AcceptedDocumentSchema:
type: object
properties:
version:
type: string
description: The version tag of the legal document template accepted by the user.
hash:
type: string
description: The SHA-256 cryptographic hash of the accepted document content.
sign_date:
type: string
format: datetime
description: The timestamp when the user accepted or signed the document.
signature_provider:
type: string
description: >-
The digital signature mechanism or provider used to complete the
acceptance.
signature_metadata:
type: object
additionalProperties:
description: Any type
description: Additional metadata collected during the signature process.
required:
- version
title: AcceptedDocumentSchema
ConsentOutput:
type: object
properties:
accepted_date:
type: string
format: datetime
description: The timestamp when the user explicitly submitted consent.
accepted_features:
type: array
items:
$ref: '#/components/schemas/ConsentOutputAcceptedFeaturesItems'
default: []
description: >-
The list of features that the user explicitly authorized for
extraction.
user_ip:
type: string
description: The IP address of the customer device that provided consent.
user_agent:
type: string
description: The browser user agent string of the customer device.
origin:
type: string
description: The origin website URL where the customer loaded the widget.
accepted_documents:
type: object
additionalProperties:
$ref: '#/components/schemas/AcceptedDocumentSchema'
default: {}
description: >-
A dictionary mapping document identifiers to their structured
acceptance metadata.
description: >-
The structured consent information, including device audit trail and
accepted documents.
title: ConsentOutput
FlowResultsSchemaRetrievedFeaturesItems:
type: string
enum:
- accounts_read
- cards_read
- deposits_read
- loans_read
- credits_read
- investment_accounts_read
- funds_read
- stocks_read
- pensions_read
- accounts_certificates
- direct_debits_read
- customer_information_read
- source_contracts_read
- cloud_resource_read
- supplier_invoices_read
- client_invoices_read
- labor_check
- public_pensions
- public_document_verification
- yearly_individual_tax
- vehicles_data
- driver_data
- academic_data
- properties_data
- credit_registry_data
description: |-
Features allowed by an engine
Allowed values are:
- `accounts_read`: Financial Accounts Read
- `cards_read`: Financial Cards Read
- `deposits_read`: Financial Deposits Read
- `loans_read`: Financial Loans Read
- `credits_read`: Financial Credits Read
- `investment_accounts_read`: Investment Accounts Read
- `funds_read`: Investment Funds Read
- `stocks_read`: Investment Stocks Read
- `pensions_read`: Pension Plans Read
- `accounts_certificates`: Account Certificates Read
- `direct_debits_read`: Direct Debits Read
- `customer_information_read`: Customer Information Read
- `source_contracts_read`: Source Contracts Read
- `cloud_resource_read`: Cloud Provider Resource Read
- `supplier_invoices_read`: Supplier Invoices Read
- `client_invoices_read`: Client Invoices Read
- `labor_check`: Labor Check
- `public_pensions`: Public Pensions
- `public_document_verification`: Public Document Verification
- `yearly_individual_tax`: Yearly Taxes for Individuals
- `vehicles_data`: Vehicles Data
- `driver_data`: Driver Data
- `academic_data`: Academic Data
- `properties_data`: Properties Data
- `credit_registry_data`: Credit Registry Data
title: FlowResultsSchemaRetrievedFeaturesItems
CustomerType:
type: string
enum:
- person
- company
- unknown
title: CustomerType
IdentificationNumberSchemaType:
type: string
enum:
- unknown
- es:dni
- es:nie
- es:cif
- es:ssn
- co:cc
- co:ce
- co:nit
- co:ti
description: >-
Kind of document the number belongs to (e.g. a national ID, passport,
tax ID, or Social
Security number).
title: IdentificationNumberSchemaType
IdentificationNumberSchema:
type: object
properties:
type:
$ref: '#/components/schemas/IdentificationNumberSchemaType'
description: >-
Kind of document the number belongs to (e.g. a national ID,
passport, tax ID, or Social
Security number).
value:
type: string
description: The number itself, as reported by the source.
validated:
type: boolean
description: >-
True when the value passed the platform's format and check-digit
validation. It vouches for
the NUMBER being well-formed — not for the official status of the
document behind it.
country:
type: string
format: country
description: Country that issued the number, as a two-letter ISO code.
valid_until:
type: string
format: date
description: Expiry date of the document, when the source reports it.
required:
- type
- value
- validated
description: >-
One identification document: its type, its value, and whether the value
passed validation.
title: IdentificationNumberSchema
PersonGender:
type: string
enum:
- male
- female
- rather_not_say
- unknown
title: PersonGender
CivilStatus:
type: string
enum:
- single
- married
- divorced
- widowed
- separated
- unknown
title: CivilStatus
AddressSchema:
type: object
properties:
title:
type: string
description: Free label for the address (e.g. `Headquarter`, `Domicilio`).
street:
type: string
description: 'Street line: name and number.'
street_extra:
type: string
description: 'Second street line: floor, suite, staircase, apartment...'
municipality:
type: string
description: Municipality the address belongs to.
city:
type: string
description: City or town.
state:
type: string
description: State or province code.
country:
type: string
format: country
description: Country, as a two-letter ISO code.
zip_code:
type: string
description: Postal code.
description: >-
A postal address. It is reused wherever the platform reports one — a
person's home, a
company's registered office, a property's location — so these fields
describe the address
itself; what it belongs to is told by the object carrying it.
title: AddressSchema
CustomerProfileSchema:
type: object
properties:
product:
type: string
enum:
- customer_information
description: >-
The product type identifier. Always `customer_information` for this
product.
sub_family:
type: string
enum:
- customer_information:user_profile
description: >-
The sub-family identifier: `customer_information:user_profile`, the
customer's profile at
the institution.
fetch_date:
type: string
format: datetime
description: Date this information was fetched.
type:
$ref: '#/components/schemas/CustomerType'
description: >-
The kind of customer: a person or a company. This is the switch that
tells you how to read
the rest of the profile.
name:
type: string
description: >-
For persons, the given name(s); for companies, the registered legal
name (razón social).
name_extra:
type: string
description: >-
**Persons only** — the rest of the legal name; Spanish institutions
report both surnames
here. Empty for companies.
alias:
type: string
description: >-
How the institution addresses the customer when it differs from the
legal name — a chosen
or commercial name.
identification_numbers:
type: array
items:
$ref: '#/components/schemas/IdentificationNumberSchema'
description: >-
The customer's identification documents as the institution registers
them — for persons a
DNI/NIE, passport or Social Security number; for companies the tax
ID (CIF). Each entry
carries its type, its value, and whether the value passed
validation.
birth_date:
type: string
format: date
description: >-
For persons, the date of birth; for companies, the date of
incorporation, when the source
provides it.
birth_country:
type: string
format: country
description: Country of birth, as a two-letter ISO code.
nationality_country:
type: string
format: country
description: >-
For persons, the country of nationality; for companies, the country
of the registered
seat. Two-letter ISO code.
residence_country:
type: string
format: country
description: >-
For persons, the country of residence; for companies, the country of
its tax residence.
Two-letter ISO code.
gender:
$ref: '#/components/schemas/PersonGender'
description: >-
**Persons only** — gender as declared at the institution. `unknown`
for companies, and for
persons whose source does not disclose it.
civil_status:
$ref: '#/components/schemas/CivilStatus'
description: >-
**Persons only** — civil status as declared at the institution.
`unknown` for companies,
and for persons whose source does not disclose it.
number_of_children:
type: integer
description: >-
**Persons only** — number of children, when the institution records
it. Empty for
companies.
emails:
type: array
items:
type: string
description: Email addresses of the customer, as they appear at the source.
phones:
type: array
items:
type: string
description: Phone numbers of the customer, as they appear at the source.
addresses:
type: array
items:
$ref: '#/components/schemas/AddressSchema'
description: Postal addresses of the customer, as they appear at the source.
language:
type: string
format: language
description: The customer's preferred language, as an ISO language code.
member_since:
type: string
format: date
description: >-
Date the customer's relationship with the institution began, when
the source reports it.
required:
- product
- sub_family
- fetch_date
- type
- identification_numbers
- gender
- civil_status
- emails
- phones
- addresses
description: >-
The customer's identity as the connected institution knows it: names,
identification
documents, birth and nationality, contact details (emails, phones,
addresses) and declared
situation (civil status, children, membership age). Use it to verify
identity and to
cross-check data the user typed against what their institution knows
about them.
**One profile describes both persons and companies** — `type` tells you
which one you are
reading. Some fields switch meaning accordingly (`name`, `birth_date`,
`nationality_country`, `residence_country` — each one says how); the
strictly person-only
fields behave predictably for companies: `name_extra` and
`number_of_children` come empty,
and `gender` / `civil_status` come as `unknown`.
title: CustomerProfileSchema
CustomerFamily:
type: object
properties:
profile:
$ref: '#/components/schemas/CustomerProfileSchema'
description: Customer profile
title: CustomerFamily
HigherEducationSchemaSubFamily:
type: string
enum:
- academic_data:higher_bachelor
- academic_data:higher_master
- academic_data:higher_doctorate
title: HigherEducationSchemaSubFamily
HigherEducationSchema:
type: object
properties:
product:
type: string
enum:
- academic_data
sub_family:
$ref: '#/components/schemas/HigherEducationSchemaSubFamily'
fetch_date:
type: string
format: datetime
description: Date this product was fetched
qualification_name:
type: string
description: Qualification name.
institution_name:
type: string
description: Institution name.
institution_country:
type: string
format: country
description: Country of the institution.
completion_status:
type: string
description: Completion status
issue_date:
type: string
format: date
description: Date when the qualification was issued.
start_date:
type: string
format: date
description: Date when the education started.
end_date:
type: string
format: date
description: Date when the education ended.
official_id:
type: string
description: National registry number / Diploma serial number.
verification_url:
type: string
description: Link to public administration validator.
thesis_title:
type: string
description: Thesis title - Mandatory for PhD, common for Master
field_of_study:
type: string
description: ISCED-F code or name (e.g., "061 ICTs")
total_credits:
type: string
format: number
description: ECTS credits (Common in Europe)
grade_average:
type: string
format: number
description: GPA or local scale (e.g., 0-10 in Spain)
required:
- product
- sub_family
- fetch_date
- qualification_name
- institution_name
- institution_country
- completion_status
- total_credits
- grade_average
title: HigherEducationSchema
SecondaryEducationSchemaSubFamily:
type: string
enum:
- academic_data:secondary_general
- academic_data:secondary_vocational
- academic_data:professional_certification
title: SecondaryEducationSchemaSubFamily
SecondaryEducationSchema:
type: object
properties:
product:
type: string
enum:
- academic_data
sub_family:
$ref: '#/components/schemas/SecondaryEducationSchemaSubFamily'
fetch_date:
type: string
format: datetime
description: Date this product was fetched
qualification_name:
type: string
description: Qualification name.
institution_name:
type: string
description: Institution name.
institution_country:
type: string
format: country
description: Country of the institution.
institution_code:
type: string
description: Local school ID or center code.
region:
type: string
description: State, Province, or Autonomous Community.
completion_status:
type: string
description: Completion status
issue_date:
type: string
format: date
description: Date when the qualification was issued.
start_date:
type: string
format: date
description: Date when the education started.
end_date:
type: string
format: date
description: Date when the education ended.
official_id:
type: string
description: National registry number / Diploma serial number.
verification_url:
type: string
description: Link to public administration validator.
study_framework:
type: string
description: Education system/law (e.g., "LOE", "K-12", "GCSE")
national_registry_id:
type: string
description: National level ID (e.g., MEC in Spain)
regional_registry_id:
type: string
description: State/Regional level ID
archive_volume:
type: string
description: Book/Volume number (Libro)
archive_entry:
type: string
description: Entry or order number (Folio/Orden)
required:
- product
- sub_family
- fetch_date
- qualification_name
- institution_name
- institution_country
- completion_status
title: SecondaryEducationSchema
AcademicFamily:
type: object
properties:
higher_education_degrees:
type: array
items:
$ref: '#/components/schemas/HigherEducationSchema'
description: 'Higher education degrees:'
secondary_education:
type: array
items:
$ref: '#/components/schemas/SecondaryEducationSchema'
description: Secondary education
title: AcademicFamily
DrivingLicenseSchema:
type: object
properties:
category:
type: string
description: Class of driving license.
date:
type: string
format: date
description: Granted date.
expires:
type: string
format: date
description: Expiry date.
required:
- category
- date
title: DrivingLicenseSchema
PointMovementSchema:
type: object
properties:
description:
type: string
description: Description of the movement.
date:
type: string
format: date
description: Date of firmness (legal date).
effective_date:
type: string
format: date
description: Effective date of the movement.
points_delta:
type: integer
description: Points added or subtracted (signed integer).
balance_after:
type: integer
description: Balance after the movement.
infraction_reference:
type: string
description: Reference number of the infraction.
infraction_date:
type: string
format: date
description: Date of the infraction.
authority_name:
type: string
description: Name of the authority.
authority_code:
type: string
description: Code of the authority.
required:
- description
- date
- points_delta
- balance_after
title: PointMovementSchema
EUDriverDataSchema:
type: object
properties:
product:
type: string
enum:
- driver_data
sub_family:
type: string
enum:
- driver_data:eu_driver_data
fetch_date:
type: string
format: datetime
description: Date this product was fetched
country:
type: string
format: country
description: Country that expired the license.
licences:
type: array
items:
$ref: '#/components/schemas/DrivingLicenseSchema'
description: List of driving licenses.
point_balance:
type: integer
description: Balance of the driver in points.
name:
type: string
description: First name of the driver
name_extra:
type: string
description: Last name of the driver.
identifier:
$ref: '#/components/schemas/IdentificationNumberSchema'
description: NIF of the driver.
dangerous_goods_authorized:
type: boolean
description: Whether the driver is authorized to transport dangerous goods.
school_transport_authorized:
type: boolean
description: Whether the driver is authorized to transport school goods.
address:
type: string
description: Address of the driver.
point_movements:
type: array
items:
$ref: '#/components/schemas/PointMovementSchema'
description: List of movements. If not present means the data was not consulted.
required:
- product
- sub_family
- fetch_date
- country
- licences
title: EUDriverDataSchema
VehicleInsuranceSchema:
type: object
properties:
is_active:
type: boolean
description: Whether the vehicle has an active insurance policy.
company:
type: string
description: Name of the insurance company.
start_date:
type: string
format: date
description: Start date of the insurance policy.
end_date:
type: string
format: date
description: End date of the insurance policy.
required:
- is_active
description: Vehicle insurance policy.
title: VehicleInsuranceSchema
SimpleVehicleReport:
type: object
properties:
report_date:
type: string
format: datetime
description: Date when the information was consulted.
has_incidents:
type: boolean
description: >-
Whether the vehicle has incidents, meaning that at the time of the
inquiry, there are one or more annotations
that prevent administrative processing or the circulation of the
vehicle. For your safety, request a full
vehicle report to know the details of all the information held in
the Registry regarding the vehicle consulted.
required:
- report_date
- has_incidents
description: Simple vehicle report.
title: SimpleVehicleReport
EUOwnedVehicleSchema:
type: object
properties:
product:
type: string
enum:
- driver_data
sub_family:
type: string
enum:
- driver_data:eu_owned_vehicle
fetch_date:
type: string
format: datetime
description: Date this product was fetched
country:
type: string
format: country
description: Country where the vehicle is registered.
registration_date:
type: string
format: date
description: Registration date of the vehicle.
inspection_expiry_date:
type: string
format: date
inspection_pending:
type: boolean
description: >-
If true, the vehicle has failed the previous inspection or is
pending to be inspected.
license_plate:
type: string
description: License plate number of the vehicle.
administrative_situation:
type: string
description: Current administrative situation of the vehicle.
vin:
type: string
description: Vehicle Identification Number.
make:
type: string
description: Vehicle manufacturer.
model:
type: string
description: Vehicle model name.
trim:
type: string
description: Specific vehicle trim/variant.
color:
type: string
description: Color of the vehicle.
mileage:
type: integer
mileage_date:
type: string
format: date
description: Date when the mileage was recorded.
fuel_type:
type: string
description: Fuel type of the vehicle.
emission_class:
type: string
description: Emission class of the vehicle.
insurance:
$ref: '#/components/schemas/VehicleInsuranceSchema'
simple_vehicle_report:
$ref: '#/components/schemas/SimpleVehicleReport'
required:
- product
- sub_family
- fetch_date
- country
- registration_date
title: EUOwnedVehicleSchema
DriverFamily:
type: object
properties:
data:
$ref: '#/components/schemas/EUDriverDataSchema'
description: Driver data
vehicles:
type: array
items:
$ref: '#/components/schemas/EUOwnedVehicleSchema'
description: Officially owned vehicles
title: DriverFamily
WorkType:
type: string
enum:
- unknown
- employee
- self_employed
- public_employee
- vacations
- unemployment_benefits
- other
title: WorkType
WorkContractType:
type: string
enum:
- unknown
- permanent
- temporary
- training
- professional_practices
- fixed_discontinuous
title: WorkContractType
WorkScheduleType:
type: string
enum:
- unknown
- full_time
- part_time
title: WorkScheduleType
WorkRelationSchema:
type: object
properties:
activity_start:
type: string
format: date
description: >-
Activity start date — the date the TGSS counts contributed days
from.
activity_end:
type: string
format: date
description: Activity end date. Empty while the relation is ongoing.
name:
type: string
description: >-
Display name of the relation: the employer's name for employees, the
regime for
self-employment, and the situation description for benefit periods.
regime:
type: string
description: Social Security regime of this relation.
ccc:
type: string
description: >-
Employer contribution account code (CCC) — the join key to
`contribution_base_by_company`.
Absent for self-employment, which has no employer account.
assimilated:
type: boolean
default: false
description: >-
True for situations assimilated to registration (benefit periods,
paid untaken
vacations...) — periods that count for Social Security but are not
an actual job. Skip
them when reasoning about employment or earned income.
work_type:
$ref: '#/components/schemas/WorkType'
description: >-
Work type of this relation (e.g. `employee`, `self_employed`,
`unemployment_benefits`).
contract_type:
$ref: '#/components/schemas/WorkContractType'
description: >-
Contract type as mapped from the TGSS classification; `unknown` when
the source key has
no mapping.
work_schedule:
$ref: '#/components/schemas/WorkScheduleType'
description: 'Work schedule: `full_time`, `part_time`, or `unknown`.'
contribution_group:
type: string
description: Contribution group of the worker in this relation.
collective_agreement:
type: string
description: Collective agreement governing this relation, when declared.
social_security_days:
type: integer
description: >-
Days this relation counts for Social Security. Simultaneous
relations each count their
own days, so summing across relations overstates — the deduplicated
career total is the
top-level `social_security_days`.
currently_active:
type: boolean
description: True while this relation is ongoing (it has no end date yet).
required:
- activity_start
- name
- work_type
- contract_type
- work_schedule
description: >-
One period of the person's labor life: an employment, a self-employment
stretch, or a
situation that counts for Social Security without being a job.
title: WorkRelationSchema
ContributionMonthStatus:
type: string
enum:
- registered
- no_alta
- no_base_registered
- pending_update
- not_yet_elapsed
- not_yet_settled
description: >-
State of one month in a social-security contribution-base history.
The first five values are what the TGSS report prints.
``not_yet_settled``
is the refined reading of a printed ``no_alta`` that falls inside a
certified open relation near the report's emission date: contribution
bases
register with a settlement lag, so those months mean "not settled yet",
never "not registered" — they must not count as gaps or zeros.
title: ContributionMonthStatus
CurrencyAmountSchemaCurrency:
oneOf:
- type: string
format: currency
- type: string
enum:
- '***'
description: >-
Three-letter ISO currency code — or `***` when the source did not
disclose the currency.
title: CurrencyAmountSchemaCurrency
CurrencyAmountSchema:
type: object
properties:
currency:
$ref: '#/components/schemas/CurrencyAmountSchemaCurrency'
description: >-
Three-letter ISO currency code — or `***` when the source did not
disclose the currency.
amount:
type: string
format: number
description: Decimal number with 2 digits precision
required:
- currency
- amount
description: A monetary amount together with its currency.
title: CurrencyAmountSchema
MonthlyBaseSchema:
type: object
properties:
date:
type: string
format: date
description: >-
Last day of the contribution month — a convenience key for
date-indexed consumers; `year`
and `month` carry the same information.
year:
type: integer
description: Contribution year.
month:
type: integer
description: Contribution month (1-12).
status:
$ref: '#/components/schemas/ContributionMonthStatus'
description: >-
State of the month: `registered` (base certified by the TGSS),
`pending_update`
(contribution reported, amount not published yet — an existing
contribution, NOT a gap),
`not_yet_settled` (recent month still inside the settlement lag),
`no_base_registered`, or
`no_alta` (not registered that month). A month absent from the flat
history altogether
means no contribution row existed for it.
base:
$ref: '#/components/schemas/CurrencyAmountSchema'
description: >-
Monthly contribution base (gross). Carries a numeric amount only
when the month is
`registered`; in any other state the amount is not available —
unavailable, not zero.
provisional:
type: boolean
default: false
description: >-
True when the base is provisional and may still be regularized by
the TGSS — typical for
self-employed workers until the yearly settlement.
required:
- date
- year
- month
- status
- base
description: >-
One month of contribution: its state and, when registered, the gross
base amount.
title: MonthlyBaseSchema
CompanyContributionsSchema:
type: object
properties:
company_name:
type: string
description: Employer or regime name, as certified by the TGSS.
ccc:
type: string
description: >-
Employer contribution account code (CCC) — the join key linking this
history to the
matching entries in `work_relations_history`. Absent for
self-employment, which has no
employer account.
regime:
type: string
description: Social Security regime of this account.
is_benefit_block:
type: boolean
default: false
description: >-
True when this entry tracks a benefit (e.g. cessation-of-activity
protection for the
self-employed), not an actual employer. Its bases are NOT earned
income — exclude them
from any income computation.
months:
type: array
items:
$ref: '#/components/schemas/MonthlyBaseSchema'
default: []
description: Monthly contribution bases of this account, most recent first.
description: >-
The month-by-month contribution history of one employer account (or
regime).
title: CompanyContributionsSchema
IncomeFloorStatus:
type: string
enum:
- computed
- not_currently_active
- activity_unknown
- insufficient_data
description: Whether a guaranteed-minimum income floor could be asserted at all.
title: IncomeFloorStatus
IncomeFloorBasis:
type: string
enum:
- window_minimum
description: >-
How a company entry's floor was derived.
The per-company list only ever contains companies CONTRIBUTING to the
computed floor (closed/stale employments are excluded entirely, so no
past
salary can be misread as a current one); the enum names the derivation
and
leaves room for future methods.
title: IncomeFloorBasis
CompanyIncomeFloorSchema:
type: object
properties:
company_name:
type: string
description: Employer or regime this floor comes from.
ccc:
type: string
description: Employer contribution account code (CCC) of this company.
work_type:
$ref: '#/components/schemas/WorkType'
description: Work type behind this income.
monthly_floor:
$ref: '#/components/schemas/CurrencyAmountSchema'
description: >-
Estimated minimum NET monthly income from this company: its worst
observed window
month's net share, after worker Social Security contributions and
IRPF withholding at
that month's real income mix. Every unknown (contract type, age,
family situation) is
resolved toward more deductions, so real take-home pay can only be
equal or higher.
annual_floor:
$ref: '#/components/schemas/CurrencyAmountSchema'
description: Estimated minimum NET annual income from this company.
gross_monthly_floor:
$ref: '#/components/schemas/CurrencyAmountSchema'
description: >-
The certified GROSS monthly floor this company's net figure derives
from — the minimum
contribution base over the observation window.
gross_annual_floor:
$ref: '#/components/schemas/CurrencyAmountSchema'
description: >-
The certified GROSS annual floor from this company (the gross
monthly floor x12).
basis:
$ref: '#/components/schemas/IncomeFloorBasis'
description: >-
How this floor was derived (e.g. `window_minimum`: the minimum base
over the trailing
window of fully certified months).
observed_months:
type: integer
default: 0
description: >-
Number of certified months the floor is based on — the more months,
the steadier the
floor.
required:
- company_name
- monthly_floor
- annual_floor
- basis
description: >-
One company's share of the income floor: the minimum net income it
contributes.
title: CompanyIncomeFloorSchema
IncomeFloorSchema:
type: object
properties:
status:
$ref: '#/components/schemas/IncomeFloorStatus'
description: >-
Whether a floor could be asserted: `computed` (floor available),
`not_currently_active`
(no ongoing employment — the current floor is zero),
`insufficient_data` (active, but no
certified window to measure), or `activity_unknown` (no employment
evidence either way).
monthly_floor:
$ref: '#/components/schemas/CurrencyAmountSchema'
description: >-
Estimated minimum NET monthly income: the worst observed window
month after worker
Social Security contributions and IRPF withholding. A lower bound
for risk assessment —
NOT a salary estimate: every unknown in the conversion (contract
type, age, family
situation) is resolved toward more deductions, so real take-home pay
can only be equal
or higher. For self-employed workers it deliberately understates
real income; combine
with other signals.
annual_floor:
$ref: '#/components/schemas/CurrencyAmountSchema'
description: The net monthly floor, annualized.
gross_monthly_floor:
$ref: '#/components/schemas/CurrencyAmountSchema'
description: >-
Guaranteed minimum GROSS monthly income, certified by the
contribution bases. The net
floor is minimized over months separately, so it can come from a
different (net-worse)
month than this gross minimum.
gross_annual_floor:
$ref: '#/components/schemas/CurrencyAmountSchema'
description: The gross monthly floor, annualized (x12).
estimated_deduction_rate:
type: string
format: number
default: nan
description: Decimal number with 4 digits precision
companies:
type: array
items:
$ref: '#/components/schemas/CompanyIncomeFloorSchema'
default: []
description: >-
Only the companies contributing to the computed floor (ongoing,
recent activity). Past
employments are never listed here — their history is in
`contribution_base_by_company` —
so nothing in this list can be misread as a salary the person no
longer earns.
method_version:
type: string
description: >-
Version of the floor derivation method. Bumped whenever the
algorithm changes meaning —
compare floors only within the same version.
required:
- status
description: >-
A guaranteed minimum NET income derived from the contribution bases — a
floor for
risk assessment, never a salary estimate. The certified gross lower
bound travels
alongside in the `gross_*` fields.
title: IncomeFloorSchema
ProductAttachmentType:
type: string
enum:
- attachment:attachment
- attachment:supplier_invoice
- attachment:client_invoice
- attachment:es-tgss-life-report
- attachment:es-tgss-contribution-base-report
- attachment:es-aeat-model-100
- attachment:es-cirbe-report
- attachment:sepa-direct-debit-bill
description: Product Attachment Type
title: ProductAttachmentType
FileAttachmentSchema:
type: object
properties:
product:
type: string
enum:
- attachment
default: attachment
description: The product type identifier. Always `attachment`.
sub_family:
$ref: '#/components/schemas/ProductAttachmentType'
description: >-
What kind of document this is (e.g.
`attachment:es-tgss-life-report`).
id:
type: string
format: ObjectId
description: >-
Attachment identifier — use it to download the file through the
execution's attachments
endpoint.
content_name:
type: string
description: File name of the document.
content_hash:
type: string
description: Fingerprint of the content, to verify its integrity.
content_type:
type: string
format: mime-type
description: MIME type of the content.
metadata:
type: object
additionalProperties:
description: Any type
description: >-
Extra facts about the document, as simple key-value pairs (e.g. its
official verification
code, its issue date).
required:
- sub_family
- id
- content_name
- content_type
- metadata
description: >-
A document attached to a result — an official report, a receipt, an
invoice... The entry
describes the file; its bytes are downloaded through the execution's
attachments endpoint
using `id`.
title: FileAttachmentSchema
TGSSSpainLaborCheckSchema:
type: object
properties:
product:
type: string
enum:
- social_security
description: >-
The product type identifier. Always `social_security` for this
product.
sub_family:
type: string
enum:
- social_security:spain_labor_check
description: >-
The sub-family identifier: `social_security:spain_labor_check`, the
Spanish Social Security (TGSS) labor life
check.
fetch_date:
type: string
format: datetime
description: Date this product was fetched.
currently_active:
type: boolean
description: >-
True when the person is currently WORKING — registered as active
with Social Security.
Receiving an unemployment benefit is not active employment: a
benefit recipient shows `false`
here.
current_work_types:
type: array
items:
$ref: '#/components/schemas/WorkType'
description: >-
The person's current work statuses: one entry per ongoing relation,
so repeated values reveal
simultaneous jobs (two `employee` entries = two concurrent
employments). An ongoing benefit
shows as `unemployment_benefits`. An empty list means nothing
ongoing — no job and no benefit.
social_security_days:
type: integer
description: >-
Total days effectively counted by Social Security over the whole
career. Simultaneous
employments are counted once, so this is NOT the sum of the
per-relation day counts.
work_relations_history:
type: array
items:
$ref: '#/components/schemas/WorkRelationSchema'
description: >-
Work relation history, most recent first — ongoing and finished
relations, including
situations assimilated to registration such as benefit periods.
contribution_base_by_company:
type: array
items:
$ref: '#/components/schemas/CompanyContributionsSchema'
default: []
description: >-
Contribution-base history grouped per employer account, most recent
first. Join each group to
its work relation through the `ccc` code.
income_floor:
$ref: '#/components/schemas/IncomeFloorSchema'
description: >-
Guaranteed minimum NET income derived from the certified
contribution bases (the certified
gross lower bound travels alongside it). A floor for risk
assessment, never a salary
estimate.
attachments:
type: array
items:
$ref: '#/components/schemas/FileAttachmentSchema'
default: []
description: >-
List of attached supporting documents (e.g. the original TGSS PDF
reports this product was
extracted from).
contribution_base_history:
type: array
items:
$ref: '#/components/schemas/MonthlyBaseSchema'
description: >-
Flat monthly contribution-base history, most recent first. Months
only — company attribution lives in `contribution_base_by_company`,
which groups these same months per employer account.
required:
- product
- sub_family
- fetch_date
- work_relations_history
- contribution_base_history
description: >-
The person's labor life with the Spanish Social Security (TGSS). It
answers three questions:
who they have worked for and when (`work_relations_history`), what they
have contributed
month by month per employer account (`contribution_base_by_company`),
and what that means
today — a guaranteed minimum NET income floor (`income_floor`, a lower
bound derived from
the contribution bases, never a salary estimate) and the person's
current work statuses
(`current_work_types`). Use it to verify employment, gauge income
stability and assess risk;
the source reports the data was read from travel in `attachments`.
title: TGSSSpainLaborCheckSchema
PublicPensionAmountsSchema:
type: object
properties:
base:
$ref: '#/components/schemas/CurrencyAmountSchema'
description: Base pension amount
revaluation:
$ref: '#/components/schemas/CurrencyAmountSchema'
description: Revaluation amount
total:
$ref: '#/components/schemas/CurrencyAmountSchema'
description: >-
Total pension amount. Is the brut amount of the pension, before any
deduction
net_amount:
$ref: '#/components/schemas/CurrencyAmountSchema'
description: Net amount of the pension, after all deductions
required:
- base
- revaluation
- total
- net_amount
title: PublicPensionAmountsSchema
TGSSSpainPublicPensionSchema:
type: object
properties:
product:
type: string
enum:
- social_security
sub_family:
type: string
enum:
- social_security:spain_public_pension
fetch_date:
type: string
format: datetime
description: Date this product was fetched
product_name:
type: string
description: Product name
product_alias:
type: string
description: Product alias
start_date:
type: string
format: date
description: Pension start date *(If proceeds)*
regime:
type: string
description: Pension regime
amounts:
$ref: '#/components/schemas/PublicPensionAmountsSchema'
description: Pension amounts if is active
required:
- product
- sub_family
- fetch_date
- product_name
- start_date
- amounts
title: TGSSSpainPublicPensionSchema
EmploymentFamily:
type: object
properties:
labor_check:
$ref: '#/components/schemas/TGSSSpainLaborCheckSchema'
description: Labor check
pensions:
type: array
items:
$ref: '#/components/schemas/TGSSSpainPublicPensionSchema'
description: Public Pensions
title: EmploymentFamily
FiscalDataStatus:
type: string
enum:
- unknown
- data
- draft
- submitted
- not_required
- amended
title: FiscalDataStatus
YearlyPersonalTaxSituationSchemaFilingCategory:
type: string
enum:
- individual
- joint
description: Category of the tax filing
title: YearlyPersonalTaxSituationSchemaFilingCategory
CurrencyAmount-Output:
type:
- object
- 'null'
additionalProperties:
type: string
title: CurrencyAmount-Output
CurrencyAmountInputCurrency:
oneOf:
- type: string
format: currency
- type: string
enum:
- '***'
title: CurrencyAmountInputCurrency
CurrencyAmount-Input:
type: object
properties:
currency:
$ref: '#/components/schemas/CurrencyAmountInputCurrency'
default: '***'
amount:
type: string
format: number
default: NaN
description: Decimal number with 2 digits precision
title: CurrencyAmount-Input
EmploymentIncomeLine:
type: object
properties:
employer_id:
type: string
description: Identifier of the employer (NIF/CIF)
employer_name:
type: string
description: Name of the employer
gross_income:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Gross income from this employer
tax_withheld:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Income tax withheld by this employer
social_security_contributions:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Social security contributions paid
taxpayer_id:
type: string
description: National identifier of the taxpayer for this line
required:
- employer_id
- employer_name
- gross_income
- tax_withheld
- social_security_contributions
- taxpayer_id
title: EmploymentIncomeLine
EmploymentIncome:
type: object
properties:
lines:
type: array
items:
$ref: '#/components/schemas/EmploymentIncomeLine'
description: List of employment income sources
total_gross:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Total gross employment income
total_withheld:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Total income tax withheld from employment
total_social_security:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Total social security contributions
required:
- lines
- total_gross
- total_withheld
- total_social_security
title: EmploymentIncome
CapitalIncomeLine:
type: object
properties:
provider_id:
type: string
description: Identifier of the financial entity (NIF/CIF)
provider_name:
type: string
description: Name of the financial entity
account_number:
type: string
description: Account number or IBAN
asset_type:
type: string
description: Type of asset (e.g., Interests, Dividends)
gross_income:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Gross capital income
tax_withheld:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Tax withheld from capital income
penalization:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Penalization for early withdrawal
deductible_expenses:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Deductible administration or custody fees
taxpayer_id:
type: string
description: National identifier of the taxpayer for this line
required:
- asset_type
- gross_income
- tax_withheld
- penalization
- deductible_expenses
- taxpayer_id
title: CapitalIncomeLine
CapitalIncome:
type: object
properties:
lines:
type: array
items:
$ref: '#/components/schemas/CapitalIncomeLine'
description: List of capital income sources
total_gross:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Total gross capital income
total_withheld:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Total tax withheld from capital income
total_penalization:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Total penalization
total_expenses:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Total deductible expenses
required:
- lines
- total_gross
- total_withheld
- total_penalization
- total_expenses
title: CapitalIncome
CapitalGainLine:
type: object
properties:
issuer_id:
type: string
description: Identifier of the issuer
issuer_name:
type: string
description: Name of the issuer
broker_id:
type: string
description: Identifier of the broker
broker_name:
type: string
description: Name of the broker
asset_description:
type: string
description: Description of the asset sold
asset_type:
type: string
description: Type of asset (e.g., Shares, Crypto, Real Estate)
sale_date:
type: string
format: date
description: Date of sale
sale_value:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Total sale value (net of expenses)
sale_expenses:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Expenses associated with the sale
taxpayer_id:
type: string
description: National identifier of the taxpayer for this line
required:
- asset_description
- asset_type
- sale_value
- sale_expenses
- taxpayer_id
title: CapitalGainLine
CapitalGains:
type: object
properties:
lines:
type: array
items:
$ref: '#/components/schemas/CapitalGainLine'
description: List of capital gain operations
required:
- lines
title: CapitalGains
BusinessActivityLine:
type: object
properties:
payer_id:
type: string
description: Payer NIF
description:
type: string
description: Description of the business activity
activity_code:
type: string
description: Activity code (IAE / NACE)
total_income:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Total business income
tax_withheld:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Tax withheld from the activity
taxpayer_id:
type: string
description: National identifier of the taxpayer for this line
required:
- description
- activity_code
- total_income
- tax_withheld
- taxpayer_id
title: BusinessActivityLine
BusinessIncome:
type: object
properties:
activities:
type: array
items:
$ref: '#/components/schemas/BusinessActivityLine'
description: List of business activities
total_income:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Total economic activities income
total_withheld:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Total economic activities withheld
social_security_contributions:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Social security contributions paid
required:
- activities
- total_income
- total_withheld
- social_security_contributions
title: BusinessIncome
RealEstateIncomeLine:
type: object
properties:
cadastral_reference:
type: string
description: Cadastral reference of the property
address:
type: string
description: Full address of the property
gross_income:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Gross rental income
deductible_expenses:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Total deductible expenses for this property
net_income:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Net rental income
taxpayer_id:
type: string
description: National identifier of the taxpayer for this line
required:
- address
- gross_income
- deductible_expenses
- net_income
- taxpayer_id
title: RealEstateIncomeLine
RealEstateIncome:
type: object
properties:
properties:
type: array
items:
$ref: '#/components/schemas/RealEstateIncomeLine'
description: List of rental properties
total_gross_income:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Total gross rental income
total_net_income:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Total net rental income
required:
- properties
- total_gross_income
- total_net_income
title: RealEstateIncome
IncomeDetails:
type: object
properties:
employment:
$ref: '#/components/schemas/EmploymentIncome'
description: Employment income details
capital:
$ref: '#/components/schemas/CapitalIncome'
description: Capital income details
capital_gains:
$ref: '#/components/schemas/CapitalGains'
description: Capital gains and losses details
business:
$ref: '#/components/schemas/BusinessIncome'
description: Business activity income details
real_estate:
$ref: '#/components/schemas/RealEstateIncome'
description: Real estate/rental income details
required:
- employment
- capital
- capital_gains
- business
- real_estate
title: IncomeDetails
DonationLine:
type: object
properties:
entity_id:
type: string
description: Identifier of the receiving entity (NIF/CIF)
entity_name:
type: string
description: Name of the receiving entity
donation_type:
type: string
description: Type of donation (e.g., Donativo)
amount:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Amount donated
is_recurring:
type: boolean
description: Whether the donation is recurring
taxpayer_id:
type: string
description: National identifier of the taxpayer for this line
required:
- entity_id
- entity_name
- amount
- is_recurring
- taxpayer_id
title: DonationLine
DeductionDetails:
type: object
properties:
donations:
type: array
items:
$ref: '#/components/schemas/DonationLine'
description: List of donations
total_donations:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Total donations
personal_allowance:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Personal tax-free allowance
family_allowance:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Family tax-free allowances (children, ascendants)
regional_deductions:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Total deductions applied at regional level
state_deductions:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Total deductions applied at state level
total_deductions:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Grand total of all deductions
required:
- donations
- total_donations
- personal_allowance
- family_allowance
- regional_deductions
- state_deductions
- total_deductions
title: DeductionDetails
RealEstateLoanLine:
type: object
properties:
loan_id:
type: string
description: Identifier of the loan
lender_id:
type: string
description: Identifier of the lender (NIF/CIF)
lender_name:
type: string
description: Name of the lender
participation:
type: string
format: number
description: Percentage of participation in the loan
amortized_capital:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Total amortized capital
interests:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Total interests paid
financial_expenses:
$ref: '#/components/schemas/CurrencyAmount-Input'
description: Total financial expenses
formalization_date:
type: string
format: date
description: Date the loan was formalized
taxpayer_id:
type: string
description: National identifier of the taxpayer for this line
required:
- loan_id
- lender_id
- lender_name
- amortized_capital
- interests
- financial_expenses
- taxpayer_id
title: RealEstateLoanLine
LiabilityDetails:
type: object
properties:
real_estate_loans:
type: array
items:
$ref: '#/components/schemas/RealEstateLoanLine'
default: []
description: List of real estate loans
title: LiabilityDetails
YearlyPersonalTaxSituationSchema:
type: object
properties:
product:
type: string
enum:
- tax_information
sub_family:
type: string
enum:
- tax_information:persons_yearly_fiscal_data
fetch_date:
type: string
format: datetime
description: Date this product was fetched
primary_taxpayer:
type: string
description: National identifier of the taxpayer
joint_taxpayers:
type: array
items:
type: string
description: List of national identifiers for joint taxpayers
address:
$ref: '#/components/schemas/AddressSchema'
description: Fiscal address for the exercise
address_reference:
type: string
description: Cadastral reference for the main home
country_code:
type: string
format: country
description: Country code for the tax declaration
currency:
type: string
format: currency
description: Currency for the tax declaration
tax_agency:
type: string
description: Tax agency for the tax declaration
fiscal_year_start:
type: string
format: date
description: Start date of the fiscal year
fiscal_year_end:
type: string
format: date
description: End date of the fiscal year
status:
$ref: '#/components/schemas/FiscalDataStatus'
description: Status of the fiscal data
filing_category:
$ref: '#/components/schemas/YearlyPersonalTaxSituationSchemaFilingCategory'
description: Category of the tax filing
taxable_base:
$ref: '#/components/schemas/CurrencyAmount-Output'
description: Total taxable base
total_tax_paid:
$ref: '#/components/schemas/CurrencyAmount-Output'
description: Total tax paid or withheld
final_tax_result:
$ref: '#/components/schemas/CurrencyAmount-Output'
description: Final tax result (to be paid or refunded)
income:
$ref: '#/components/schemas/IncomeDetails'
description: Detailed breakdown of income
deductions:
$ref: '#/components/schemas/DeductionDetails'
description: Detailed breakdown of deductions
liabilities:
$ref: '#/components/schemas/LiabilityDetails'
description: Detailed breakdown of liabilities
attachments:
type: array
items:
$ref: '#/components/schemas/FileAttachmentSchema'
default: []
description: List of attached supporting documents
required:
- product
- sub_family
- fetch_date
- primary_taxpayer
- address
- address_reference
- country_code
- currency
- tax_agency
- fiscal_year_start
- fiscal_year_end
- status
- filing_category
- taxable_base
- total_tax_paid
- final_tax_result
- income
- deductions
- liabilities
title: YearlyPersonalTaxSituationSchema
TaxesFamily:
type: object
properties:
individual_yearly:
type: array
items:
$ref: '#/components/schemas/YearlyPersonalTaxSituationSchema'
description: Yearly individual tax situations
title: TaxesFamily
PropertyOwnerSchema:
type: object
properties:
name:
type: string
description: Full name of the owner.
identifier:
type: string
description: Identification number of the owner.
percentage:
type: string
format: number
default: nan
description: Ownership percentage (e.g., 0.59).
required:
- name
title: PropertyOwnerSchema
CadastralDownloadInfoSchema:
type: object
properties:
cn:
type: string
description: Class of nature.
cp:
type: string
description: Province code.
cm:
type: string
description: Municipality code.
pc1:
type: string
description: Cadastral plot 1.
pc2:
type: string
description: Cadastral plot 2.
car:
type: string
description: Cargo/charge identifier.
cc1:
type: string
description: Control character 1.
cc2:
type: string
description: Control character 2.
cpo:
type: string
description: Postal code.
cpa:
type: string
description: Postal code area.
refCat:
type: string
description: Full cadastral reference.
title: CadastralDownloadInfoSchema
ESOwnedPropertySchema:
type: object
properties:
product:
type: string
enum:
- owned_property
sub_family:
type: string
enum:
- owned_property:es_owned_property
fetch_date:
type: string
format: datetime
description: Date this product was fetched
country:
type: string
format: country
description: Country of the property.
cadastral_reference:
type: string
description: Unique cadastral reference identifier.
address:
type: string
description: Full address of the property.
property_type:
type: string
description: Type of property (e.g., Urban, Rustic).
property_use:
type: string
description: Main use of the property (e.g., Residential).
assessment_year:
type: string
description: Year of the catastral assessment.
assessed_value:
$ref: '#/components/schemas/CurrencyAmount-Output'
description: Total assessed cadastral value.
land_value:
$ref: '#/components/schemas/CurrencyAmount-Output'
description: Assessed land value.
construction_value:
$ref: '#/components/schemas/CurrencyAmount-Output'
description: Assessed construction value.
owners:
type: array
items:
$ref: '#/components/schemas/PropertyOwnerSchema'
description: List of owners of the property.
cartography_link:
type: string
description: Link to the cartography map.
download_info:
$ref: '#/components/schemas/CadastralDownloadInfoSchema'
description: Internal metadata for downloading documents.
required:
- product
- sub_family
- fetch_date
- country
- owners
title: ESOwnedPropertySchema
PropertiesFamily:
type: object
properties:
es:
type: array
items:
$ref: '#/components/schemas/ESOwnedPropertySchema'
description: Officially owned properties
title: PropertiesFamily
EuCreditRegistryDataSchemaSubFamily:
type: string
enum:
- credit_registry_data:es_cirbe_detailed
- credit_registry_data:es_cirbe_aggregated
description: The sub-family specifying detailed or aggregated registry data.
title: EuCreditRegistryDataSchemaSubFamily
OperationSchema:
type: object
properties:
entity_name:
type:
- string
- 'null'
entity_code:
type:
- string
- 'null'
operation_code:
type:
- string
- 'null'
product_type:
type: string
intervention_nature:
type: string
collective_status:
type:
- string
- 'null'
participants_number:
type:
- integer
- 'null'
currency:
type: string
format: currency
maturity_type:
type:
- string
- 'null'
real_guarantee_type:
type:
- string
- 'null'
real_guarantee_coverage:
oneOf:
- $ref: '#/components/schemas/CurrencyAmount-Input'
- type: 'null'
personal_guarantee_type:
type:
- string
- 'null'
personal_guarantee_coverage:
oneOf:
- $ref: '#/components/schemas/CurrencyAmount-Input'
- type: 'null'
operation_status:
type:
- string
- 'null'
total_drawn:
$ref: '#/components/schemas/CurrencyAmount-Input'
overdue:
oneOf:
- $ref: '#/components/schemas/CurrencyAmount-Input'
- type: 'null'
arrears:
oneOf:
- $ref: '#/components/schemas/CurrencyAmount-Input'
- type: 'null'
risk_available:
oneOf:
- $ref: '#/components/schemas/CurrencyAmount-Input'
- type: 'null'
required:
- product_type
- intervention_nature
- currency
- total_drawn
title: OperationSchema
MinorRiskSchema:
type: object
properties:
entity_name:
type: string
entity_code:
type:
- string
- 'null'
limit_amount:
$ref: '#/components/schemas/CurrencyAmount-Input'
required:
- entity_name
- limit_amount
title: MinorRiskSchema
EUCreditRegistryDataSchema:
type: object
properties:
product:
type: string
enum:
- credit_registry_data
description: The product type identifier.
sub_family:
$ref: '#/components/schemas/EuCreditRegistryDataSchemaSubFamily'
description: The sub-family specifying detailed or aggregated registry data.
fetch_date:
type: string
format: datetime
description: Date this product was fetched.
country:
type: string
format: country
description: Country of the credit registry.
holder_code:
type:
- string
- 'null'
description: Identification code of the holder in the registry.
holder_name:
type: string
description: Full name or business name of the holder.
identifier:
oneOf:
- $ref: '#/components/schemas/IdentificationNumberSchema'
- type: 'null'
description: National identifier of the holder.
report_month:
type: string
description: Target month and year of the operation report in MM-YYYY format.
consultation_date:
type:
- string
- 'null'
format: datetime
description: Timestamp when the report was issued/consulted.
total_drawn:
$ref: '#/components/schemas/CurrencyAmount-Output'
description: Total active drawn risk amount in the system.
total_overdue:
$ref: '#/components/schemas/CurrencyAmount-Output'
description: Total risk amount that is overdue in the system.
total_arrears:
$ref: '#/components/schemas/CurrencyAmount-Output'
description: Total overdue interest and expenses in the system.
total_risk_available:
$ref: '#/components/schemas/CurrencyAmount-Output'
description: Total available risk amount in the system.
operations:
type: array
items:
$ref: '#/components/schemas/OperationSchema'
default: []
description: List of operations reported in the registry.
minor_risks:
type: array
items:
$ref: '#/components/schemas/MinorRiskSchema'
default: []
description: List of entities with accumulated risks below the threshold.
attachments:
type: array
items:
$ref: '#/components/schemas/FileAttachmentSchema'
default: []
description: List of attached original documents (e.g. PDF).
required:
- product
- sub_family
- fetch_date
- country
- holder_name
- report_month
title: EUCreditRegistryDataSchema
CreditFamily:
type: object
properties:
registry:
type: array
items:
$ref: '#/components/schemas/EUCreditRegistryDataSchema'
description: Credit registry data
title: CreditFamily
PublicGlobalPositionSchema:
type: object
properties:
customer:
$ref: '#/components/schemas/CustomerFamily'
description: Customer family
academic:
$ref: '#/components/schemas/AcademicFamily'
description: Academic family
driver:
$ref: '#/components/schemas/DriverFamily'
description: Driver & vehicles family
employment:
$ref: '#/components/schemas/EmploymentFamily'
description: Employment family
tax:
$ref: '#/components/schemas/TaxesFamily'
description: Tax family
properties:
$ref: '#/components/schemas/PropertiesFamily'
description: Properties family
credit:
$ref: '#/components/schemas/CreditFamily'
description: Credit registry family
title: PublicGlobalPositionSchema
FlowResultsSchema:
type: object
properties:
is_closed:
type: boolean
description: Indicates if the flow session has been finalized.
status_code:
$ref: '#/components/schemas/FlowResultsSchemaStatusCode'
description: The final execution status code of the session.
cursor:
$ref: '#/components/schemas/FlowResultsSchemaCursor'
description: The last screen of the widget experience where the user interacted.
connections:
type: object
additionalProperties:
type: string
format: engine-reference
description: >-
A mapping of internal connection identifiers to the engine
references executed.
consent:
$ref: '#/components/schemas/ConsentOutput'
description: >-
The structured consent audit trail and accepted document versions
signed by the user.
retrieved_features:
type: array
items:
$ref: '#/components/schemas/FlowResultsSchemaRetrievedFeaturesItems'
description: >-
The list of features successfully extracted from the official
portals during the session.
data:
$ref: '#/components/schemas/PublicGlobalPositionSchema'
description: >-
The retrieved public administration records, conforming to the
PublicGlobalPositionSchema.
required:
- is_closed
- status_code
- cursor
- connections
title: FlowResultsSchema
WebhookEndedErrorPayload:
type: object
properties:
user_feedback:
type: object
additionalProperties:
description: Any type
description: User cancellation feedback details.
system_feedback:
type: object
additionalProperties:
description: Any type
description: System failure context or details.
description: >-
Why a session ended without results: the user's cancellation feedback,
or the system's
failure details.
title: WebhookEndedErrorPayload
WebhookEndedPayloadData:
oneOf:
- $ref: '#/components/schemas/FlowResultsSchema'
- $ref: '#/components/schemas/WebhookEndedErrorPayload'
description: >-
Verification results payload.
- On success (COMPLETED):
* If an `aes_key` was provided during session creation, the results are delivered
encrypted. Please refer to the Payload Decryption section of the API introduction to
decrypt them into `FlowResultsSchema`.
* If no `aes_key` was specified, this field is not informed (null), and you must retrieve
the results manually using the session API.
- On cancellation or failure, it contains error/feedback details
conforming to
`WebhookEndedErrorPayload`.
title: WebhookEndedPayloadData
WebhookEndedPayload:
type: object
properties:
event_class:
type: string
enum:
- EsPublicAdministrationV1FlowEvent
description: >-
Payload class discriminator — always this value for Spain Public
Administration events.
app_id:
type: string
format: ObjectId
customer_id:
type: string
session_id:
type: string
format: ObjectId
producer:
type: string
enum:
- es-public-administration
description: The flow that produced the event.
event:
type: string
enum:
- es-public-administration:ended
description: 'The event type: `ended`.'
date:
type: string
format: datetime
status_code:
$ref: '#/components/schemas/WebhookEndedPayloadStatusCode'
description: >-
Base status codes for widget flows
Allowed values are:
- `READY`: The flow is waiting for an input
- `WAITING`: Flow is waiting for an external event
- `COMPLETED`: The flow has finalized successfully
- `FAILED`: The flow has failed
- `SYSTEM_CANCELLED`: The flow has ben cancelled by the system
- `CLIENT_CANCELLED`: The flow has been cancelled by the client
- `CUSTOMER_CANCELLED`: The flow has been cancelled by the customer
- `TIMED_OUT`: The flow has timed out
- `CONFIGURATION_ERROR`: The flow has been rejected due to a
configuration error
status_message:
type:
- string
- 'null'
data:
$ref: '#/components/schemas/WebhookEndedPayloadData'
description: >-
Verification results payload.
- On success (COMPLETED):
* If an `aes_key` was provided during session creation, the results are delivered
encrypted. Please refer to the Payload Decryption section of the API introduction to
decrypt them into `FlowResultsSchema`.
* If no `aes_key` was specified, this field is not informed (null), and you must retrieve
the results manually using the session API.
- On cancellation or failure, it contains error/feedback details
conforming to
`WebhookEndedErrorPayload`.
required:
- event_class
- app_id
- customer_id
- session_id
- producer
- event
- status_code
description: >-
Fired when the session finishes — successfully with the complete
results, or on
cancellation/failure with the reason.
title: WebhookEndedPayload
```