> This page is for Spain Public Administration Flow. > 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. # Data models A Spain Public Administration session reads what the administrations hold about your customer, and what it returns is their **public position**: the customer profile and one family per source you asked for — Social Security, the Banco de España, the DGT, the tax agency, the Cadastre, the education registries. A family you did not ask for is absent. These pages lay each model out flat, field by field, rendered from the live API specification. ## Where the data arrives The same models reach you by two routes: * **[Get Session Results](https://infonite.dev/flows/spain-public-administration/api-reference/spain-public-administration-api/sessions-results/flows-es-public-administration-v-1-session-results)** — whenever you ask, behind your application secret. * **The webhooks** — `es-public-administration:ended` when the session ends, and `es-public-administration:partial` with what has arrived so far if your customer leaves while a source is still answering. Both are encrypted with the session's `aes_key`; without one, they carry no data and tell you to fetch it. [Webhooks](/flows/spain-public-administration/webhooks) has the details. ## The public position ### Schema (`PublicGlobalPositionSchema`) ```yaml components: schemas: 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 - 'null' 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 - 'null' description: Free label for the address (e.g. `Headquarter`, `Domicilio`). street: type: - string - 'null' description: 'Street line: name and number.' street_extra: type: - string - 'null' description: 'Second street line: floor, suite, staircase, apartment...' municipality: type: - string - 'null' description: Municipality the address belongs to. city: type: - string - 'null' description: City or town. state: type: - string - 'null' description: State or province code. country: type: - string - 'null' format: country description: Country, as a two-letter ISO code. zip_code: type: - string - 'null' 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 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 - attachment:person-certified-photo 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: object-id description: >- Attachment identifier — what the attachments endpoint of the API that returned the result takes to download the file. 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 with `id`, through the attachments endpoint of the API that returned the result. title: FileAttachmentSchema 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 minimum: 0 maximum: 20 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. attachments: type: array items: $ref: '#/components/schemas/FileAttachmentSchema' default: [] description: >- Supporting documents of this driver record. With the DGT's own connection, the person's photograph as the DGT holds it (`attachment:person-certified-photo`), when they are registered there — that is, when they hold a driving licence. 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 VehicleIncidentFlag: type: string enum: - seizure - seal - financing_charge - temporary_deregistration - permanent_deregistration - theft_deregistration - transfer_deregistration - inspection_expired description: >- The incidents that make a vehicle a risk to buy, finance or insure: what its registry flags on it, and an inspection that has expired. title: VehicleIncidentFlag 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. Always `true` when `flags` names any — an expired inspection included. flags: type: array items: $ref: '#/components/schemas/VehicleIncidentFlag' description: >- The incidents that make this vehicle a risk to buy, finance or insure: what the registry flags on it — a seizure, a seal, a financing charge, a deregistration — and `inspection_expired` when its inspection (ITV) had expired at the time of the report. Each code appears once, in no particular order. Absent when the source does not say; empty when it says there are none. A vehicle can have incidents no flag names, so an empty list does not mean `has_incidents` is `false`. required: - report_date - has_incidents description: >- Whether the vehicle has incidents, and which ones. Present only when `vehicles_data` is requested with `simple_vehicle_report: true` in its configurations. 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: >- **Deprecated: read `last_registration_date` and `first_registration_date` instead.** A registration date as the source reports it, which is not always the same registration: the one in `country` when the source gives it, the vehicle's first registration when the source gives only that one. Still present, and filled as before. deprecated: true first_registration_date: type: string format: date description: >- Date the vehicle was registered for the first time, in any country: for an imported vehicle, its original registration abroad. It belongs to the vehicle, not to its owner — a vehicle bought second hand keeps it — and it is the date that tells the vehicle's age. Equal to `last_registration_date` when the vehicle was first registered in `country`. Absent when the source consulted does not give it — and then `last_registration_date` may well be the first registration too: the absence only says the source does not tell. last_registration_date: type: string format: date description: >- Date the vehicle was registered in `country`: the registration in force. Equal to `first_registration_date` for a vehicle first registered there, later for one registered abroad before. It belongs to the vehicle, not to its owner — a change of owner leaves it as it was. Absent when the source consulted does not give it — and then `first_registration_date` may well be the registration in `country` too: the absence only says the source does not tell. inspection_expiry_date: type: string format: date description: Expiry date of the vehicle inspection. 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 minimum: 0 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 list 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 — e.g. between contracts, a scheduled future hire or an ongoing unemployment benefit; the current floor is zero), `insufficient_data` (working, but not enough certified months yet to measure a floor), 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 observed_months: type: integer default: 0 description: >- Number of months the floor was measured over. A month only partly worked (a start after the 1st, an end before the month's last day) is left out once at least two full months exist, so its prorated pay never passes for a monthly income. Fewer than 3 means the floor rests on little evidence — typically a recent hire. 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 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. holder_name: type: string description: >- The holder's full name, as printed on the official Social Security reports (the PDFs). ⚠️ **When it is not reported, review this product carefully before you rely on it**: the two reports print different names for the same holder, or no report could be used. identifier: $ref: '#/components/schemas/IdentificationNumberSchema' description: >- The holder's identity document (DNI or NIE), as printed on the official reports; when both are read, they must agree on it. Not reported when no report could be used (not available, not readable, or disagreeing on the identity numbers). When the labor check is retrieved by connecting to the Social Security, both reports are read whether or not you ask for them as attachments, and without a usable one the rest of the data may come from its web pages instead. currently_active: type: boolean description: >- True when the person is actually WORKING right now: at least one entry in `current_work_types` is real work (`employee`, `self_employed` or `public_employee`). Receiving an unemployment benefit is not active employment. Neither is a hire scheduled for a future date: Social Security reports such a person as registered ("alta programada"), but this field stays `false` until the job actually starts. `false` means the person's current situation is known and includes no active job; `null` means the work history could not be recovered, so nothing is claimed either way. The value is deliberately cautious — it is designed for risk decisions — so only clearly identified work counts: in the rare case where an ongoing relation cannot be classified you get `false` plus a `current_work_type_unknown` warning, never an optimistic `true`. 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: ongoing relations first, then the finished ones from the most recently ended backwards — 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. deprecated: true 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`, and the holder they name in `holder_name` and `identifier`. 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: the gross amount, 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, when applicable regime: type: string description: Pension regime amounts: $ref: '#/components/schemas/PublicPensionAmountsSchema' description: Amounts of the pension, when 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 additionalProperties: type: string title: _CurrencyAmount-Output CurrencyAmountInputCurrency: oneOf: - type: string enum: - '***' - type: string format: currency 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: 'The owner''s share, as a fraction: 0.59 is 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 cadastral value: the value for tax purposes, usually below the market price. 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: >- Every holder of the property, the person included, each with their share. 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: >- Which report this is: detailed or aggregated — what the document turned out to be, not what was requested. A holder with nothing declared to the register only ever gets the aggregated report. title: EuCreditRegistryDataSchemaSubFamily CreditRegistryProductType: type: string enum: - securities_lending - trade_credit_with_recourse - trade_credit_without_recourse - trade_receivables - financial_credit - financial_lease - reverse_repurchase_agreement - debt_securities - financial_guarantee - forward_deposit - non_financial_guarantee - irrevocable_documentary_credit - available_in_other_commitments - overdraft - credit_card_debt - deposit - revolving_credit - credit_line - other_loans description: Type of product or operation ("Tipo de producto/operación"). title: CreditRegistryProductType CreditRegistryInterventionNature: type: string enum: - direct_holder - guarantor - bill_signatory description: >- How the report's holder takes part in the operation ("Naturaleza de la intervención"). title: CreditRegistryInterventionNature CreditRegistryJointLiability: type: string enum: - joint_and_several - collective - not_joint_and_several description: >- Whether the holder answers for the operation together with others ("Solidario/colectivo"). A CIR report prints nothing when neither applies; that is "not stated", not a member. title: CreditRegistryJointLiability CreditRegistryResidualMaturity: type: string enum: - up_to_three_months - three_months_to_one_year - one_to_five_years - over_five_years - indeterminate description: >- Time left between the report's date and the operation's maturity ("Plazo residual"). title: CreditRegistryResidualMaturity CreditRegistryRealGuarantee: type: string enum: - none - financial_assets_pledge - real_estate_mortgage - other_real_guarantee - life_insurance_pledge - other_physical_collateral - credit_derivatives - financial_guarantee_other_than_credit_derivatives - other_protection - residential_real_estate - offices_and_commercial_premises - commercial_real_estate - debt_securities - gold - cash_and_deposits - loans - trade_receivables - equity_and_investment_fund_shares description: >- Type of the principal real (collateral) guarantee ("Tipo de garantía real principal"). title: CreditRegistryRealGuarantee CreditRegistryGuaranteeCoverage: type: string enum: - total - partial description: >- How much of the risk (drawn and available) the principal guarantee covers. title: CreditRegistryGuaranteeCoverage CreditRegistryPersonalGuarantee: type: string enum: - none - public_administration - other_personal_guarantee - reporting_entity - public_credit_insurer - unspecified description: >- Type of the principal personal guarantee, beyond the direct holders' own ("Tipo de garantía personal principal"). title: CreditRegistryPersonalGuarantee CreditRegistryOperationSituation: type: string enum: - standard - restructured_under_rdl_6_2012 - refinanced_or_restructured - creditors_agreement - default_90_days_to_4_years - default_over_4_years - written_off description: Special situation of the operation ("Situación de la operación"). title: CreditRegistryOperationSituation OperationSchema: type: object properties: entity_name: type: - string - 'null' description: Name of the reporting entity. Detailed reports only. entity_code: type: - string - 'null' description: >- Bank of Spain code of the reporting entity (e.g. `0182`). Detailed reports only. operation_code: type: - string - 'null' description: >- Unique code of the operation, as the entity reports it. Detailed reports only. product_type: oneOf: - $ref: '#/components/schemas/CreditRegistryProductType' - type: 'null' description: >- Type of product: a loan, a lease, a guarantee… Empty only if the code is new to us; see `product_type_code`. product_type_code: type: - string - 'null' description: Product code as printed (e.g. `V32`). intervention_nature: oneOf: - $ref: '#/components/schemas/CreditRegistryInterventionNature' - type: 'null' description: >- How the holder takes part: as the direct obligor, or as a guarantor of someone else's operation. intervention_nature_code: type: - string - 'null' description: Intervention code as printed (e.g. `T11`). collective_status: oneOf: - $ref: '#/components/schemas/CreditRegistryJointLiability' - type: 'null' description: >- Whether the holder answers jointly and severally, or collectively, with others. Empty when neither. collective_status_code: type: - string - 'null' description: Code as printed (e.g. `T33`). participants_number: type: - integer - 'null' minimum: 1 description: >- Number of participants in a joint and several or collective operation. currency: type: string format: currency description: >- Currency the operation is contracted in. `XXX` means "other currencies". maturity_type: oneOf: - $ref: '#/components/schemas/CreditRegistryResidualMaturity' - type: 'null' description: Time left to maturity at the report's date. maturity_type_code: type: - string - 'null' description: Maturity code as printed (e.g. `L08`). real_guarantee_type: oneOf: - $ref: '#/components/schemas/CreditRegistryRealGuarantee' - type: 'null' description: 'Main real guarantee (collateral): a mortgage, a pledge… or `none`.' real_guarantee_type_code: type: - string - 'null' description: Code as printed (e.g. `G19`). real_guarantee_coverage: oneOf: - $ref: '#/components/schemas/CreditRegistryGuaranteeCoverage' - type: 'null' description: >- Whether the real guarantee covers all of the risk or part of it. Empty when there is no guarantee. real_guarantee_coverage_code: type: - string - 'null' description: Code as printed (e.g. `E14`). personal_guarantee_type: oneOf: - $ref: '#/components/schemas/CreditRegistryPersonalGuarantee' - type: 'null' description: Main personal guarantee beyond the holders' own, or `none`. personal_guarantee_type_code: type: - string - 'null' description: >- Code as printed (e.g. `G10`). Empty when there is no personal guarantee. personal_guarantee_coverage: oneOf: - $ref: '#/components/schemas/CreditRegistryGuaranteeCoverage' - type: 'null' description: Whether the personal guarantee covers all of the risk or part of it. personal_guarantee_coverage_code: type: - string - 'null' description: Code as printed (e.g. `E15`). operation_status: oneOf: - $ref: '#/components/schemas/CreditRegistryOperationSituation' - type: 'null' description: >- Special situation of the operation: refinanced, in default, written off… `standard` when none applies. operation_status_code: type: - string - 'null' description: >- Code as printed (e.g. `I19`). Empty when no special situation applies. total_drawn: $ref: '#/components/schemas/CurrencyAmountSchema' description: >- Amount drawn, overdue amounts included. In an aggregated report, exact to the thousand. overdue: $ref: '#/components/schemas/CurrencyAmountSchema' description: >- Part of the drawn amount that is overdue, with a first default over 90 days old. arrears: $ref: '#/components/schemas/CurrencyAmountSchema' description: >- Part of the overdue amount that is default interest and enforceable expenses. risk_available: $ref: '#/components/schemas/CurrencyAmountSchema' description: Amount still available to draw. required: - currency title: OperationSchema MinorRiskSchema: type: object properties: entity_name: type: string description: >- Name of an entity whose accumulated risk with the holder is below the reporting threshold. entity_code: type: - string - 'null' description: Bank of Spain code of the entity. limit_amount: $ref: '#/components/schemas/CurrencyAmountSchema' description: >- The reporting threshold: 1,000 EUR from period 01-2021, 9,000 EUR before. required: - entity_name 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: >- Which report this is: detailed or aggregated — what the document turned out to be, not what was requested. A holder with nothing declared to the register only ever gets the aggregated report. 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 description: >- The holder's code exactly as the report prints it (e.g. `ES44444444A`). Not reported when the report could not be read. holder_name: type: string description: >- Full name or business name of the holder, as the report prints it. Not reported when the report could not be read: the attached report is then the only reference. identifier: $ref: '#/components/schemas/IdentificationNumberSchema' description: >- The holder's national identifier, from the report's holder code. Not reported when the report could not be read. report_month: type: string description: Period the operations correspond to, `MM-YYYY`. consultation_date: type: - string - 'null' format: datetime description: When the register's data was taken, as the report states it. total_drawn: $ref: '#/components/schemas/CurrencyAmountSchema' description: >- Total drawn across every operation in the system. In an aggregated report, exact to the thousand. total_overdue: $ref: '#/components/schemas/CurrencyAmountSchema' description: Total overdue across every operation in the system. total_arrears: $ref: '#/components/schemas/CurrencyAmountSchema' description: Total default interest and enforceable expenses in the system. total_risk_available: $ref: '#/components/schemas/CurrencyAmountSchema' description: Total still available to draw in the system. operations: type: array items: $ref: '#/components/schemas/OperationSchema' default: [] description: >- The operations: one per operation in a detailed report, one per group in an aggregated one. minor_risks: type: array items: $ref: '#/components/schemas/MinorRiskSchema' default: [] description: >- Entities whose accumulated risk is below the reporting threshold. Detailed reports only. attachments: type: array items: $ref: '#/components/schemas/FileAttachmentSchema' default: [] description: The original report (PDF). required: - product - sub_family - fetch_date - country - report_month description: >- The holder's risk position at a central credit register: in Spain, the Bank of Spain's CIRBE report, detailed (one row per operation and entity) or aggregated (operations grouped, no entities). Every key the register prints comes twice: as its meaning (an enum, the same whatever the report's period) and as the printed code (the `*_code` fields). Every amount is always present. One the report did not give — when the report could not be read — comes with currency `***` and amount `NaN`: unknown, never zero. 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 ``` #### [Customer profile](/flows/spain-public-administration/data-models/customer-profile) Your customer's identity as the administration holds it. #### [Labor Check](/flows/spain-public-administration/data-models/labor-check) Their working life with the Spanish Social Security (TGSS). #### [Public Pensions](/flows/spain-public-administration/data-models/public-pensions) The public pensions they receive from the Spanish Social Security. #### [Credit Registry](/flows/spain-public-administration/data-models/credit-registry) Their risk position at the Banco de España's credit registry (CIRBE). #### [Taxes](/flows/spain-public-administration/data-models/taxes) Their yearly fiscal data and income-tax return, from the tax agency (AEAT). #### [Properties](/flows/spain-public-administration/data-models/properties) Real estate registered to them in the Spanish Cadastre. #### [Driver](/flows/spain-public-administration/data-models/driver) Their driving record, from the traffic authority (DGT). #### [Vehicles](/flows/spain-public-administration/data-models/vehicles) The vehicles registered to them, from the traffic authority (DGT). #### [Academic Records](/flows/spain-public-administration/data-models/academic) Their official degrees and qualifications, from the Spanish registries. #### [Attachments](/flows/spain-public-administration/data-models/attachments) The official documents behind the data, downloadable for your records. ## The session envelope The position travels as `data` inside the session results — the same object the `partial` and `ended` webhooks deliver — beside the `consent` your customer gave and the `messages` the session raised: ### Schema (`FlowResultsSchema`) ```yaml components: schemas: FlowStatusCode: type: string enum: - READY - WAITING - COMPLETED - FAILED - SYSTEM_CANCELLED - CLIENT_CANCELLED - CUSTOMER_CANCELLED - TIMED_OUT - CONFIGURATION_ERROR description: Describes the status of a flow. title: FlowStatusCode 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 signed the document. Absent on a document that was only read: mandatory reading keeps the version and the hash of the text the user read to its end, and nothing else — the consent's own date is when it was accepted. 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 - 'null' 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 - 'null' description: Free label for the address (e.g. `Headquarter`, `Domicilio`). street: type: - string - 'null' description: 'Street line: name and number.' street_extra: type: - string - 'null' description: 'Second street line: floor, suite, staircase, apartment...' municipality: type: - string - 'null' description: Municipality the address belongs to. city: type: - string - 'null' description: City or town. state: type: - string - 'null' description: State or province code. country: type: - string - 'null' format: country description: Country, as a two-letter ISO code. zip_code: type: - string - 'null' 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 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 - attachment:person-certified-photo 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: object-id description: >- Attachment identifier — what the attachments endpoint of the API that returned the result takes to download the file. 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 with `id`, through the attachments endpoint of the API that returned the result. title: FileAttachmentSchema 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 minimum: 0 maximum: 20 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. attachments: type: array items: $ref: '#/components/schemas/FileAttachmentSchema' default: [] description: >- Supporting documents of this driver record. With the DGT's own connection, the person's photograph as the DGT holds it (`attachment:person-certified-photo`), when they are registered there — that is, when they hold a driving licence. 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 VehicleIncidentFlag: type: string enum: - seizure - seal - financing_charge - temporary_deregistration - permanent_deregistration - theft_deregistration - transfer_deregistration - inspection_expired description: >- The incidents that make a vehicle a risk to buy, finance or insure: what its registry flags on it, and an inspection that has expired. title: VehicleIncidentFlag 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. Always `true` when `flags` names any — an expired inspection included. flags: type: array items: $ref: '#/components/schemas/VehicleIncidentFlag' description: >- The incidents that make this vehicle a risk to buy, finance or insure: what the registry flags on it — a seizure, a seal, a financing charge, a deregistration — and `inspection_expired` when its inspection (ITV) had expired at the time of the report. Each code appears once, in no particular order. Absent when the source does not say; empty when it says there are none. A vehicle can have incidents no flag names, so an empty list does not mean `has_incidents` is `false`. required: - report_date - has_incidents description: >- Whether the vehicle has incidents, and which ones. Present only when `vehicles_data` is requested with `simple_vehicle_report: true` in its configurations. 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: >- **Deprecated: read `last_registration_date` and `first_registration_date` instead.** A registration date as the source reports it, which is not always the same registration: the one in `country` when the source gives it, the vehicle's first registration when the source gives only that one. Still present, and filled as before. deprecated: true first_registration_date: type: string format: date description: >- Date the vehicle was registered for the first time, in any country: for an imported vehicle, its original registration abroad. It belongs to the vehicle, not to its owner — a vehicle bought second hand keeps it — and it is the date that tells the vehicle's age. Equal to `last_registration_date` when the vehicle was first registered in `country`. Absent when the source consulted does not give it — and then `last_registration_date` may well be the first registration too: the absence only says the source does not tell. last_registration_date: type: string format: date description: >- Date the vehicle was registered in `country`: the registration in force. Equal to `first_registration_date` for a vehicle first registered there, later for one registered abroad before. It belongs to the vehicle, not to its owner — a change of owner leaves it as it was. Absent when the source consulted does not give it — and then `first_registration_date` may well be the registration in `country` too: the absence only says the source does not tell. inspection_expiry_date: type: string format: date description: Expiry date of the vehicle inspection. 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 minimum: 0 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 list 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 — e.g. between contracts, a scheduled future hire or an ongoing unemployment benefit; the current floor is zero), `insufficient_data` (working, but not enough certified months yet to measure a floor), 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 observed_months: type: integer default: 0 description: >- Number of months the floor was measured over. A month only partly worked (a start after the 1st, an end before the month's last day) is left out once at least two full months exist, so its prorated pay never passes for a monthly income. Fewer than 3 means the floor rests on little evidence — typically a recent hire. 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 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. holder_name: type: string description: >- The holder's full name, as printed on the official Social Security reports (the PDFs). ⚠️ **When it is not reported, review this product carefully before you rely on it**: the two reports print different names for the same holder, or no report could be used. identifier: $ref: '#/components/schemas/IdentificationNumberSchema' description: >- The holder's identity document (DNI or NIE), as printed on the official reports; when both are read, they must agree on it. Not reported when no report could be used (not available, not readable, or disagreeing on the identity numbers). When the labor check is retrieved by connecting to the Social Security, both reports are read whether or not you ask for them as attachments, and without a usable one the rest of the data may come from its web pages instead. currently_active: type: boolean description: >- True when the person is actually WORKING right now: at least one entry in `current_work_types` is real work (`employee`, `self_employed` or `public_employee`). Receiving an unemployment benefit is not active employment. Neither is a hire scheduled for a future date: Social Security reports such a person as registered ("alta programada"), but this field stays `false` until the job actually starts. `false` means the person's current situation is known and includes no active job; `null` means the work history could not be recovered, so nothing is claimed either way. The value is deliberately cautious — it is designed for risk decisions — so only clearly identified work counts: in the rare case where an ongoing relation cannot be classified you get `false` plus a `current_work_type_unknown` warning, never an optimistic `true`. 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: ongoing relations first, then the finished ones from the most recently ended backwards — 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. deprecated: true 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`, and the holder they name in `holder_name` and `identifier`. 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: the gross amount, 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, when applicable regime: type: string description: Pension regime amounts: $ref: '#/components/schemas/PublicPensionAmountsSchema' description: Amounts of the pension, when 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 additionalProperties: type: string title: _CurrencyAmount-Output CurrencyAmountInputCurrency: oneOf: - type: string enum: - '***' - type: string format: currency 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: 'The owner''s share, as a fraction: 0.59 is 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 cadastral value: the value for tax purposes, usually below the market price. 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: >- Every holder of the property, the person included, each with their share. 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: >- Which report this is: detailed or aggregated — what the document turned out to be, not what was requested. A holder with nothing declared to the register only ever gets the aggregated report. title: EuCreditRegistryDataSchemaSubFamily CreditRegistryProductType: type: string enum: - securities_lending - trade_credit_with_recourse - trade_credit_without_recourse - trade_receivables - financial_credit - financial_lease - reverse_repurchase_agreement - debt_securities - financial_guarantee - forward_deposit - non_financial_guarantee - irrevocable_documentary_credit - available_in_other_commitments - overdraft - credit_card_debt - deposit - revolving_credit - credit_line - other_loans description: Type of product or operation ("Tipo de producto/operación"). title: CreditRegistryProductType CreditRegistryInterventionNature: type: string enum: - direct_holder - guarantor - bill_signatory description: >- How the report's holder takes part in the operation ("Naturaleza de la intervención"). title: CreditRegistryInterventionNature CreditRegistryJointLiability: type: string enum: - joint_and_several - collective - not_joint_and_several description: >- Whether the holder answers for the operation together with others ("Solidario/colectivo"). A CIR report prints nothing when neither applies; that is "not stated", not a member. title: CreditRegistryJointLiability CreditRegistryResidualMaturity: type: string enum: - up_to_three_months - three_months_to_one_year - one_to_five_years - over_five_years - indeterminate description: >- Time left between the report's date and the operation's maturity ("Plazo residual"). title: CreditRegistryResidualMaturity CreditRegistryRealGuarantee: type: string enum: - none - financial_assets_pledge - real_estate_mortgage - other_real_guarantee - life_insurance_pledge - other_physical_collateral - credit_derivatives - financial_guarantee_other_than_credit_derivatives - other_protection - residential_real_estate - offices_and_commercial_premises - commercial_real_estate - debt_securities - gold - cash_and_deposits - loans - trade_receivables - equity_and_investment_fund_shares description: >- Type of the principal real (collateral) guarantee ("Tipo de garantía real principal"). title: CreditRegistryRealGuarantee CreditRegistryGuaranteeCoverage: type: string enum: - total - partial description: >- How much of the risk (drawn and available) the principal guarantee covers. title: CreditRegistryGuaranteeCoverage CreditRegistryPersonalGuarantee: type: string enum: - none - public_administration - other_personal_guarantee - reporting_entity - public_credit_insurer - unspecified description: >- Type of the principal personal guarantee, beyond the direct holders' own ("Tipo de garantía personal principal"). title: CreditRegistryPersonalGuarantee CreditRegistryOperationSituation: type: string enum: - standard - restructured_under_rdl_6_2012 - refinanced_or_restructured - creditors_agreement - default_90_days_to_4_years - default_over_4_years - written_off description: Special situation of the operation ("Situación de la operación"). title: CreditRegistryOperationSituation OperationSchema: type: object properties: entity_name: type: - string - 'null' description: Name of the reporting entity. Detailed reports only. entity_code: type: - string - 'null' description: >- Bank of Spain code of the reporting entity (e.g. `0182`). Detailed reports only. operation_code: type: - string - 'null' description: >- Unique code of the operation, as the entity reports it. Detailed reports only. product_type: oneOf: - $ref: '#/components/schemas/CreditRegistryProductType' - type: 'null' description: >- Type of product: a loan, a lease, a guarantee… Empty only if the code is new to us; see `product_type_code`. product_type_code: type: - string - 'null' description: Product code as printed (e.g. `V32`). intervention_nature: oneOf: - $ref: '#/components/schemas/CreditRegistryInterventionNature' - type: 'null' description: >- How the holder takes part: as the direct obligor, or as a guarantor of someone else's operation. intervention_nature_code: type: - string - 'null' description: Intervention code as printed (e.g. `T11`). collective_status: oneOf: - $ref: '#/components/schemas/CreditRegistryJointLiability' - type: 'null' description: >- Whether the holder answers jointly and severally, or collectively, with others. Empty when neither. collective_status_code: type: - string - 'null' description: Code as printed (e.g. `T33`). participants_number: type: - integer - 'null' minimum: 1 description: >- Number of participants in a joint and several or collective operation. currency: type: string format: currency description: >- Currency the operation is contracted in. `XXX` means "other currencies". maturity_type: oneOf: - $ref: '#/components/schemas/CreditRegistryResidualMaturity' - type: 'null' description: Time left to maturity at the report's date. maturity_type_code: type: - string - 'null' description: Maturity code as printed (e.g. `L08`). real_guarantee_type: oneOf: - $ref: '#/components/schemas/CreditRegistryRealGuarantee' - type: 'null' description: 'Main real guarantee (collateral): a mortgage, a pledge… or `none`.' real_guarantee_type_code: type: - string - 'null' description: Code as printed (e.g. `G19`). real_guarantee_coverage: oneOf: - $ref: '#/components/schemas/CreditRegistryGuaranteeCoverage' - type: 'null' description: >- Whether the real guarantee covers all of the risk or part of it. Empty when there is no guarantee. real_guarantee_coverage_code: type: - string - 'null' description: Code as printed (e.g. `E14`). personal_guarantee_type: oneOf: - $ref: '#/components/schemas/CreditRegistryPersonalGuarantee' - type: 'null' description: Main personal guarantee beyond the holders' own, or `none`. personal_guarantee_type_code: type: - string - 'null' description: >- Code as printed (e.g. `G10`). Empty when there is no personal guarantee. personal_guarantee_coverage: oneOf: - $ref: '#/components/schemas/CreditRegistryGuaranteeCoverage' - type: 'null' description: Whether the personal guarantee covers all of the risk or part of it. personal_guarantee_coverage_code: type: - string - 'null' description: Code as printed (e.g. `E15`). operation_status: oneOf: - $ref: '#/components/schemas/CreditRegistryOperationSituation' - type: 'null' description: >- Special situation of the operation: refinanced, in default, written off… `standard` when none applies. operation_status_code: type: - string - 'null' description: >- Code as printed (e.g. `I19`). Empty when no special situation applies. total_drawn: $ref: '#/components/schemas/CurrencyAmountSchema' description: >- Amount drawn, overdue amounts included. In an aggregated report, exact to the thousand. overdue: $ref: '#/components/schemas/CurrencyAmountSchema' description: >- Part of the drawn amount that is overdue, with a first default over 90 days old. arrears: $ref: '#/components/schemas/CurrencyAmountSchema' description: >- Part of the overdue amount that is default interest and enforceable expenses. risk_available: $ref: '#/components/schemas/CurrencyAmountSchema' description: Amount still available to draw. required: - currency title: OperationSchema MinorRiskSchema: type: object properties: entity_name: type: string description: >- Name of an entity whose accumulated risk with the holder is below the reporting threshold. entity_code: type: - string - 'null' description: Bank of Spain code of the entity. limit_amount: $ref: '#/components/schemas/CurrencyAmountSchema' description: >- The reporting threshold: 1,000 EUR from period 01-2021, 9,000 EUR before. required: - entity_name 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: >- Which report this is: detailed or aggregated — what the document turned out to be, not what was requested. A holder with nothing declared to the register only ever gets the aggregated report. 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 description: >- The holder's code exactly as the report prints it (e.g. `ES44444444A`). Not reported when the report could not be read. holder_name: type: string description: >- Full name or business name of the holder, as the report prints it. Not reported when the report could not be read: the attached report is then the only reference. identifier: $ref: '#/components/schemas/IdentificationNumberSchema' description: >- The holder's national identifier, from the report's holder code. Not reported when the report could not be read. report_month: type: string description: Period the operations correspond to, `MM-YYYY`. consultation_date: type: - string - 'null' format: datetime description: When the register's data was taken, as the report states it. total_drawn: $ref: '#/components/schemas/CurrencyAmountSchema' description: >- Total drawn across every operation in the system. In an aggregated report, exact to the thousand. total_overdue: $ref: '#/components/schemas/CurrencyAmountSchema' description: Total overdue across every operation in the system. total_arrears: $ref: '#/components/schemas/CurrencyAmountSchema' description: Total default interest and enforceable expenses in the system. total_risk_available: $ref: '#/components/schemas/CurrencyAmountSchema' description: Total still available to draw in the system. operations: type: array items: $ref: '#/components/schemas/OperationSchema' default: [] description: >- The operations: one per operation in a detailed report, one per group in an aggregated one. minor_risks: type: array items: $ref: '#/components/schemas/MinorRiskSchema' default: [] description: >- Entities whose accumulated risk is below the reporting threshold. Detailed reports only. attachments: type: array items: $ref: '#/components/schemas/FileAttachmentSchema' default: [] description: The original report (PDF). required: - product - sub_family - fetch_date - country - report_month description: >- The holder's risk position at a central credit register: in Spain, the Bank of Spain's CIRBE report, detailed (one row per operation and entity) or aggregated (operations grouped, no entities). Every key the register prints comes twice: as its meaning (an enum, the same whatever the report's period) and as the printed code (the `*_code` fields). Every amount is always present. One the report did not give — when the report could not be read — comes with currency `***` and amount `NaN`: unknown, never zero. 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 SessionMessageType: type: string enum: - error - warning - info - flag description: >- What a message attached to a SESSION is — a flow today, an execution tomorrow. The vocabulary of the standalone message models (`ISessionMessage` and its concrete documents), which is why it is not the legacy `MessageType` right below: that one is an `IShortEnum` whose numeric codes were persisted inside execution states, and no new model uses that form. The two overlap in three values on purpose — the day the engine messages move to this paradigm, `error`/`warning`/`info` translate by name. title: SessionMessageType MessageOutputLocationItems: oneOf: - type: string - type: integer title: MessageOutputLocationItems MessageOutput: type: object properties: type: $ref: '#/components/schemas/SessionMessageType' description: >- The kind of message: `error`, `warning`, `flag` or `info`. A `flag` is the one raised for you to act on rather than for us: nothing failed on our side and the session still found something that deserves a decision. message_id: type: string description: >- The stable identifier of the SITUATION, such as `profile_identity_mismatch`. Automate on this value: the wording of `message` may change without the situation becoming a different one. location: type: array items: $ref: '#/components/schemas/MessageOutputLocationItems' default: [] description: >- Where in this results document the message applies, as a `loc` list — the same shape as the `loc` of a validation error, with strings for fields and integers for array positions (`["data", "driver", "vehicles", 0, "license_plate"]`). An empty list means the message is about the session as a whole. message: type: string description: >- A human-readable description of the situation, when there is one to add. date_created: type: string format: datetime description: When the situation was first detected during the session. required: - type - message_id - date_created description: Something the session has to say about itself or about what it read. title: MessageOutput FlowResultsSchema: type: object properties: is_closed: type: boolean description: Indicates if the flow session has been finalized. status_code: $ref: '#/components/schemas/FlowStatusCode' 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. messages: type: array items: $ref: '#/components/schemas/MessageOutput' default: [] description: >- What the session has to say about itself and about the data it read, oldest first. Most sessions say nothing and the list is empty. When it is not, each entry is a situation that was detected while the session ran: an `error` or a `warning` about a read, an `info` note, or a `flag` — the type raised for you. A flag never means something of ours failed; it means the session found something worth a decision on your side, and `location` points at the part of this document it is about. A situation is reported ONCE however many times it occurred, so this list is a set of facts and not a log: automate on `message_id`, which is stable, and treat `message` as text for a person. required: - is_closed - status_code - cursor - connections title: FlowResultsSchema ```