Provero ONS Lead Validator API
Validate leads using ONS Census 2021 tenure data. Flags leads where demographic data may not match purchasing intent.
API Documentation
Overview
The ONS Lead Validator API validates leads using Census 2021 tenure data at LSOA-level precision (~35,000 areas).
Endpoints
/api/healthHealth check endpoint
/api/validateValidate a single lead
Risk-driving demographics (occupation, NS-SEC, household composition, car availability, deprivation, qualifications) are always fetched and used for scoring.
Optional: commitmentTier (tier1|tier2|tier3|tier4|tier5|tier6) — omit to receive scores for all six tiers in tierRisks; address (property details), applicantAge (integer 0–120) or dob (YYYY-MM-DD) for life-stage risk, age (TS007 distribution), countryOfBirth.
/api/validateValidate a lead (JSON body)
Risk-driving demographics are always fetched. Optional: commitmentTier (omit for all six in tierRisks), address, applicantAge or dateOfBirth, age (TS007), countryOfBirth.
/api/validate/batchBatch validation (up to 100 leads)
Product Risk Tiers
Each tier uses different demographic indicators to assess risk:
How Scores Are Calculated
Each lead is scored against the selected commitment tier (or against all six if no tier is supplied). Four inputs feed the score, each contributing in its own way. Tier-specific contributions from the first three are summed, then the applicant-age adjustment is applied on top, then the final score is bucketed into a level. Property/EPC data is returned for enrichment but does not influence the score.
Owned / social-rented / private-rented %, taken from Census 2021 at LSOA level (Local Authority fallback).
- Tier 1 — high social-rented % adds risk.
- Tiers 4 & 5 — low ownership adds risk, but is contextualised: an expensive area with strong qualifications and low income deprivation is treated as a "professional renter" area and not penalised.
- Tier 6 — inverted: ownership below 70% adds risk; below 50% adds substantially more.
LSOA-level median from HPSSA Dataset 46. Used as a tier signal and as a plausibility cross-check against age.
- Tier 4 — median below £150k adds risk.
- Tier 5 — median below £150k adds risk; high prices also flip the Tier 4/5 ownership penalty off.
- Tier 6 — inverted: median below £500k adds risk, below £300k adds more, missing data is itself penalised.
- Plausibility — applicant under 25 in an area with median ≥ £500k adds a flat +10 and raises the
AGE_PROPERTY_MISMATCHflag (applies to all tiers).
IMD deprivation (with income / employment / education / barriers / no-car / housing domains), car availability, occupation, NS-SEC, qualifications, household composition. Each tier weights these differently:
- Tier 1 — overall deprivation %, no-car households
- Tier 2 — employment & income deprivation (IMD), qualifications, occupation mix
- Tier 3 — income & employment deprivation, NS-SEC routine vs managerial mix, qualifications
- Tier 4 — income deprivation, qualifications, NS-SEC
- Tier 5 — income & employment deprivation, qualifications, NS-SEC
- Tier 6 — inverted: actively requires high degree-level (≥ 50%), high managerial % (≥ 45%), low income deprivation (< 5%). Failing those thresholds adds risk.
Supplied as applicantAge or derived from dob. Behaviour:
- Under 18 → hard gate: score forced to ≥100, level high,
AGE_INELIGIBLEflag. - Otherwise → per-tier life-stage adjustment:
score = round(score × (1 + multiplier/100)) + additive. The multiplier amplifies risk derived from the other three inputs; the additive captures standalone life-stage risk (e.g. mortgage term feasibility for Tier 5/6) that fires regardless. Short commitments (Tier 1) barely move; long-dated commitments penalise both very young (lending caps) and very old (mortgage term feasibility) applicants.
| Tier | Young applicants | Older applicants |
|---|---|---|
| Tier 1 | <20: ×1.05 | — |
| Tier 2 | <21: ×1.06 | 75–79: ×1.05; 80+: ×1.08 +4 |
| Tier 3 | <22: ×1.12 +4; <25: ×1.08 | 75–79: ×1.10 +6; 80+: ×1.14 +12 |
| Tier 4 | <21: ×1.18 +14; <23: ×1.14 +8; <25: ×1.10 +4 | 75–79: ×1.10 +12; 80+: ×1.14 +24 |
| Tier 5 | <21: ×1.25 +30; <23: ×1.22 +22; <26: ×1.18 +16; <30: ×1.12 +8 | 75–79: ×1.12 +24; 80+: ×1.18 +40 |
| Tier 6 | <22: ×1.22 +32; <26: ×1.18 +22; <30: ×1.14 +14; <35: ×1.10 +6 | 75–79: ×1.10 +18; 80+: ×1.14 +30 |
score— integer, typically 0–100+ (no hard cap).level— low (0–29), medium (30–59), high (60+).reasons— human-readable strings explaining each contribution.indicators— boolean flags for the conditions that fired.
TIER_HIGH_RISK/TIER_MEDIUM_RISK— set when a single tier is queried and that tier's level is high/medium.AGE_PROPERTY_MISMATCH— applicant under 25 in an area with median price ≥ £500k.AGE_INELIGIBLE— applicant under 18.INVALID_POSTCODE,INVALID_AGE,INVALID_DOB,NO_CENSUS_DATA— input/coverage problems.