Labor Check
The person’s labor life with the Spanish Social Security (TGSS)
Where it lives: in the Spain Public Administration results, at data.employment.labor_check. APIs with dedicated per-product results endpoints return this model directly.
The labor check answers three questions about a person: who they have worked for and when, what they have contributed month by month, and what that means today — whether they are currently working, their current work statuses, and a guaranteed minimum net income floor. Use it to verify employment, gauge income stability and assess risk.
It arrives in the session results under data, and the official TGSS reports the data was read from travel as attachments when you ask for them, downloadable for your own records.
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.
The product type identifier. Always social_security for this product.
The sub-family identifier: social_security:spain_labor_check, the Spanish Social Security (TGSS) labor life
check.
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.
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.
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.
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.
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.
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.
Contribution-base history grouped per employer account, most recent first. Join each group to
its work relation through the ccc code.
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.
List of attached supporting documents (e.g. the original TGSS PDF reports this product was extracted from).
The holder
holder_name and identifier say whom the official reports are about, exactly as the reports print it: the holder’s name, and their DNI or NIE. The official reports are the two PDFs the Social Security issues — the work-life report and the contribution-base report. When the labor check is retrieved by connecting to the Social Security, both are read whether or not you ask for them as attachments: the feature’s work_life_report and contribution_base_report settings decide what is attached, never what is read. The holder fields record what the documents say; they do not verify your customer — comparing them with the identity you hold is your decision. The work-life report prints the given name first and the contribution-base report the surnames first: when both are read, holder_name is the work-life report’s, and when only one could be read, it is that one’s.
A labor check without holder_name needs a careful review
When both official reports are read, they must carry the same identity numbers, or neither is used. Their names are compared with tolerance, because each report prints them its own way — surnames first or last, abbreviated, without accents. When they still do not match, holder_name is not reported, while identifier is. In Direct Executions, the execution’s messages then carry a labor_check_holder_name_mismatch warning.
The Social Security may hold the name in two forms — after a legal change of name, for instance — or one of its records may carry an error. Either way, compare the name printed in the reports with your customer’s identity before you rely on this product — ask for them as attachments to have them at hand.
When identifier is not reported either, no report could be used — they were not available, could not be read, or did not agree on the holder’s identity numbers — or the person has never been registered with the Social Security. If the labor check was retrieved by connecting to the Social Security, the rest of its data then comes from the Social Security’s web pages, and leaving the reports out of the attachments is never the reason.
Work relations
One entry per period of the labor life, most recent first: employments, self-employment
stretches, and situations that count for Social Security without being a job (an ongoing
unemployment benefit, paid untaken vacations). The ccc employer account code is the join key
to the contribution history below.
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.
Activity start date — the date the TGSS counts contributed days from.
Display name of the relation: the employer's name for employees, the regime for self-employment, and the situation description for benefit periods.
Work type of this relation (e.g. employee, self_employed, unemployment_benefits).
Contract type as mapped from the TGSS classification; unknown when the source key has
no mapping.
Work schedule: full_time, part_time, or unknown.
Employer contribution account code (CCC) — the join key to contribution_base_by_company.
Absent for self-employment, which has no employer account.
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.
True while this relation is ongoing (it has no end date yet).
A relation’s social_security_days are the days the official report certifies, and they can be fewer than its dates span. A part-time relation counts its days at its coefficient; when the working hours changed during a relation, the report counts every one of them but prints only the last coefficient — so a relation that ended full-time can show no part_time_percentage and fewer days than its dates. Read the days as certified; never recompute them from the dates.
Contribution bases
The monthly contribution history, grouped per employer account — join each group to its work
relation through ccc. The flat contribution_base_history on the labor check is the same
months in one list, for date-keyed consumers.
The month-by-month contribution history of one employer account (or regime).
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.
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.
Each month carries its state and, when registered, the gross base:
One month of contribution: its state and, when registered, the gross base amount.
Last day of the contribution month — a convenience key for date-indexed consumers; year
and month carry the same information.
Contribution month (1-12).
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.
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.
True when the base is provisional and may still be regularized by the TGSS — typical for self-employed workers until the yearly settlement.
Income floor
The floor is a guaranteed minimum net income, never a salary estimate: deductions are estimated conservatively so the net stays a floor, and real net income can only be equal or higher. For self-employed workers it deliberately understates real income — combine it with other signals.
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.
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).
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.
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.
The gross monthly floor, annualized (x12).
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.
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.
Version of the floor derivation method. Bumped whenever the algorithm changes meaning — compare floors only within the same version.
Each company contributing to the computed floor appears with its own share — past employments are never listed here, so nothing in this list can be misread as a salary the person no longer earns:
One company's share of the income floor: the minimum net income it contributes.
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.
How this floor was derived (e.g. window_minimum: the minimum base over the trailing
window of fully certified months).
Employer contribution account code (CCC) of this company.
The certified GROSS monthly floor this company's net figure derives from — the minimum contribution base over the observation window.
The certified GROSS annual floor from this company (the gross monthly floor x12).
Number of certified months the floor is based on — the more months, the steadier the floor.