{ "openapi": "3.1.0", "info": { "title": "PensionHunter", "version": "1.12.0", "description": "Building the world's pension identification infrastructure. The read-only PensionHunter research tools, called with a Pro API key in the X-API-Key header: the same inputs and outputs as our public connector. Identification and research data, not advice. Keys are issued on application at https://pensionhunter.ai/developers.", "contact": { "url": "https://pensionhunter.ai/developers" } }, "externalDocs": { "url": "https://pensionhunter.ai/developers#agent-manifests", "description": "How this file is made" }, "servers": [ { "url": "https://api.pensionhunter.ai/v1", "description": "Pro API" } ], "security": [ { "apiKey": [] } ], "paths": { "/tools/list_covered_countries": { "post": { "operationId": "list_covered_countries", "summary": "List covered countries", "description": "The countries PensionHunter covers, each with its ISO code and one sourced line on what exists there, and separately the countries we have mapped but not yet researched, each with the institution that pays its old age pension.", "x-openai-isConsequential": false, "security": [ { "apiKey": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "language": { "type": "string", "minLength": 2, "maxLength": 35, "description": "Optional. The language for our own sentences (notes, offer, labels, gap and register sentences), as an ISO 639-1 code: en, ar, da, de, es, fa, fr, hi, id, it, ja, ko, nb, nl, pl, pt, pt-BR, ro, ru, sv, th, tl, tr, zh, vi, uk, bg. Default en. pt is European Portuguese, pt-BR Brazilian, zh Simplified Chinese. Facts, numbers, dates, names and authority answers stay exactly as stored; a fact translation appears only from our committed table, marked translation: true. An unknown code is answered in English with a note." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Result. A result for researched countries ends with the report offer and an order link built for them; a result naming only mapped countries carries neither.", "content": { "application/json": { "schema": { "type": "object", "properties": { "countryCount": { "type": "integer" }, "countries": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "iso2": { "type": [ "string", "null" ] }, "whatExists": { "type": [ "object", "null" ], "description": "A stored fact with the source it came from and the date we read that source. Null when we hold no sourced line.", "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The publisher or document the fact comes from." }, "read": { "type": "string", "description": "The date we read the source, for example 7 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "read" ], "additionalProperties": false }, "localName": { "type": "string", "description": "The country name in the language served, from Unicode CLDR. Present only for a language other than English." } }, "required": [ "country", "iso2", "whatExists" ], "additionalProperties": false } }, "mapped": { "type": "array", "description": "Countries we have mapped but not researched; not counted in countryCount. Mapped: we name the institution and the official route; we have not yet researched this country in depth.", "items": { "type": "object", "properties": { "iso2": { "type": "string" }, "name": { "type": "string" }, "tier": { "type": "string", "enum": [ "mapped" ] }, "institution": { "type": "string", "description": "The English name of the institution that pays the old age pension." }, "localName": { "type": "string", "description": "The country name in the language served, from Unicode CLDR. Present only for a language other than English." } }, "required": [ "iso2", "name", "tier", "institution" ], "additionalProperties": false } }, "language": { "type": "object", "description": "Present when language was sent: the language served, its own name, and labels for source, read date, translation and original in that language. Our sentences in this result are translations of our own wording, review recommended.", "properties": { "requested": { "type": "string", "description": "The language as sent, when it reads as a language tag; empty otherwise." }, "served": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "name": { "type": "string" }, "supported": { "type": "boolean", "description": "False when the language sent is not one of ours; the result is then in English." }, "note": { "type": [ "string", "null" ], "description": "Why the result is in English, when the language sent is not one we serve." }, "ourWording": { "type": "string", "description": "In the served language: these are translations of our own wording, review recommended." }, "facts": { "type": "string", "description": "In the served language: facts, numbers and dates are served exactly as stored." }, "labels": { "type": "object", "properties": { "source": { "type": "string" }, "read": { "type": "string" }, "translation": { "type": "string" }, "original": { "type": "string" } }, "required": [ "source", "read", "translation", "original" ], "additionalProperties": false } }, "required": [ "requested", "served", "name", "supported", "note", "ourWording", "facts", "labels" ], "additionalProperties": false }, "sample_report": { "type": "string", "format": "uri", "description": "Our sample report, to read what a report holds before ordering." } }, "required": [ "countryCount", "countries", "mapped" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input. The error says how to fix the call.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, unknown or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit reached: for this key, or for a widget key, for this key and Origin. Retry after the number of seconds in the Retry-After header." } } } }, "/tools/country_pension_facts": { "post": { "operationId": "country_pension_facts", "summary": "Country pension facts", "description": "One country's facts, the official free routes first: freeOfficialRoute (never empty for a covered country; each route with what it does, the scheme it covers and whether it works from abroad) and contactAbroad (an official contact for people living abroad), then whatIsHardFromAbroad (honest and.", "x-openai-isConsequential": false, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "type": "string", "minLength": 2, "maxLength": 200, "description": "One country, as an English name, a native name, a common alias or an ISO 3166 alpha-2 or alpha-3 code, in any case. Examples: Netherlands, Nederland, Holland, NL, NLD; United Kingdom, UK, GB, Britain; Germany, Deutschland, DE." }, "question": { "type": "string", "maxLength": 500, "description": "Optional. The person's question in plain words, for example \"Where is my workplace pension from Merrill Lynch?\" or \"Do I still have money in my EPF account?\". Used only to tell which kind of pension it is about." }, "pensionType": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ], "description": "Optional. The kind of pension asked about, when known: state, workplace, provident or personal. Overrides the question." }, "language": { "type": "string", "minLength": 2, "maxLength": 35, "description": "Optional. The language for our own sentences (notes, offer, labels, gap and register sentences), as an ISO 639-1 code: en, ar, da, de, es, fa, fr, hi, id, it, ja, ko, nb, nl, pl, pt, pt-BR, ro, ru, sv, th, tl, tr, zh, vi, uk, bg. Default en. pt is European Portuguese, pt-BR Brazilian, zh Simplified Chinese. Facts, numbers, dates, names and authority answers stay exactly as stored; a fact translation appears only from our committed table, marked translation: true. An unknown code is answered in English with a note." } }, "required": [ "country" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Result. A result for researched countries ends with the report offer and an order link built for them; a result naming only mapped countries carries neither.", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "The country string as sent." }, "country": { "type": "string", "description": "The country it was read as." }, "iso2": { "type": [ "string", "null" ] }, "recognised": { "type": "boolean", "description": "False when the string is not a country we can read." }, "covered": { "type": "boolean" }, "riskFreeOffer": { "type": "object", "description": "The risk-free offer, at the top of every research answer: finding who holds your pension and how to reach them is our job, with a full refund if we find nothing material, the delivery times, our Trustpilot reviews as last synced, and a sample report to read first.", "properties": { "line": { "type": "string", "description": "The one line to lead with." }, "refund": { "type": "string" }, "refundUrl": { "type": "string", "format": "uri" }, "delivery": { "type": "object", "properties": { "country": { "type": "string" }, "enhanced": { "type": "string" }, "global": { "type": "string" } }, "required": [ "country", "enhanced", "global" ], "additionalProperties": false }, "trustpilot": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "score": { "type": [ "number", "null" ] }, "reviewCount": { "type": [ "integer", "null" ] } }, "required": [ "url", "score", "reviewCount" ], "additionalProperties": false }, "sampleReport": { "type": "string", "format": "uri" } }, "required": [ "line", "refund", "refundUrl", "delivery", "trustpilot", "sampleReport" ], "additionalProperties": false }, "citation": { "type": "object", "description": "A canonical pensionhunter.ai page for this answer and a one-line attribution, so an assistant can cite us as the source. Points only at pages we publish; a per-country facts page is being built and this will point there when it lands.", "properties": { "url": { "type": "string", "format": "uri" }, "attribution": { "type": "string" }, "note": { "type": "string" } }, "required": [ "url", "attribution" ], "additionalProperties": false }, "freeOfficialRoute": { "type": "array", "items": { "type": "object", "description": "An official body's contact details, read from its own page on the date given. email is null when the page publishes none; emailNote then says so and online gives the official service or form.", "properties": { "id": { "type": "string" }, "iso2": { "type": "string" }, "institution": { "type": "string" }, "role": { "type": "string" }, "website": { "type": "string", "format": "uri" }, "contactPage": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "emailNote": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "phoneFromAbroad": { "type": [ "string", "null" ] }, "hours": { "type": [ "string", "null" ] }, "post": { "type": [ "string", "null" ] }, "online": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "required": [ "name", "url" ], "additionalProperties": false }, "source": { "type": "string" }, "read": { "type": "string" }, "quote": { "type": [ "string", "null" ] }, "scheme": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ] }, "description": "The scheme the fact is about: state (state pension), workplace (workplace or occupational pension), provident (a national provident fund account) or personal (personal pension)." }, "process": { "type": "array", "items": { "type": "string", "enum": [ "tracing", "record", "payment" ], "description": "What the fact is about: tracing (finding which scheme or fund holds it), record (seeing your record or forecast) or payment (applying for payment)." }, "description": "What the route does: tracing, record or payment." }, "fromAbroad": { "type": "object", "description": "Whether the route works for a person living abroad, as our directory or the body's own page records it, with the note behind it.", "properties": { "verdict": { "type": "string", "enum": [ "yes", "conditional", "mostly_in_country", "not_stated" ] }, "note": { "type": [ "string", "null" ] } }, "required": [ "verdict", "note" ], "additionalProperties": false }, "abroadOnly": { "type": "boolean", "description": "Present and true for a route that exists for people living OUTSIDE the country (e.g. the UK International Pension Centre); it is dropped for a person who resides in that country." } }, "required": [ "id", "iso2", "institution", "role", "website", "contactPage", "email", "emailNote", "phone", "phoneFromAbroad", "hours", "post", "online", "source", "read", "quote" ], "additionalProperties": false }, "description": "The official free routes, first and never empty for a covered country: each official body or service with what it does (role), the scheme it covers, whether it works from abroad, and the website, email, phone and post we read on its own page with the date. Our report is only what we add on top." }, "contactAbroad": { "type": [ "object", "null" ], "description": "The official contact page for people living abroad, as a link, with the body it belongs to, the scheme and the date we read it. Telephone numbers, emails and postal addresses are report content and are never returned by the free tools. Null only when we hold no official route.", "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The publisher or document the fact comes from." }, "read": { "type": "string", "description": "The date we read the source, for example 7 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false }, "scheme": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ] }, "description": "The scheme the fact is about: state (state pension), workplace (workplace or occupational pension), provident (a national provident fund account) or personal (personal pension)." }, "process": { "type": "string", "enum": [ "tracing", "record", "payment" ], "description": "What the fact is about: tracing (finding which scheme or fund holds it), record (seeing your record or forecast) or payment (applying for payment)." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "source": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "quote": { "type": "string", "description": "Verbatim words from the source." }, "read": { "type": "string" }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "url", "read" ], "additionalProperties": false }, "description": "The stored rows this sentence restates, each with the page it was read on, the words on that page and the date we read it." }, "url": { "type": "string", "format": "uri", "description": "The official contact page." } }, "required": [ "text", "source", "read", "scheme" ], "additionalProperties": false }, "whatIsHardFromAbroad": { "type": "array", "items": { "type": "object", "description": "A stored fact with the source it came from and the date we read that source. Null when we hold no sourced line.", "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The publisher or document the fact comes from." }, "read": { "type": "string", "description": "The date we read the source, for example 7 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false }, "scheme": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ] }, "description": "The scheme the fact is about: state (state pension), workplace (workplace or occupational pension), provident (a national provident fund account) or personal (personal pension)." }, "process": { "type": "string", "enum": [ "tracing", "record", "payment" ], "description": "What the fact is about: tracing (finding which scheme or fund holds it), record (seeing your record or forecast) or payment (applying for payment)." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "source": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "quote": { "type": "string", "description": "Verbatim words from the source." }, "read": { "type": "string" }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "url", "read" ], "additionalProperties": false }, "description": "The stored rows this sentence restates, each with the page it was read on, the words on that page and the date we read it." } }, "required": [ "text", "source", "read", "scheme", "process" ], "additionalProperties": false }, "description": "What is hard from abroad, one fact per scheme and process (tracing, record, payment), each with its source and read date. Honest and specific: what a person living abroad meets on the free route, and the route that works where we hold one. Never an absolute." }, "whatTheMoneyIsWorth": { "type": [ "object", "null" ], "description": "A stored fact with the source it came from and the date we read that source. Null when we hold no sourced line.", "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The publisher or document the fact comes from." }, "read": { "type": "string", "description": "The date we read the source, for example 7 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false }, "scheme": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ] }, "description": "The scheme the fact is about: state (state pension), workplace (workplace or occupational pension), provident (a national provident fund account) or personal (personal pension)." }, "process": { "type": "string", "enum": [ "tracing", "record", "payment" ], "description": "What the fact is about: tracing (finding which scheme or fund holds it), record (seeing your record or forecast) or payment (applying for payment)." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "source": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "quote": { "type": "string", "description": "Verbatim words from the source." }, "read": { "type": "string" }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "url", "read" ], "additionalProperties": false }, "description": "The stored rows this sentence restates, each with the page it was read on, the words on that page and the date we read it." } }, "required": [ "text", "source", "read", "scheme" ], "additionalProperties": false }, "periodFacts": { "type": "array", "description": "Rules in force today, from stored rows. Stored rows whose dates fit the period given and the birth year where one was sent, or, without a period, the rows in force today: each with its source, the page it was read on, the words on that page, the date we read it, and the dates the rule covers (null: the source states no start or end). A row about years before a scheme began is never listed.", "items": { "type": "object", "properties": { "text": { "type": "string" }, "source": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "quote": { "type": "string", "description": "Verbatim words from the source." }, "read": { "type": "string" }, "scheme": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ] }, "description": "The scheme the fact is about: state (state pension), workplace (workplace or occupational pension), provident (a national provident fund account) or personal (personal pension)." }, "topic": { "type": "string", "enum": [ "start", "money", "qualifying", "vesting", "value" ] }, "validFrom": { "type": [ "string", "null" ] }, "validTo": { "type": [ "string", "null" ] }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "url", "read", "scheme", "topic", "validFrom", "validTo" ], "additionalProperties": false } }, "datedObligations": { "type": "array", "items": { "type": "object", "description": "A stored fact with the source it came from and the date we read that source. Null when we hold no sourced line.", "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The publisher or document the fact comes from." }, "read": { "type": "string", "description": "The date we read the source, for example 7 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false }, "scheme": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ] }, "description": "The scheme the fact is about: state (state pension), workplace (workplace or occupational pension), provident (a national provident fund account) or personal (personal pension)." }, "process": { "type": "string", "enum": [ "tracing", "record", "payment" ], "description": "What the fact is about: tracing (finding which scheme or fund holds it), record (seeing your record or forecast) or payment (applying for payment)." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "source": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "quote": { "type": "string", "description": "Verbatim words from the source." }, "read": { "type": "string" }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "url", "read" ], "additionalProperties": false }, "description": "The stored rows this sentence restates, each with the page it was read on, the words on that page and the date we read it." } }, "required": [ "text", "source", "read", "scheme" ], "additionalProperties": false } }, "reportAdds": { "type": "array", "items": { "type": "string" }, "description": "What our report adds for this country beyond the official free routes, as sentences to pass on: which workplace or second pillar funds or insurers hold the pensions, the successor of any renamed, merged or bought out employer or scheme, one sourced contact route per holder, and the work we take off the person. Never the state pension holder alone." }, "whyTheFreeRouteFailsFromAbroad": { "type": [ "object", "null" ], "description": "Deprecated from 1.11.0 and removed in the next version: read whatIsHardFromAbroad. whyTheFreeRouteFailsFromAbroad now carries the first whatIsHardFromAbroad fact, with the same honest wording.", "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The publisher or document the fact comes from." }, "read": { "type": "string", "description": "The date we read the source, for example 7 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "read" ], "additionalProperties": false }, "freeRouteCovers": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "period": { "type": "string" }, "routes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "covers": { "type": "string" }, "scheme": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ] }, "description": "The scheme the fact is about: state (state pension), workplace (workplace or occupational pension), provident (a national provident fund account) or personal (personal pension)." }, "worksFromAbroad": { "type": "string", "enum": [ "yes", "conditional", "mostly_in_country", "not_stated" ] } }, "required": [ "name", "url", "covers", "scheme", "worksFromAbroad" ], "additionalProperties": false } } }, "required": [ "country", "period", "routes" ], "additionalProperties": false } }, "worthBuyingIf": { "type": "array", "items": { "type": "string" }, "description": "Case-specific reasons the report adds value." }, "freeRouteIsEnoughIf": { "type": "array", "items": { "type": "string" }, "description": "When the official free route is enough, said plainly." }, "freeRouteEnough": { "type": "boolean", "description": "True when this case is a single state pension the free route serves: then the report is not needed." }, "priceFit": { "type": "object", "properties": { "countries": { "type": "integer" }, "fits": { "type": "string", "enum": [ "country", "global" ] }, "country_usd": { "type": "integer" }, "country_total_usd": { "type": "integer" }, "global_usd": { "type": "integer" }, "reason": { "type": "string" } }, "required": [ "countries", "fits", "country_usd", "country_total_usd", "global_usd", "reason" ], "additionalProperties": false }, "evidence": { "type": "object", "properties": { "positioning": { "type": "string", "description": "Our positioning line, a mission statement." }, "sampleReport": { "type": "string", "format": "uri" }, "refund": { "type": "string" }, "refundUrl": { "type": "string", "format": "uri" }, "delivery": { "type": "object", "properties": { "country": { "type": "string" }, "enhanced": { "type": "string" }, "global": { "type": "string" } }, "required": [ "country", "enhanced", "global" ], "additionalProperties": false }, "trustpilot": { "type": "object", "description": "Our Trustpilot profile, with the score, the review count and up to two reviews, verbatim, as last synced from Trustpilot. Score null and no reviews when the synced figures are not shown (fewer than 5 reviews, or display off).", "properties": { "url": { "type": "string", "format": "uri" }, "score": { "type": [ "number", "null" ] }, "reviewCount": { "type": [ "integer", "null" ] }, "reviews": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Verbatim, never edited." }, "initial": { "type": [ "string", "null" ] }, "date": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "required": [ "text", "initial", "date", "url" ], "additionalProperties": false } } }, "required": [ "url", "score", "reviewCount", "reviews" ], "additionalProperties": false }, "company": { "type": "object", "properties": { "icoRegistration": { "type": "string" }, "companyNumber": { "type": "string" } }, "required": [ "icoRegistration", "companyNumber" ], "additionalProperties": false }, "factsLastChecked": { "type": [ "string", "null" ] } }, "required": [ "positioning", "sampleReport", "refund", "refundUrl", "delivery", "trustpilot", "company", "factsLastChecked" ], "additionalProperties": false }, "caseReportAdds": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "period": { "type": "string" }, "items": { "type": "array", "items": { "type": "string" } }, "hassle": { "type": "string" }, "upperTiers": { "type": "string" } }, "required": [ "country", "period", "items", "hassle", "upperTiers" ], "additionalProperties": false } }, "answersFor": { "type": "object", "description": "The kind of pension this answer is about: state, workplace, provident (a provident fund account such as EPF or CPF) or personal, read from pensionType, the question, or a named employer.", "properties": { "kind": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ] }, "readFrom": { "type": [ "string", "null" ], "enum": [ "pensionType", "question", "employer", null ] }, "matched": { "type": "array", "items": { "type": "string" } }, "note": { "type": [ "string", "null" ] } }, "required": [ "kind", "readFrom" ], "additionalProperties": false }, "schemeRegister": { "type": [ "object", "null" ], "description": "For a workplace pension question: where the country lists occupational pension funds.", "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The publisher or document the fact comes from." }, "read": { "type": "string", "description": "The date we read the source, for example 7 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "read" ], "additionalProperties": false }, "pending": { "type": "string" }, "note": { "type": "string" }, "tier": { "type": "string", "enum": [ "mapped" ], "description": "Present for a mapped country: one we have mapped but not yet researched in depth." }, "mapped": { "type": "object", "description": "For a mapped country only: the institution that pays the contributory old age pension, its website as a bare domain, its official route to contact it from abroad, and which researched countries it has a social security agreement with, each with the domain it was read on and the date. Mapped: we name the institution and the official route; we have not yet researched this country in depth.", "properties": { "note": { "type": "string", "enum": [ "Mapped: we name the institution and the official route; we have not yet researched this country in depth.", "بلد مرصود: نذكر المؤسسة والطريق الرسمي؛ لم نبحث هذا البلد بعمق حتى الآن.", "Kortlagt land: vi navngiver institutionen og den officielle vej; vi har endnu ikke undersøgt dette land i dybden.", "Erfasstes Land: Wir nennen die Institution und den offiziellen Weg; dieses Land haben wir noch nicht vertieft recherchiert.", "País cartografiado: nombramos la institución y la vía oficial; todavía no hemos investigado este país en profundidad.", "کشور نقشه‌برداری‌شده: نهاد و راه رسمی را نام می‌بریم؛ هنوز این کشور را به‌طور عمیق بررسی نکرده‌ایم.", "Pays cartographié : nous nommons l'institution et la voie officielle ; nous n'avons pas encore étudié ce pays en profondeur.", "मैप किया गया देश: हम संस्था और आधिकारिक रास्ते का नाम बताते हैं; हमने अभी तक इस देश पर गहराई से शोध नहीं किया है।", "Negara terpetakan: kami menyebutkan lembaga dan jalur resminya; kami belum meneliti negara ini secara mendalam.", "Paese mappato: indichiamo l'istituto e la via ufficiale; non abbiamo ancora studiato a fondo questo paese.", "マッピング済みの国：機関と公式の経路をお示しします。この国はまだ詳しく調査していません。", "매핑된 국가: 기관과 공식 경로를 알려 드립니다. 이 국가는 아직 심층 조사하지 않았습니다.", "Kartlagt land: vi navngir institusjonen og den offisielle veien; vi har ennå ikke undersøkt dette landet i dybden.", "In kaart gebracht land: wij noemen de instelling en de officiële route; dit land hebben wij nog niet diepgaand onderzocht.", "Kraj zmapowany: podajemy instytucję i oficjalną drogę; tego kraju nie zbadaliśmy jeszcze dogłębnie.", "País mapeado: indicamos a instituição e a via oficial; ainda não estudámos este país em profundidade.", "País mapeado: indicamos a instituição e a via oficial; ainda não estudamos este país em profundidade.", "Țară cartografiată: numim instituția și calea oficială; nu am cercetat încă în profunzime această țară.", "Страна нанесена на карту: мы называем учреждение и официальный путь; эту страну мы ещё не исследовали углублённо.", "Kartlagt land: vi namnger institutionen och den officiella vägen; vi har ännu inte undersökt det här landet på djupet.", "ประเทศที่จัดทำแผนที่แล้ว: เราระบุหน่วยงานและช่องทางทางการ แต่ยังไม่ได้ศึกษาประเทศนี้อย่างลึกซึ้ง", "Bansang naimapa: binabanggit namin ang institusyon at ang opisyal na daan; hindi pa namin lubusang sinasaliksik ang bansang ito.", "Haritalanmış ülke: kurumu ve resmi yolu belirtiyoruz; bu ülkeyi henüz derinlemesine araştırmadık.", "已梳理国家：我们列出该机构及官方途径；我们尚未深入研究这个国家。", "Đã lập bản đồ: chúng tôi nêu tên cơ quan và con đường chính thức; chúng tôi chưa nghiên cứu sâu quốc gia này.", "Країну нанесено на мапу: ми називаємо установу та офіційний шлях; цю країну ми ще не досліджували поглиблено.", "Страната е картографирана: посочваме институцията и официалния път; все още не сме проучили задълбочено тази страна." ], "description": "The honest line, in the language served." }, "institutions": { "type": "array", "items": { "type": "object", "properties": { "nameEn": { "type": "object", "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The domain of the official page the fact was read on." }, "read": { "type": "string", "description": "The date we read that page, for example 13 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "read" ], "additionalProperties": false }, "nameNative": { "type": [ "object", "null" ], "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The domain of the official page the fact was read on." }, "read": { "type": "string", "description": "The date we read that page, for example 13 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "read" ], "additionalProperties": false }, "website": { "type": [ "object", "null" ], "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The domain of the official page the fact was read on." }, "read": { "type": "string", "description": "The date we read that page, for example 13 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "read" ], "additionalProperties": false, "description": "The official website as its bare domain, never a link." }, "contactFromAbroad": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "form", "postal", "email" ] }, "detail": { "type": "string", "description": "The form name, the postal address as published, or the email address." }, "source": { "type": "string" }, "read": { "type": "string" } }, "required": [ "kind", "detail", "source", "read" ], "additionalProperties": false } } }, "required": [ "nameEn", "nameNative", "website", "contactFromAbroad" ], "additionalProperties": false } }, "agreements": { "type": "array", "items": { "type": "object", "properties": { "iso2": { "type": "string" }, "country": { "type": "string", "description": "A researched country this one has a social security agreement with." }, "source": { "type": "string" }, "read": { "type": "string" } }, "required": [ "iso2", "country", "source", "read" ], "additionalProperties": false } }, "agreementListsRead": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The domain of the official page the fact was read on." }, "read": { "type": "string", "description": "The date we read that page, for example 13 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "read" ], "additionalProperties": false }, "description": "The official agreement lists we read, so an absent agreement is itself sourced." }, "gaps": { "type": "array", "items": { "type": "string" }, "description": "Facts we could not read on an official page. Recurring sentences are served in the language asked for; the rest stay in English." } }, "required": [ "note", "institutions", "agreements", "agreementListsRead", "gaps" ], "additionalProperties": false }, "localName": { "type": "string", "description": "The country name in the language served, from Unicode CLDR. Present only for a language other than English." }, "next_step": { "type": "object", "description": "What we add to the free official route, as one structured field built from the finding: one line to pass on, the pre-filled order link with a source tag, the tier, the country and the fee from our price config. Country tier for one or two likely countries; Global only when three or more countries are likely. Absent when the result found nothing in a country we research, or names only mapped countries.", "properties": { "line": { "type": "string", "description": "One line to pass on to the person, with the fee." }, "order_url": { "type": "string", "format": "uri", "description": "Our order page with tier and countries filled in and utm_source=connector, utm_medium=mcp, utm_campaign=. Never personal data." }, "tier": { "type": "string", "enum": [ "country", "global" ] }, "country": { "type": "string", "description": "ISO 3166 alpha-2 code of the country, or the first of them." }, "countries": { "type": "array", "items": { "type": "string" }, "description": "Every country the step covers, ISO codes." }, "price_usd": { "type": "integer", "description": "The fee in whole US dollars, from our price config." }, "refund": { "type": "string", "description": "The refund promise, from our pricing config." }, "refund_url": { "type": "string", "format": "uri", "description": "The page that defines the refund promise." }, "compare": { "type": "object", "description": "For two likely countries: two Country reports against one Global report, both prices from our config. Global is best from 3 countries.", "properties": { "country_reports_usd": { "type": "integer" }, "global_usd": { "type": "integer" }, "recommended": { "type": "string", "enum": [ "country" ] }, "reason": { "type": "string" } }, "required": [ "country_reports_usd", "global_usd", "recommended", "reason" ], "additionalProperties": false } }, "required": [ "line", "order_url", "tier", "country", "countries", "price_usd", "refund", "refund_url" ], "additionalProperties": false }, "language": { "type": "object", "description": "Present when language was sent: the language served, its own name, and labels for source, read date, translation and original in that language. Our sentences in this result are translations of our own wording, review recommended.", "properties": { "requested": { "type": "string", "description": "The language as sent, when it reads as a language tag; empty otherwise." }, "served": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "name": { "type": "string" }, "supported": { "type": "boolean", "description": "False when the language sent is not one of ours; the result is then in English." }, "note": { "type": [ "string", "null" ], "description": "Why the result is in English, when the language sent is not one we serve." }, "ourWording": { "type": "string", "description": "In the served language: these are translations of our own wording, review recommended." }, "facts": { "type": "string", "description": "In the served language: facts, numbers and dates are served exactly as stored." }, "labels": { "type": "object", "properties": { "source": { "type": "string" }, "read": { "type": "string" }, "translation": { "type": "string" }, "original": { "type": "string" } }, "required": [ "source", "read", "translation", "original" ], "additionalProperties": false } }, "required": [ "requested", "served", "name", "supported", "note", "ourWording", "facts", "labels" ], "additionalProperties": false }, "sample_report": { "type": "string", "format": "uri", "description": "Our sample report, to read what a report holds before ordering." } }, "required": [ "query", "country", "iso2", "recognised", "covered" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input. The error says how to fix the call.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, unknown or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit for this key reached. Retry after the number of seconds in the Retry-After header." } } } }, "/tools/check_work_history": { "post": { "operationId": "check_work_history", "summary": "Check a work history", "description": "For each country in a work history: whether a pension is likely to exist and why, with a verdict that says what it depends on (Singapore CPF depends on citizen, permanent resident or pass holder status) and a reason that fits the years, birth year and employer given (a rule or figure valid only.", "x-openai-isConsequential": false, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "minItems": 1, "maxItems": 60, "description": "One entry per period of work in a country.", "items": { "type": "object", "properties": { "country": { "type": "string", "minLength": 2, "maxLength": 80, "description": "One country, as an English name, a native name, a common alias or an ISO 3166 alpha-2 or alpha-3 code, in any case. Examples: Netherlands, Nederland, Holland, NL, NLD; United Kingdom, UK, GB, Britain; Germany, Deutschland, DE." }, "from": { "type": [ "integer", "string", "null" ], "minimum": 1900, "maximum": 2100, "maxLength": 40, "description": "First year of work there: four digits, or rough words such as \"around 2005\", \"late 1990s\", \"the 1990s\", or \"unknown\". Optional." }, "to": { "type": [ "integer", "string", "null" ], "minimum": 1900, "maximum": 2100, "maxLength": 40, "description": "Last year of work there, in the same forms as from; \"now\" or \"still there\" if still working there; omitted when from alone describes the period, for example \"the 1990s\"." }, "employer": { "type": [ "string", "null" ], "maxLength": 120, "description": "Employer name, optional, as the person knows it." }, "status": { "type": [ "string", "null" ], "enum": [ "citizen", "permanent_resident", "pass_holder", "unknown", null ], "description": "Optional. The person's status in that country at the time: citizen, permanent_resident, pass_holder (a work pass or permit) or unknown. Decides the verdict where contributions depended on it, such as Singapore CPF." }, "pensionType": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ], "description": "Optional. The kind of pension asked about for this period: state, workplace, provident or personal." } }, "required": [ "country" ], "additionalProperties": false } }, "subject": { "type": "object", "description": "Optional facts about the person, used only to decide which dated obligations apply.", "properties": { "birthYear": { "type": "integer", "minimum": 1900, "maximum": 2100, "description": "Year of birth, four digits." }, "deceased": { "type": "boolean", "description": "True when the person has died and a relative is asking." }, "pensionInPaymentCountries": { "type": "array", "items": { "type": "string", "description": "One country, as an English name, a native name, a common alias or an ISO 3166 alpha-2 or alpha-3 code, in any case. Examples: Netherlands, Nederland, Holland, NL, NLD; United Kingdom, UK, GB, Britain; Germany, Deutschland, DE." }, "description": "Countries already paying the person a pension." }, "childrenMentioned": { "type": "boolean", "description": "True when children are part of the question." } }, "additionalProperties": false }, "question": { "type": "string", "maxLength": 500, "description": "Optional. The person's question in plain words; used only to tell which kind of pension it is about." }, "countryOfResidence": { "type": "string", "maxLength": 80, "description": "Optional. The country the person lives in now, as a name, alias or ISO code. For a country they still live in, what is hard from abroad is left out (livesHere: true)." }, "birthYear": { "type": "integer", "minimum": 1900, "maximum": 2100, "description": "Optional. Year of birth, four digits; the same as subject.birthYear. Used for rules that depend on age, such as German employer pension vesting." }, "language": { "type": "string", "minLength": 2, "maxLength": 35, "description": "Optional. The language for our own sentences (notes, offer, labels, gap and register sentences), as an ISO 639-1 code: en, ar, da, de, es, fa, fr, hi, id, it, ja, ko, nb, nl, pl, pt, pt-BR, ro, ru, sv, th, tl, tr, zh, vi, uk, bg. Default en. pt is European Portuguese, pt-BR Brazilian, zh Simplified Chinese. Facts, numbers, dates, names and authority answers stay exactly as stored; a fact translation appears only from our committed table, marked translation: true. An unknown code is answered in English with a note." } }, "required": [ "entries" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Result. A result for researched countries ends with the report offer and an order link built for them; a result naming only mapped countries carries neither.", "content": { "application/json": { "schema": { "type": "object", "properties": { "riskFreeOffer": { "type": "object", "description": "The risk-free offer, at the top of every research answer: finding who holds your pension and how to reach them is our job, with a full refund if we find nothing material, the delivery times, our Trustpilot reviews as last synced, and a sample report to read first.", "properties": { "line": { "type": "string", "description": "The one line to lead with." }, "refund": { "type": "string" }, "refundUrl": { "type": "string", "format": "uri" }, "delivery": { "type": "object", "properties": { "country": { "type": "string" }, "enhanced": { "type": "string" }, "global": { "type": "string" } }, "required": [ "country", "enhanced", "global" ], "additionalProperties": false }, "trustpilot": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "score": { "type": [ "number", "null" ] }, "reviewCount": { "type": [ "integer", "null" ] } }, "required": [ "url", "score", "reviewCount" ], "additionalProperties": false }, "sampleReport": { "type": "string", "format": "uri" } }, "required": [ "line", "refund", "refundUrl", "delivery", "trustpilot", "sampleReport" ], "additionalProperties": false }, "citation": { "type": "object", "description": "A canonical pensionhunter.ai page for this answer and a one-line attribution, so an assistant can cite us as the source. Points only at pages we publish; a per-country facts page is being built and this will point there when it lands.", "properties": { "url": { "type": "string", "format": "uri" }, "attribution": { "type": "string" }, "note": { "type": "string" } }, "required": [ "url", "attribution" ], "additionalProperties": false }, "freeRouteCovers": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "period": { "type": "string" }, "routes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "covers": { "type": "string" }, "scheme": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ] }, "description": "The scheme the fact is about: state (state pension), workplace (workplace or occupational pension), provident (a national provident fund account) or personal (personal pension)." }, "worksFromAbroad": { "type": "string", "enum": [ "yes", "conditional", "mostly_in_country", "not_stated" ] } }, "required": [ "name", "url", "covers", "scheme", "worksFromAbroad" ], "additionalProperties": false } } }, "required": [ "country", "period", "routes" ], "additionalProperties": false } }, "reportAdds": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "period": { "type": "string" }, "items": { "type": "array", "items": { "type": "string" } }, "hassle": { "type": "string" }, "upperTiers": { "type": "string" } }, "required": [ "country", "period", "items", "hassle", "upperTiers" ], "additionalProperties": false } }, "worthBuyingIf": { "type": "array", "items": { "type": "string" }, "description": "Case-specific reasons the report adds value." }, "freeRouteIsEnoughIf": { "type": "array", "items": { "type": "string" }, "description": "When the official free route is enough, said plainly." }, "freeRouteEnough": { "type": "boolean", "description": "True when this case is a single state pension the free route serves: then the report is not needed." }, "priceFit": { "type": "object", "properties": { "countries": { "type": "integer" }, "fits": { "type": "string", "enum": [ "country", "global" ] }, "country_usd": { "type": "integer" }, "country_total_usd": { "type": "integer" }, "global_usd": { "type": "integer" }, "reason": { "type": "string" } }, "required": [ "countries", "fits", "country_usd", "country_total_usd", "global_usd", "reason" ], "additionalProperties": false }, "evidence": { "type": "object", "properties": { "positioning": { "type": "string", "description": "Our positioning line, a mission statement." }, "sampleReport": { "type": "string", "format": "uri" }, "refund": { "type": "string" }, "refundUrl": { "type": "string", "format": "uri" }, "delivery": { "type": "object", "properties": { "country": { "type": "string" }, "enhanced": { "type": "string" }, "global": { "type": "string" } }, "required": [ "country", "enhanced", "global" ], "additionalProperties": false }, "trustpilot": { "type": "object", "description": "Our Trustpilot profile, with the score, the review count and up to two reviews, verbatim, as last synced from Trustpilot. Score null and no reviews when the synced figures are not shown (fewer than 5 reviews, or display off).", "properties": { "url": { "type": "string", "format": "uri" }, "score": { "type": [ "number", "null" ] }, "reviewCount": { "type": [ "integer", "null" ] }, "reviews": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Verbatim, never edited." }, "initial": { "type": [ "string", "null" ] }, "date": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "required": [ "text", "initial", "date", "url" ], "additionalProperties": false } } }, "required": [ "url", "score", "reviewCount", "reviews" ], "additionalProperties": false }, "company": { "type": "object", "properties": { "icoRegistration": { "type": "string" }, "companyNumber": { "type": "string" } }, "required": [ "icoRegistration", "companyNumber" ], "additionalProperties": false }, "factsLastChecked": { "type": [ "string", "null" ] } }, "required": [ "positioning", "sampleReport", "refund", "refundUrl", "delivery", "trustpilot", "company", "factsLastChecked" ], "additionalProperties": false }, "recommendation": { "type": "object", "description": "The honest buy or no-buy recommendation for this case, for an assistant to act on, built from the sourced findings only. free_route is a correct non-buy and carries no order link. Decisions stay the person's own.", "properties": { "recommendation": { "type": "string", "enum": [ "country", "enhanced", "global", "free_route" ], "description": "country or global by the number of likely countries (Global from three), enhanced for a single complex country, free_route when the official route is enough." }, "why": { "type": "array", "items": { "type": "string" }, "description": "Up to three concrete, case-specific reasons, from the sourced findings." }, "whatYouWouldDoYourself": { "type": "array", "items": { "type": "string" }, "description": "The work from abroad the report replaces: tracing each holder across old company names and languages, and the steps that are hard from abroad." }, "confidence": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "high", "medium", "low" ] }, "basis": { "type": "string" } }, "required": [ "level", "basis" ], "additionalProperties": false }, "tier": { "type": [ "string", "null" ], "enum": [ "country", "enhanced", "global", null ], "description": "The tier to order; null for a free_route non-buy." }, "priceUsd": { "type": [ "integer", "null" ] }, "countries": { "type": "array", "items": { "type": "string" }, "description": "ISO codes the recommendation covers." }, "orderUrl": { "type": [ "string", "null" ], "description": "The pre-filled order page; null for a free_route non-buy." }, "enhanced": { "type": [ "object", "null" ], "description": "The Enhanced report option with its price, offered alongside a Country buy.", "properties": { "priceUsd": { "type": "integer" }, "whenItHelps": { "type": "string" } }, "required": [ "priceUsd", "whenItHelps" ], "additionalProperties": false }, "proof": { "type": "object", "description": "Risk reversal an assistant can pass on: our reviews, the refund, delivery times and a sample report.", "properties": { "trustpilot": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "score": { "type": [ "number", "null" ] }, "reviewCount": { "type": [ "integer", "null" ] } }, "required": [ "url", "score", "reviewCount" ], "additionalProperties": false }, "refund": { "type": "string" }, "refundUrl": { "type": "string", "format": "uri" }, "delivery": { "type": "object", "properties": { "country": { "type": "string" }, "enhanced": { "type": "string" }, "global": { "type": "string" } }, "required": [ "country", "enhanced", "global" ], "additionalProperties": false }, "sampleReport": { "type": "string", "format": "uri" } }, "required": [ "trustpilot", "refund", "refundUrl", "delivery", "sampleReport" ], "additionalProperties": false }, "agency": { "type": "string", "description": "Our team explains each reply; decisions stay the person's own." } }, "required": [ "recommendation", "why", "whatYouWouldDoYourself", "confidence", "tier", "priceUsd", "countries", "orderUrl", "enhanced", "proof", "agency" ], "additionalProperties": false }, "countries": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "iso2": { "type": [ "string", "null" ] }, "recognised": { "type": "boolean" }, "period": { "type": "string" }, "covered": { "type": "boolean" }, "dates": { "type": "object", "description": "The years used: assumed range, whether they were rough or unknown, and the input as sent.", "properties": { "approximate": { "type": "boolean" }, "unknown": { "type": "boolean" }, "assumedFrom": { "type": [ "integer", "null" ] }, "assumedTo": { "type": [ "integer", "null" ] }, "asSent": { "type": "array", "items": { "type": "string" } } }, "required": [ "approximate", "unknown", "assumedFrom", "assumedTo", "asSent" ], "additionalProperties": false }, "answersFor": { "type": "object", "description": "The kind of pension this answer is about: state, workplace, provident (a provident fund account such as EPF or CPF) or personal, read from pensionType, the question, or a named employer.", "properties": { "kind": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ] }, "readFrom": { "type": [ "string", "null" ], "enum": [ "pensionType", "question", "employer", null ] }, "matched": { "type": "array", "items": { "type": "string" } }, "note": { "type": [ "string", "null" ] } }, "required": [ "kind", "readFrom" ], "additionalProperties": false }, "likelyToExist": { "type": "object", "properties": { "assessment": { "type": "string", "description": "An inference from the dates and facts given, never a finding: for example \"Your dates suggest an entitlement is likely.\"" }, "why": { "type": [ "object", "null" ], "description": "The sourced fact the verdict rests on, valid for the person's period and facts; a rule that does not apply to them is never quoted.", "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The publisher or document the fact comes from." }, "read": { "type": "string", "description": "The date we read the source, for example 7 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false }, "scheme": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ] }, "description": "The scheme the fact is about: state (state pension), workplace (workplace or occupational pension), provident (a national provident fund account) or personal (personal pension)." }, "process": { "type": "string", "enum": [ "tracing", "record", "payment" ], "description": "What the fact is about: tracing (finding which scheme or fund holds it), record (seeing your record or forecast) or payment (applying for payment)." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "source": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "quote": { "type": "string", "description": "Verbatim words from the source." }, "read": { "type": "string" }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "url", "read" ], "additionalProperties": false }, "description": "The stored rows this sentence restates, each with the page it was read on, the words on that page and the date we read it." } }, "required": [ "text", "source", "read", "scheme" ], "additionalProperties": false }, "level": { "type": "string", "enum": [ "likely", "depends", "unlikely", "not_assessed" ] }, "reasons": { "type": "array", "items": { "type": "object", "description": "A stored fact with the source it came from and the date we read that source. Null when we hold no sourced line.", "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The publisher or document the fact comes from." }, "read": { "type": "string", "description": "The date we read the source, for example 7 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false }, "scheme": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ] }, "description": "The scheme the fact is about: state (state pension), workplace (workplace or occupational pension), provident (a national provident fund account) or personal (personal pension)." }, "process": { "type": "string", "enum": [ "tracing", "record", "payment" ], "description": "What the fact is about: tracing (finding which scheme or fund holds it), record (seeing your record or forecast) or payment (applying for payment)." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "source": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "quote": { "type": "string", "description": "Verbatim words from the source." }, "read": { "type": "string" }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "url", "read" ], "additionalProperties": false }, "description": "The stored rows this sentence restates, each with the page it was read on, the words on that page and the date we read it." } }, "required": [ "text", "source", "read", "scheme" ], "additionalProperties": false }, "description": "Every sourced fact the verdict rests on." }, "dependsOn": { "type": [ "string", "null" ], "description": "What the verdict depends on when it is not settled." } }, "required": [ "assessment", "why" ], "additionalProperties": false }, "freeOfficialRoute": { "type": "array", "items": { "type": "object", "description": "An official body's contact details, read from its own page on the date given. email is null when the page publishes none; emailNote then says so and online gives the official service or form.", "properties": { "id": { "type": "string" }, "iso2": { "type": "string" }, "institution": { "type": "string" }, "role": { "type": "string" }, "website": { "type": "string", "format": "uri" }, "contactPage": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "emailNote": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "phoneFromAbroad": { "type": [ "string", "null" ] }, "hours": { "type": [ "string", "null" ] }, "post": { "type": [ "string", "null" ] }, "online": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "required": [ "name", "url" ], "additionalProperties": false }, "source": { "type": "string" }, "read": { "type": "string" }, "quote": { "type": [ "string", "null" ] }, "scheme": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ] }, "description": "The scheme the fact is about: state (state pension), workplace (workplace or occupational pension), provident (a national provident fund account) or personal (personal pension)." }, "process": { "type": "array", "items": { "type": "string", "enum": [ "tracing", "record", "payment" ], "description": "What the fact is about: tracing (finding which scheme or fund holds it), record (seeing your record or forecast) or payment (applying for payment)." }, "description": "What the route does: tracing, record or payment." }, "fromAbroad": { "type": "object", "description": "Whether the route works for a person living abroad, as our directory or the body's own page records it, with the note behind it.", "properties": { "verdict": { "type": "string", "enum": [ "yes", "conditional", "mostly_in_country", "not_stated" ] }, "note": { "type": [ "string", "null" ] } }, "required": [ "verdict", "note" ], "additionalProperties": false }, "abroadOnly": { "type": "boolean", "description": "Present and true for a route that exists for people living OUTSIDE the country (e.g. the UK International Pension Centre); it is dropped for a person who resides in that country." } }, "required": [ "id", "iso2", "institution", "role", "website", "contactPage", "email", "emailNote", "phone", "phoneFromAbroad", "hours", "post", "online", "source", "read", "quote" ], "additionalProperties": false }, "description": "The official free routes, first and never empty for a covered country: each official body or service with what it does (role), the scheme it covers, whether it works from abroad, and the website, email, phone and post we read on its own page with the date. Our report is only what we add on top." }, "contactAbroad": { "type": [ "object", "null" ], "description": "The official contact page for people living abroad, as a link, with the body it belongs to, the scheme and the date we read it. Telephone numbers, emails and postal addresses are report content and are never returned by the free tools. Null only when we hold no official route.", "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The publisher or document the fact comes from." }, "read": { "type": "string", "description": "The date we read the source, for example 7 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false }, "scheme": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ] }, "description": "The scheme the fact is about: state (state pension), workplace (workplace or occupational pension), provident (a national provident fund account) or personal (personal pension)." }, "process": { "type": "string", "enum": [ "tracing", "record", "payment" ], "description": "What the fact is about: tracing (finding which scheme or fund holds it), record (seeing your record or forecast) or payment (applying for payment)." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "source": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "quote": { "type": "string", "description": "Verbatim words from the source." }, "read": { "type": "string" }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "url", "read" ], "additionalProperties": false }, "description": "The stored rows this sentence restates, each with the page it was read on, the words on that page and the date we read it." }, "url": { "type": "string", "format": "uri", "description": "The official contact page." } }, "required": [ "text", "source", "read", "scheme" ], "additionalProperties": false }, "whatIsHardFromAbroad": { "type": "array", "items": { "type": "object", "description": "A stored fact with the source it came from and the date we read that source. Null when we hold no sourced line.", "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The publisher or document the fact comes from." }, "read": { "type": "string", "description": "The date we read the source, for example 7 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false }, "scheme": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ] }, "description": "The scheme the fact is about: state (state pension), workplace (workplace or occupational pension), provident (a national provident fund account) or personal (personal pension)." }, "process": { "type": "string", "enum": [ "tracing", "record", "payment" ], "description": "What the fact is about: tracing (finding which scheme or fund holds it), record (seeing your record or forecast) or payment (applying for payment)." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "source": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "quote": { "type": "string", "description": "Verbatim words from the source." }, "read": { "type": "string" }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "url", "read" ], "additionalProperties": false }, "description": "The stored rows this sentence restates, each with the page it was read on, the words on that page and the date we read it." } }, "required": [ "text", "source", "read", "scheme", "process" ], "additionalProperties": false }, "description": "What is hard from abroad, one fact per scheme and process (tracing, record, payment), each with its source and read date. Honest and specific: what a person living abroad meets on the free route, and the route that works where we hold one. Never an absolute." }, "reportAdds": { "type": "array", "items": { "type": "string" }, "description": "What our report adds for this country beyond the official free routes, as sentences to pass on: which workplace or second pillar funds or insurers hold the pensions, the successor of any renamed, merged or bought out employer or scheme, one sourced contact route per holder, and the work we take off the person. Never the state pension holder alone." }, "whySelfServiceFailsFromAbroad": { "type": [ "object", "null" ], "description": "Deprecated from 1.11.0 and removed in the next version: read whatIsHardFromAbroad. whySelfServiceFailsFromAbroad now carries the first whatIsHardFromAbroad fact, with the same honest wording.", "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The publisher or document the fact comes from." }, "read": { "type": "string", "description": "The date we read the source, for example 7 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "read" ], "additionalProperties": false }, "datedObligation": { "type": [ "object", "null" ], "description": "A stored fact with the source it came from and the date we read that source. Null when we hold no sourced line.", "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The publisher or document the fact comes from." }, "read": { "type": "string", "description": "The date we read the source, for example 7 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false }, "scheme": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ] }, "description": "The scheme the fact is about: state (state pension), workplace (workplace or occupational pension), provident (a national provident fund account) or personal (personal pension)." }, "process": { "type": "string", "enum": [ "tracing", "record", "payment" ], "description": "What the fact is about: tracing (finding which scheme or fund holds it), record (seeing your record or forecast) or payment (applying for payment)." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "source": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "quote": { "type": "string", "description": "Verbatim words from the source." }, "read": { "type": "string" }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "url", "read" ], "additionalProperties": false }, "description": "The stored rows this sentence restates, each with the page it was read on, the words on that page and the date we read it." } }, "required": [ "text", "source", "read", "scheme" ], "additionalProperties": false }, "toConfirm": { "type": [ "string", "null" ] }, "ifDatesDiffer": { "type": "array", "description": "Dates that change the answer if the real dates differ from the ones given, each with what applies before and after and its sources.", "items": { "type": "object", "properties": { "date": { "type": "string" }, "ifBefore": { "type": "string" }, "ifAfter": { "type": "string" }, "why": { "type": "array", "items": { "type": "object", "description": "A fact with its source, the page it was read on, the words on that page and the date we read it.", "properties": { "text": { "type": "string" }, "source": { "type": "string" }, "read": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "quote": { "type": "string", "description": "Verbatim words from the source." } }, "required": [ "text", "source", "read" ], "additionalProperties": false } } }, "required": [ "date", "ifBefore", "ifAfter", "why" ], "additionalProperties": false } }, "employers": { "type": "array", "items": { "type": "string" } }, "employerLineage": { "type": "array", "description": "Sourced renames, sales and mergers of the employers named for this country, free: what the free route does not follow.", "items": { "type": "object", "properties": { "oldName": { "type": "string" }, "newName": { "type": "string" }, "kind": { "type": "string", "enum": [ "rename", "sale", "merger" ] }, "since": { "type": "integer" }, "iso2": { "type": "string" }, "text": { "type": "string" }, "source": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "quote": { "type": "string" }, "read": { "type": "string" } }, "required": [ "oldName", "newName", "kind", "since", "iso2", "text", "source", "url", "quote", "read" ], "additionalProperties": false } }, "holderTeaser": { "type": "object", "description": "The current holder of the workplace pension for a named employer and period, from our verified records, period-correct. Identification only: naming the holder is not a statement that you are a member; whether it holds benefits for you, the member contact process and the value are confirmed in the report.", "properties": { "employer": { "type": "string" }, "holder": { "type": "string", "description": "The scheme or fund that holds the workplace pension." }, "register": { "type": "string", "description": "The official register number, where the country keeps one (DNB in the Netherlands, FSMA in Belgium)." }, "insurer": { "type": "string", "description": "An insurer the benefits are insured with or moving to (a buy-in or buy-out); the scheme is still named." }, "note": { "type": "string", "description": "A caveat that keeps the teaser honest, such as a staff-type or era split." }, "basis": { "type": "string" }, "source": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "read": { "type": "string" }, "quote": { "type": "string", "description": "Verbatim words from the source, where one was fetched." } }, "required": [ "employer", "holder", "basis", "source", "url", "read" ], "additionalProperties": false }, "employerNote": { "type": "string", "description": "Present when an employer was named but we hold no sourced scheme for it: we say plainly that finding the scheme is the report's job, and never assert the employer has operations anywhere." }, "valueTeaser": { "type": "object", "description": "A free value estimate for the years given, only where a sourced formula is stored: a range or ceiling, labelled as an estimate with its source; not the person's entitlement. The exact figure is in the report.", "properties": { "estimate": { "type": "string" }, "basis": { "type": "string" }, "source": { "type": "string" }, "read": { "type": "string" }, "label": { "type": "string" }, "scheme": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ] }, "description": "The scheme the fact is about: state (state pension), workplace (workplace or occupational pension), provident (a national provident fund account) or personal (personal pension)." } }, "required": [ "estimate", "basis", "source", "read", "label", "scheme" ], "additionalProperties": false }, "periodFacts": { "type": "array", "description": "Stored rows whose dates fit the period given and the birth year where one was sent, or, without a period, the rows in force today: each with its source, the page it was read on, the words on that page, the date we read it, and the dates the rule covers (null: the source states no start or end). A row about years before a scheme began is never listed.", "items": { "type": "object", "properties": { "text": { "type": "string" }, "source": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "quote": { "type": "string", "description": "Verbatim words from the source." }, "read": { "type": "string" }, "scheme": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ] }, "description": "The scheme the fact is about: state (state pension), workplace (workplace or occupational pension), provident (a national provident fund account) or personal (personal pension)." }, "topic": { "type": "string", "enum": [ "start", "money", "qualifying", "vesting", "value" ] }, "validFrom": { "type": [ "string", "null" ] }, "validTo": { "type": [ "string", "null" ] }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "url", "read", "scheme", "topic", "validFrom", "validTo" ], "additionalProperties": false } }, "livesHere": { "type": "boolean", "description": "True when countryOfResidence is this country: what is hard from abroad does not apply." }, "workplacePension": { "type": "object", "description": "For an employer we researched by hand: what the employer became and the workplace pension plan for its people, each fact with its source page, verbatim quote and read date, the plan's published contact, and our independence line. Identification only: a plan named here is not a statement that a given person is a member.", "properties": { "employer": { "type": "string" }, "confidence": { "type": "number", "description": "How closely the name sent matches this employer, 0 to 1." }, "history": { "type": "array", "items": { "type": "object", "description": "A fact with its source, the page it was read on, the words on that page and the date we read it.", "properties": { "text": { "type": "string" }, "source": { "type": "string" }, "read": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "quote": { "type": "string", "description": "Verbatim words from the source." } }, "required": [ "text", "source", "read" ], "additionalProperties": false } }, "schemes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "registrationNumber": { "type": [ "string", "null" ] }, "facts": { "type": "array", "items": { "type": "object", "description": "A fact with its source, the page it was read on, the words on that page and the date we read it.", "properties": { "text": { "type": "string" }, "source": { "type": "string" }, "read": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "quote": { "type": "string", "description": "Verbatim words from the source." } }, "required": [ "text", "source", "read" ], "additionalProperties": false } }, "contact": { "type": [ "object", "null" ], "properties": { "role": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "post": { "type": [ "string", "null" ] }, "hours": { "type": [ "string", "null" ] }, "sourceUrl": { "type": "string" }, "read": { "type": "string" }, "quote": { "type": "string" } }, "required": [ "role", "email", "phone", "post", "hours", "sourceUrl", "read", "quote" ], "additionalProperties": false }, "independence": { "type": "string" } }, "required": [ "name", "registrationNumber", "facts", "contact", "independence" ], "additionalProperties": false } }, "caveat": { "type": "string" } }, "required": [ "employer", "confidence", "history", "schemes", "caveat" ], "additionalProperties": false }, "otherPensionFacts": { "type": "object", "description": "Facts we hold for this country about another kind of pension than the one asked about, labelled.", "properties": { "kind": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ] }, "whatTheMoneyIsWorth": { "type": [ "object", "null" ], "description": "A stored fact with the source it came from and the date we read that source. Null when we hold no sourced line.", "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The publisher or document the fact comes from." }, "read": { "type": "string", "description": "The date we read the source, for example 7 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false }, "scheme": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ] }, "description": "The scheme the fact is about: state (state pension), workplace (workplace or occupational pension), provident (a national provident fund account) or personal (personal pension)." }, "process": { "type": "string", "enum": [ "tracing", "record", "payment" ], "description": "What the fact is about: tracing (finding which scheme or fund holds it), record (seeing your record or forecast) or payment (applying for payment)." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "source": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "quote": { "type": "string", "description": "Verbatim words from the source." }, "read": { "type": "string" }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "url", "read" ], "additionalProperties": false }, "description": "The stored rows this sentence restates, each with the page it was read on, the words on that page and the date we read it." } }, "required": [ "text", "source", "read", "scheme" ], "additionalProperties": false }, "whatIsHardFromAbroad": { "type": "array", "items": { "type": "object", "description": "A stored fact with the source it came from and the date we read that source. Null when we hold no sourced line.", "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The publisher or document the fact comes from." }, "read": { "type": "string", "description": "The date we read the source, for example 7 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false }, "scheme": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ] }, "description": "The scheme the fact is about: state (state pension), workplace (workplace or occupational pension), provident (a national provident fund account) or personal (personal pension)." }, "process": { "type": "string", "enum": [ "tracing", "record", "payment" ], "description": "What the fact is about: tracing (finding which scheme or fund holds it), record (seeing your record or forecast) or payment (applying for payment)." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "source": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "quote": { "type": "string", "description": "Verbatim words from the source." }, "read": { "type": "string" }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "url", "read" ], "additionalProperties": false }, "description": "The stored rows this sentence restates, each with the page it was read on, the words on that page and the date we read it." } }, "required": [ "text", "source", "read", "scheme", "process" ], "additionalProperties": false }, "description": "What is hard from abroad, one fact per scheme and process (tracing, record, payment), each with its source and read date. Honest and specific: what a person living abroad meets on the free route, and the route that works where we hold one. Never an absolute." }, "whySelfServiceFailsFromAbroad": { "type": [ "object", "null" ], "description": "Deprecated from 1.11.0 and removed in the next version: read whatIsHardFromAbroad. whySelfServiceFailsFromAbroad now carries the first whatIsHardFromAbroad fact, with the same honest wording.", "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The publisher or document the fact comes from." }, "read": { "type": "string", "description": "The date we read the source, for example 7 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "read" ], "additionalProperties": false } }, "required": [ "kind", "whatTheMoneyIsWorth", "whySelfServiceFailsFromAbroad" ], "additionalProperties": false }, "unclaimedMoney": { "type": "object", "description": "Where dormant pension money in this country moves to a body that holds unclaimed money: the exact conditions as they apply to this period, the official free search and the body's contact details, each sourced and dated. Absent where it does not apply or we hold nothing verified.", "properties": { "body": { "type": "string" }, "when": { "type": "string" }, "conditions": { "type": "array", "items": { "type": "object", "description": "A fact with its source, the page it was read on, the words on that page and the date we read it.", "properties": { "text": { "type": "string" }, "source": { "type": "string" }, "read": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "quote": { "type": "string", "description": "Verbatim words from the source." } }, "required": [ "text", "source", "read" ], "additionalProperties": false } }, "search": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "note": { "type": [ "string", "null" ] } }, "required": [ "name", "url", "note" ], "additionalProperties": false }, "contact": { "type": [ "object", "null" ], "description": "An official body's contact details, read from its own page on the date given. email is null when the page publishes none; emailNote then says so and online gives the official service or form.", "properties": { "id": { "type": "string" }, "iso2": { "type": "string" }, "institution": { "type": "string" }, "role": { "type": "string" }, "website": { "type": "string", "format": "uri" }, "contactPage": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "emailNote": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "phoneFromAbroad": { "type": [ "string", "null" ] }, "hours": { "type": [ "string", "null" ] }, "post": { "type": [ "string", "null" ] }, "online": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "required": [ "name", "url" ], "additionalProperties": false }, "source": { "type": "string" }, "read": { "type": "string" }, "quote": { "type": [ "string", "null" ] }, "scheme": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ] }, "description": "The scheme the fact is about: state (state pension), workplace (workplace or occupational pension), provident (a national provident fund account) or personal (personal pension)." }, "process": { "type": "array", "items": { "type": "string", "enum": [ "tracing", "record", "payment" ], "description": "What the fact is about: tracing (finding which scheme or fund holds it), record (seeing your record or forecast) or payment (applying for payment)." }, "description": "What the route does: tracing, record or payment." }, "fromAbroad": { "type": "object", "description": "Whether the route works for a person living abroad, as our directory or the body's own page records it, with the note behind it.", "properties": { "verdict": { "type": "string", "enum": [ "yes", "conditional", "mostly_in_country", "not_stated" ] }, "note": { "type": [ "string", "null" ] } }, "required": [ "verdict", "note" ], "additionalProperties": false }, "abroadOnly": { "type": "boolean", "description": "Present and true for a route that exists for people living OUTSIDE the country (e.g. the UK International Pension Centre); it is dropped for a person who resides in that country." } }, "required": [ "id", "iso2", "institution", "role", "website", "contactPage", "email", "emailNote", "phone", "phoneFromAbroad", "hours", "post", "online", "source", "read", "quote" ], "additionalProperties": false }, "contactNote": { "type": [ "string", "null" ] }, "more": { "type": "array", "items": { "type": "object", "description": "A fact with its source, the page it was read on, the words on that page and the date we read it.", "properties": { "text": { "type": "string" }, "source": { "type": "string" }, "read": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "quote": { "type": "string", "description": "Verbatim words from the source." } }, "required": [ "text", "source", "read" ], "additionalProperties": false } } }, "required": [ "body", "when", "conditions", "search", "contact", "contactNote", "more" ], "additionalProperties": false }, "tier": { "type": "string", "enum": [ "mapped" ], "description": "Present for a mapped country: one we have mapped but not yet researched in depth." }, "mapped": { "type": "object", "description": "For a mapped country only: the institution that pays the contributory old age pension, its website as a bare domain, its official route to contact it from abroad, and which researched countries it has a social security agreement with, each with the domain it was read on and the date. Mapped: we name the institution and the official route; we have not yet researched this country in depth.", "properties": { "note": { "type": "string", "enum": [ "Mapped: we name the institution and the official route; we have not yet researched this country in depth.", "بلد مرصود: نذكر المؤسسة والطريق الرسمي؛ لم نبحث هذا البلد بعمق حتى الآن.", "Kortlagt land: vi navngiver institutionen og den officielle vej; vi har endnu ikke undersøgt dette land i dybden.", "Erfasstes Land: Wir nennen die Institution und den offiziellen Weg; dieses Land haben wir noch nicht vertieft recherchiert.", "País cartografiado: nombramos la institución y la vía oficial; todavía no hemos investigado este país en profundidad.", "کشور نقشه‌برداری‌شده: نهاد و راه رسمی را نام می‌بریم؛ هنوز این کشور را به‌طور عمیق بررسی نکرده‌ایم.", "Pays cartographié : nous nommons l'institution et la voie officielle ; nous n'avons pas encore étudié ce pays en profondeur.", "मैप किया गया देश: हम संस्था और आधिकारिक रास्ते का नाम बताते हैं; हमने अभी तक इस देश पर गहराई से शोध नहीं किया है।", "Negara terpetakan: kami menyebutkan lembaga dan jalur resminya; kami belum meneliti negara ini secara mendalam.", "Paese mappato: indichiamo l'istituto e la via ufficiale; non abbiamo ancora studiato a fondo questo paese.", "マッピング済みの国：機関と公式の経路をお示しします。この国はまだ詳しく調査していません。", "매핑된 국가: 기관과 공식 경로를 알려 드립니다. 이 국가는 아직 심층 조사하지 않았습니다.", "Kartlagt land: vi navngir institusjonen og den offisielle veien; vi har ennå ikke undersøkt dette landet i dybden.", "In kaart gebracht land: wij noemen de instelling en de officiële route; dit land hebben wij nog niet diepgaand onderzocht.", "Kraj zmapowany: podajemy instytucję i oficjalną drogę; tego kraju nie zbadaliśmy jeszcze dogłębnie.", "País mapeado: indicamos a instituição e a via oficial; ainda não estudámos este país em profundidade.", "País mapeado: indicamos a instituição e a via oficial; ainda não estudamos este país em profundidade.", "Țară cartografiată: numim instituția și calea oficială; nu am cercetat încă în profunzime această țară.", "Страна нанесена на карту: мы называем учреждение и официальный путь; эту страну мы ещё не исследовали углублённо.", "Kartlagt land: vi namnger institutionen och den officiella vägen; vi har ännu inte undersökt det här landet på djupet.", "ประเทศที่จัดทำแผนที่แล้ว: เราระบุหน่วยงานและช่องทางทางการ แต่ยังไม่ได้ศึกษาประเทศนี้อย่างลึกซึ้ง", "Bansang naimapa: binabanggit namin ang institusyon at ang opisyal na daan; hindi pa namin lubusang sinasaliksik ang bansang ito.", "Haritalanmış ülke: kurumu ve resmi yolu belirtiyoruz; bu ülkeyi henüz derinlemesine araştırmadık.", "已梳理国家：我们列出该机构及官方途径；我们尚未深入研究这个国家。", "Đã lập bản đồ: chúng tôi nêu tên cơ quan và con đường chính thức; chúng tôi chưa nghiên cứu sâu quốc gia này.", "Країну нанесено на мапу: ми називаємо установу та офіційний шлях; цю країну ми ще не досліджували поглиблено.", "Страната е картографирана: посочваме институцията и официалния път; все още не сме проучили задълбочено тази страна." ], "description": "The honest line, in the language served." }, "institutions": { "type": "array", "items": { "type": "object", "properties": { "nameEn": { "type": "object", "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The domain of the official page the fact was read on." }, "read": { "type": "string", "description": "The date we read that page, for example 13 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "read" ], "additionalProperties": false }, "nameNative": { "type": [ "object", "null" ], "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The domain of the official page the fact was read on." }, "read": { "type": "string", "description": "The date we read that page, for example 13 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "read" ], "additionalProperties": false }, "website": { "type": [ "object", "null" ], "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The domain of the official page the fact was read on." }, "read": { "type": "string", "description": "The date we read that page, for example 13 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "read" ], "additionalProperties": false, "description": "The official website as its bare domain, never a link." }, "contactFromAbroad": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "form", "postal", "email" ] }, "detail": { "type": "string", "description": "The form name, the postal address as published, or the email address." }, "source": { "type": "string" }, "read": { "type": "string" } }, "required": [ "kind", "detail", "source", "read" ], "additionalProperties": false } } }, "required": [ "nameEn", "nameNative", "website", "contactFromAbroad" ], "additionalProperties": false } }, "agreements": { "type": "array", "items": { "type": "object", "properties": { "iso2": { "type": "string" }, "country": { "type": "string", "description": "A researched country this one has a social security agreement with." }, "source": { "type": "string" }, "read": { "type": "string" } }, "required": [ "iso2", "country", "source", "read" ], "additionalProperties": false } }, "agreementListsRead": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The domain of the official page the fact was read on." }, "read": { "type": "string", "description": "The date we read that page, for example 13 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "read" ], "additionalProperties": false }, "description": "The official agreement lists we read, so an absent agreement is itself sourced." }, "gaps": { "type": "array", "items": { "type": "string" }, "description": "Facts we could not read on an official page. Recurring sentences are served in the language asked for; the rest stay in English." } }, "required": [ "note", "institutions", "agreements", "agreementListsRead", "gaps" ], "additionalProperties": false }, "localName": { "type": "string", "description": "The country name in the language served, from Unicode CLDR. Present only for a language other than English." } }, "required": [ "country", "iso2", "recognised", "period", "dates", "covered", "likelyToExist", "whySelfServiceFailsFromAbroad", "contactAbroad", "datedObligation", "toConfirm", "ifDatesDiffer", "employers" ], "additionalProperties": false } }, "next_step": { "type": "object", "description": "What we add to the free official route, as one structured field built from the finding: one line to pass on, the pre-filled order link with a source tag, the tier, the country and the fee from our price config. Country tier for one or two likely countries; Global only when three or more countries are likely. Absent when the result found nothing in a country we research, or names only mapped countries.", "properties": { "line": { "type": "string", "description": "One line to pass on to the person, with the fee." }, "order_url": { "type": "string", "format": "uri", "description": "Our order page with tier and countries filled in and utm_source=connector, utm_medium=mcp, utm_campaign=. Never personal data." }, "tier": { "type": "string", "enum": [ "country", "global" ] }, "country": { "type": "string", "description": "ISO 3166 alpha-2 code of the country, or the first of them." }, "countries": { "type": "array", "items": { "type": "string" }, "description": "Every country the step covers, ISO codes." }, "price_usd": { "type": "integer", "description": "The fee in whole US dollars, from our price config." }, "refund": { "type": "string", "description": "The refund promise, from our pricing config." }, "refund_url": { "type": "string", "format": "uri", "description": "The page that defines the refund promise." }, "compare": { "type": "object", "description": "For two likely countries: two Country reports against one Global report, both prices from our config. Global is best from 3 countries.", "properties": { "country_reports_usd": { "type": "integer" }, "global_usd": { "type": "integer" }, "recommended": { "type": "string", "enum": [ "country" ] }, "reason": { "type": "string" } }, "required": [ "country_reports_usd", "global_usd", "recommended", "reason" ], "additionalProperties": false } }, "required": [ "line", "order_url", "tier", "country", "countries", "price_usd", "refund", "refund_url" ], "additionalProperties": false }, "language": { "type": "object", "description": "Present when language was sent: the language served, its own name, and labels for source, read date, translation and original in that language. Our sentences in this result are translations of our own wording, review recommended.", "properties": { "requested": { "type": "string", "description": "The language as sent, when it reads as a language tag; empty otherwise." }, "served": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "name": { "type": "string" }, "supported": { "type": "boolean", "description": "False when the language sent is not one of ours; the result is then in English." }, "note": { "type": [ "string", "null" ], "description": "Why the result is in English, when the language sent is not one we serve." }, "ourWording": { "type": "string", "description": "In the served language: these are translations of our own wording, review recommended." }, "facts": { "type": "string", "description": "In the served language: facts, numbers and dates are served exactly as stored." }, "labels": { "type": "object", "properties": { "source": { "type": "string" }, "read": { "type": "string" }, "translation": { "type": "string" }, "original": { "type": "string" } }, "required": [ "source", "read", "translation", "original" ], "additionalProperties": false } }, "required": [ "requested", "served", "name", "supported", "note", "ourWording", "facts", "labels" ], "additionalProperties": false }, "sample_report": { "type": "string", "format": "uri", "description": "Our sample report, to read what a report holds before ordering." } }, "required": [ "countries" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input. The error says how to fix the call.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, unknown or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit reached: for this key, or for a widget key, for this key and Origin. Retry after the number of seconds in the Retry-After header." } } } }, "/tools/resolve_employer": { "post": { "operationId": "resolve_employer", "summary": "Place an employer in a country", "description": "Three things about an employer name, typed however the person remembers it.", "x-openai-isConsequential": false, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 200, "description": "The employer name as the person knows it, ideally with its legal form and city, for example \"Shell Nederland B.V.\" or \"Deutsche Bank Frankfurt\"." }, "country": { "type": "string", "maxLength": 80, "description": "Optional. The country the person worked in for this employer, as a name, alias or ISO code. Matches are then taken from that country only, and a name we do not hold there is said to be not found rather than matched elsewhere." }, "language": { "type": "string", "minLength": 2, "maxLength": 35, "description": "Optional. The language for our own sentences (notes, offer, labels, gap and register sentences), as an ISO 639-1 code: en, ar, da, de, es, fa, fr, hi, id, it, ja, ko, nb, nl, pl, pt, pt-BR, ro, ru, sv, th, tl, tr, zh, vi, uk, bg. Default en. pt is European Portuguese, pt-BR Brazilian, zh Simplified Chinese. Facts, numbers, dates, names and authority answers stay exactly as stored; a fact translation appears only from our committed table, marked translation: true. An unknown code is answered in English with a note." } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Result. A result for researched countries ends with the report offer and an order link built for them; a result naming only mapped countries carries neither.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "resolved": { "type": "boolean" }, "country": { "type": [ "string", "null" ] }, "iso2": { "type": [ "string", "null" ] }, "covered": { "type": "boolean", "description": "True when the country is one we cover." }, "candidates": { "type": "array", "items": { "type": "string" }, "description": "Countries the evidence allows when it does not settle on one." }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "country", "recorded", "city", "nationality", "suffix" ] }, "matched": { "type": "string" }, "countries": { "type": "array", "items": { "type": "string" } } }, "required": [ "kind", "matched", "countries" ], "additionalProperties": false } }, "reason": { "type": "string" }, "normalisedName": { "type": "string", "description": "The name as we compare it: no city, country, legal form, punctuation or case. The name sent is kept as sent." }, "matches": { "type": "array", "description": "Employers we hold that the name may mean, best first, each with its confidence and the register facts it carries.", "items": { "type": "object", "properties": { "employer": { "type": "string" }, "iso2": { "type": "string" }, "country": { "type": "string" }, "confidence": { "type": "number" }, "from": { "type": "string", "enum": [ "history", "directory" ] }, "page": { "type": [ "string", "null" ] }, "lei": { "type": [ "string", "null" ] }, "facts": { "type": "array", "items": { "type": [ "object", "null" ], "description": "A stored fact with the source it came from and the date we read that source. Null when we hold no sourced line.", "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The publisher or document the fact comes from." }, "read": { "type": "string", "description": "The date we read the source, for example 7 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "read" ], "additionalProperties": false } }, "source": { "type": "string" } }, "required": [ "employer", "iso2", "country", "confidence", "from", "page", "lei", "facts", "source" ], "additionalProperties": false } }, "citySource": { "type": "object", "description": "The cities read in the name and where we read their country.", "properties": { "source": { "type": "string" }, "read": { "type": "string" }, "cities": { "type": "array", "items": { "type": "object", "properties": { "city": { "type": "string" }, "iso2": { "type": "string" }, "wikidata": { "type": "string" } }, "required": [ "city", "iso2", "wikidata" ], "additionalProperties": false } } }, "required": [ "source", "read", "cities" ], "additionalProperties": false }, "workplacePension": { "type": "object", "description": "For an employer we researched by hand: what the employer became and the workplace pension plan for its people, each fact with its source page, verbatim quote and read date, the plan's published contact, and our independence line. Identification only: a plan named here is not a statement that a given person is a member.", "properties": { "employer": { "type": "string" }, "confidence": { "type": "number", "description": "How closely the name sent matches this employer, 0 to 1." }, "history": { "type": "array", "items": { "type": "object", "description": "A fact with its source, the page it was read on, the words on that page and the date we read it.", "properties": { "text": { "type": "string" }, "source": { "type": "string" }, "read": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "quote": { "type": "string", "description": "Verbatim words from the source." } }, "required": [ "text", "source", "read" ], "additionalProperties": false } }, "schemes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "registrationNumber": { "type": [ "string", "null" ] }, "facts": { "type": "array", "items": { "type": "object", "description": "A fact with its source, the page it was read on, the words on that page and the date we read it.", "properties": { "text": { "type": "string" }, "source": { "type": "string" }, "read": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "quote": { "type": "string", "description": "Verbatim words from the source." } }, "required": [ "text", "source", "read" ], "additionalProperties": false } }, "contact": { "type": [ "object", "null" ], "properties": { "role": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "post": { "type": [ "string", "null" ] }, "hours": { "type": [ "string", "null" ] }, "sourceUrl": { "type": "string" }, "read": { "type": "string" }, "quote": { "type": "string" } }, "required": [ "role", "email", "phone", "post", "hours", "sourceUrl", "read", "quote" ], "additionalProperties": false }, "independence": { "type": "string" } }, "required": [ "name", "registrationNumber", "facts", "contact", "independence" ], "additionalProperties": false } }, "caveat": { "type": "string" } }, "required": [ "employer", "confidence", "history", "schemes", "caveat" ], "additionalProperties": false }, "freeOfficialRoute": { "type": "array", "items": { "type": "object", "description": "An official body's contact details, read from its own page on the date given. email is null when the page publishes none; emailNote then says so and online gives the official service or form.", "properties": { "id": { "type": "string" }, "iso2": { "type": "string" }, "institution": { "type": "string" }, "role": { "type": "string" }, "website": { "type": "string", "format": "uri" }, "contactPage": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "emailNote": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "phoneFromAbroad": { "type": [ "string", "null" ] }, "hours": { "type": [ "string", "null" ] }, "post": { "type": [ "string", "null" ] }, "online": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "required": [ "name", "url" ], "additionalProperties": false }, "source": { "type": "string" }, "read": { "type": "string" }, "quote": { "type": [ "string", "null" ] }, "scheme": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ] }, "description": "The scheme the fact is about: state (state pension), workplace (workplace or occupational pension), provident (a national provident fund account) or personal (personal pension)." }, "process": { "type": "array", "items": { "type": "string", "enum": [ "tracing", "record", "payment" ], "description": "What the fact is about: tracing (finding which scheme or fund holds it), record (seeing your record or forecast) or payment (applying for payment)." }, "description": "What the route does: tracing, record or payment." }, "fromAbroad": { "type": "object", "description": "Whether the route works for a person living abroad, as our directory or the body's own page records it, with the note behind it.", "properties": { "verdict": { "type": "string", "enum": [ "yes", "conditional", "mostly_in_country", "not_stated" ] }, "note": { "type": [ "string", "null" ] } }, "required": [ "verdict", "note" ], "additionalProperties": false }, "abroadOnly": { "type": "boolean", "description": "Present and true for a route that exists for people living OUTSIDE the country (e.g. the UK International Pension Centre); it is dropped for a person who resides in that country." } }, "required": [ "id", "iso2", "institution", "role", "website", "contactPage", "email", "emailNote", "phone", "phoneFromAbroad", "hours", "post", "online", "source", "read", "quote" ], "additionalProperties": false }, "description": "The official free routes, first and never empty for a covered country: each official body or service with what it does (role), the scheme it covers, whether it works from abroad, and the website, email, phone and post we read on its own page with the date. Our report is only what we add on top." }, "lineage": { "type": "array", "description": "Sourced renames, sales and mergers of the employer, each from an official or company page with a verbatim quote and the date we read it. Never inferred from the name.", "items": { "type": "object", "properties": { "oldName": { "type": "string" }, "newName": { "type": "string" }, "kind": { "type": "string", "enum": [ "rename", "sale", "merger" ] }, "since": { "type": "integer" }, "iso2": { "type": "string" }, "text": { "type": "string" }, "source": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "quote": { "type": "string" }, "read": { "type": "string" } }, "required": [ "oldName", "newName", "kind", "since", "iso2", "text", "source", "url", "quote", "read" ], "additionalProperties": false } }, "currentEntity": { "type": "object", "description": "What the employer is called now, read from official registers (the Global LEI Index, then a national register): renamed, merged, unchanged, ambiguous when several entities carry exactly that name, not_found, or unavailable when the register could not be read. Legal entities only, never people.", "properties": { "status": { "type": "string", "enum": [ "renamed", "merged", "unchanged", "ambiguous", "not_found", "unavailable" ] }, "text": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "kind": { "type": "string" }, "date": { "type": [ "string", "null" ] } }, "required": [ "from", "to", "kind", "date" ], "additionalProperties": false } }, "source": { "type": [ "string", "null" ], "description": "Publisher and register." }, "read": { "type": [ "string", "null" ], "description": "The date we read the register." } }, "required": [ "status", "text", "steps", "source", "read" ], "additionalProperties": false }, "schemeRegister": { "type": [ "object", "null" ], "description": "Where the employer's country lists occupational pension funds, or that it has no such public register. Null when the country is not settled.", "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The publisher or document the fact comes from." }, "read": { "type": "string", "description": "The date we read the source, for example 7 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "read" ], "additionalProperties": false }, "localName": { "type": "string", "description": "The country name in the language served, from Unicode CLDR. Present only for a language other than English." }, "next_step": { "type": "object", "description": "What we add to the free official route, as one structured field built from the finding: one line to pass on, the pre-filled order link with a source tag, the tier, the country and the fee from our price config. Country tier for one or two likely countries; Global only when three or more countries are likely. Absent when the result found nothing in a country we research, or names only mapped countries.", "properties": { "line": { "type": "string", "description": "One line to pass on to the person, with the fee." }, "order_url": { "type": "string", "format": "uri", "description": "Our order page with tier and countries filled in and utm_source=connector, utm_medium=mcp, utm_campaign=. Never personal data." }, "tier": { "type": "string", "enum": [ "country", "global" ] }, "country": { "type": "string", "description": "ISO 3166 alpha-2 code of the country, or the first of them." }, "countries": { "type": "array", "items": { "type": "string" }, "description": "Every country the step covers, ISO codes." }, "price_usd": { "type": "integer", "description": "The fee in whole US dollars, from our price config." }, "refund": { "type": "string", "description": "The refund promise, from our pricing config." }, "refund_url": { "type": "string", "format": "uri", "description": "The page that defines the refund promise." }, "compare": { "type": "object", "description": "For two likely countries: two Country reports against one Global report, both prices from our config. Global is best from 3 countries.", "properties": { "country_reports_usd": { "type": "integer" }, "global_usd": { "type": "integer" }, "recommended": { "type": "string", "enum": [ "country" ] }, "reason": { "type": "string" } }, "required": [ "country_reports_usd", "global_usd", "recommended", "reason" ], "additionalProperties": false } }, "required": [ "line", "order_url", "tier", "country", "countries", "price_usd", "refund", "refund_url" ], "additionalProperties": false }, "language": { "type": "object", "description": "Present when language was sent: the language served, its own name, and labels for source, read date, translation and original in that language. Our sentences in this result are translations of our own wording, review recommended.", "properties": { "requested": { "type": "string", "description": "The language as sent, when it reads as a language tag; empty otherwise." }, "served": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "name": { "type": "string" }, "supported": { "type": "boolean", "description": "False when the language sent is not one of ours; the result is then in English." }, "note": { "type": [ "string", "null" ], "description": "Why the result is in English, when the language sent is not one we serve." }, "ourWording": { "type": "string", "description": "In the served language: these are translations of our own wording, review recommended." }, "facts": { "type": "string", "description": "In the served language: facts, numbers and dates are served exactly as stored." }, "labels": { "type": "object", "properties": { "source": { "type": "string" }, "read": { "type": "string" }, "translation": { "type": "string" }, "original": { "type": "string" } }, "required": [ "source", "read", "translation", "original" ], "additionalProperties": false } }, "required": [ "requested", "served", "name", "supported", "note", "ourWording", "facts", "labels" ], "additionalProperties": false }, "sample_report": { "type": "string", "format": "uri", "description": "Our sample report, to read what a report holds before ordering." } }, "required": [ "name", "resolved", "country", "iso2", "covered", "candidates", "evidence", "reason", "currentEntity", "schemeRegister" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input. The error says how to fix the call.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, unknown or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit for this key reached. Retry after the number of seconds in the Retry-After header." } } } }, "/tools/authority_answer": { "post": { "operationId": "authority_answer", "summary": "Authority answers on the record", "description": "What a national pension institution told us in writing, as published on our answers page: the institution, its answer exactly as published, any translation marked as ours, the date of the reply and the link to that answer on pensionhunter.ai/answers.", "x-openai-isConsequential": false, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "type": "string", "minLength": 2, "maxLength": 200, "description": "One country, as an English name, a native name, a common alias or an ISO 3166 alpha-2 or alpha-3 code, in any case. Examples: Netherlands, Nederland, Holland, NL, NLD; United Kingdom, UK, GB, Britain; Germany, Deutschland, DE." }, "question": { "type": "string", "minLength": 2, "maxLength": 500, "description": "The question in plain words, for example \"Can I deal with this without travelling there?\", \"What do heirs need?\" or \"Do they publish figures on unpaid pensions?\". Matched by keywords to the questions we hold answers to." }, "language": { "type": "string", "minLength": 2, "maxLength": 35, "description": "Optional. The language for our own sentences (notes, offer, labels, gap and register sentences), as an ISO 639-1 code: en, ar, da, de, es, fa, fr, hi, id, it, ja, ko, nb, nl, pl, pt, pt-BR, ro, ru, sv, th, tl, tr, zh, vi, uk, bg. Default en. pt is European Portuguese, pt-BR Brazilian, zh Simplified Chinese. Facts, numbers, dates, names and authority answers stay exactly as stored; a fact translation appears only from our committed table, marked translation: true. An unknown code is answered in English with a note." } }, "required": [ "country", "question" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Result. A result for researched countries ends with the report offer and an order link built for them; a result naming only mapped countries carries neither.", "content": { "application/json": { "schema": { "type": "object", "properties": { "officialContact": { "type": [ "object", "null" ], "description": "For a country we research: the official contact page of its free route, as a link. Contact details themselves are report content.", "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The publisher or document the fact comes from." }, "read": { "type": "string", "description": "The date we read the source, for example 7 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false }, "scheme": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "state", "workplace", "provident", "personal" ] }, "description": "The scheme the fact is about: state (state pension), workplace (workplace or occupational pension), provident (a national provident fund account) or personal (personal pension)." }, "process": { "type": "string", "enum": [ "tracing", "record", "payment" ], "description": "What the fact is about: tracing (finding which scheme or fund holds it), record (seeing your record or forecast) or payment (applying for payment)." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "source": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "quote": { "type": "string", "description": "Verbatim words from the source." }, "read": { "type": "string" }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "url", "read" ], "additionalProperties": false }, "description": "The stored rows this sentence restates, each with the page it was read on, the words on that page and the date we read it." }, "url": { "type": "string", "format": "uri", "description": "The official contact page." } }, "required": [ "text", "source", "read", "scheme" ], "additionalProperties": false }, "query": { "type": "string", "description": "The country string as sent." }, "question": { "type": "string", "description": "The question as sent." }, "country": { "type": "string" }, "iso2": { "type": [ "string", "null" ] }, "recognised": { "type": "boolean", "description": "False when the string is not a country we can read." }, "matched": { "type": "boolean", "description": "True when the question matched at least one published answer." }, "status": { "type": [ "string", "null" ], "enum": [ "answered", "asked_no_answer_yet", "asked_no_answer_published", "replied_no_answer_published", "not_asked", null ], "description": "Where our written questions to the country stand: answered when our answers page publishes an answer from an institution there; asked_no_answer_yet when asked on askedOn, no answer yet; asked_no_answer_published when asked on askedOn and the answer is not published; replied_no_answer_published when the institution replied and nothing is published; not_asked when no dated letter is on our record. Null when the country is not recognised." }, "askedOn": { "type": [ "string", "null" ], "description": "ISO date of our most recent dated letter to the country, or null." }, "askedInstitution": { "type": [ "string", "null" ], "description": "The institution that letter went to. Never a person. Null when none." }, "questionKey": { "type": [ "string", "null" ], "description": "The question topic matched." }, "answers": { "type": "array", "items": { "type": "object", "properties": { "institution": { "type": "string", "description": "The institution that replied. Never a person." }, "questionKey": { "type": "string" }, "question": { "type": "string" }, "questionAsPublished": { "type": "boolean", "description": "True when the question is worded as published on the answers page; false when it is our plain summary of what the passage answers." }, "answer": { "type": [ "object", "null" ], "description": "The answer exactly as published, with the institution as source and the reply date as read date. Null when the passage gives a contact detail, which we publish only on the answers page.", "properties": { "text": { "type": "string" }, "source": { "type": "string", "description": "The publisher or document the fact comes from." }, "read": { "type": "string", "description": "The date we read the source, for example 7 October 2026." }, "translated": { "type": "object", "description": "A translation of the fact above, present only when our committed table holds one for that exact text. The original text stays in text.", "properties": { "language": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "text": { "type": "string" }, "translation": { "type": "boolean", "enum": [ true ] } }, "required": [ "language", "text", "translation" ], "additionalProperties": false } }, "required": [ "text", "source", "read" ], "additionalProperties": false }, "translation": { "type": [ "string", "null" ], "description": "Our English translation, exactly as published, where the answer is in another language or quotes the original. Ours, not the institution's." }, "wording": { "type": "string", "enum": [ "verbatim", "approved by the institution", "our translation", "our summary" ] }, "wordingNote": { "type": "string" }, "withheld": { "type": [ "string", "null" ], "description": "Why the passage is served only on the answers page, or null." }, "date": { "type": "string", "description": "The date of the reply, as published." }, "url": { "type": "string", "format": "uri", "description": "The answer on https://pensionhunter.ai/answers, with its anchor." } }, "required": [ "institution", "questionKey", "question", "questionAsPublished", "answer", "translation", "wording", "wordingNote", "withheld", "date", "url" ], "additionalProperties": false } }, "questions": { "type": "array", "description": "When nothing matched: the questions we hold answers to for this country.", "items": { "type": "object", "properties": { "questionKey": { "type": "string" }, "question": { "type": "string" }, "questionAsPublished": { "type": "boolean" }, "institution": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "required": [ "questionKey", "question", "questionAsPublished", "institution", "url" ], "additionalProperties": false } }, "answersPage": { "type": "string", "format": "uri", "description": "Our answers page, https://pensionhunter.ai/answers." }, "note": { "type": "string" }, "localName": { "type": "string", "description": "The country name in the language served, from Unicode CLDR. Present only for a language other than English." }, "next_step": { "type": "object", "description": "What we add to the free official route, as one structured field built from the finding: one line to pass on, the pre-filled order link with a source tag, the tier, the country and the fee from our price config. Country tier for one or two likely countries; Global only when three or more countries are likely. Absent when the result found nothing in a country we research, or names only mapped countries.", "properties": { "line": { "type": "string", "description": "One line to pass on to the person, with the fee." }, "order_url": { "type": "string", "format": "uri", "description": "Our order page with tier and countries filled in and utm_source=connector, utm_medium=mcp, utm_campaign=. Never personal data." }, "tier": { "type": "string", "enum": [ "country", "global" ] }, "country": { "type": "string", "description": "ISO 3166 alpha-2 code of the country, or the first of them." }, "countries": { "type": "array", "items": { "type": "string" }, "description": "Every country the step covers, ISO codes." }, "price_usd": { "type": "integer", "description": "The fee in whole US dollars, from our price config." }, "refund": { "type": "string", "description": "The refund promise, from our pricing config." }, "refund_url": { "type": "string", "format": "uri", "description": "The page that defines the refund promise." }, "compare": { "type": "object", "description": "For two likely countries: two Country reports against one Global report, both prices from our config. Global is best from 3 countries.", "properties": { "country_reports_usd": { "type": "integer" }, "global_usd": { "type": "integer" }, "recommended": { "type": "string", "enum": [ "country" ] }, "reason": { "type": "string" } }, "required": [ "country_reports_usd", "global_usd", "recommended", "reason" ], "additionalProperties": false } }, "required": [ "line", "order_url", "tier", "country", "countries", "price_usd", "refund", "refund_url" ], "additionalProperties": false }, "language": { "type": "object", "description": "Present when language was sent: the language served, its own name, and labels for source, read date, translation and original in that language. Our sentences in this result are translations of our own wording, review recommended.", "properties": { "requested": { "type": "string", "description": "The language as sent, when it reads as a language tag; empty otherwise." }, "served": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "name": { "type": "string" }, "supported": { "type": "boolean", "description": "False when the language sent is not one of ours; the result is then in English." }, "note": { "type": [ "string", "null" ], "description": "Why the result is in English, when the language sent is not one we serve." }, "ourWording": { "type": "string", "description": "In the served language: these are translations of our own wording, review recommended." }, "facts": { "type": "string", "description": "In the served language: facts, numbers and dates are served exactly as stored." }, "labels": { "type": "object", "properties": { "source": { "type": "string" }, "read": { "type": "string" }, "translation": { "type": "string" }, "original": { "type": "string" } }, "required": [ "source", "read", "translation", "original" ], "additionalProperties": false } }, "required": [ "requested", "served", "name", "supported", "note", "ourWording", "facts", "labels" ], "additionalProperties": false }, "sample_report": { "type": "string", "format": "uri", "description": "Our sample report, to read what a report holds before ordering." } }, "required": [ "query", "question", "country", "iso2", "recognised", "matched", "status", "askedOn", "askedInstitution", "answers", "questions", "answersPage" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input. The error says how to fix the call.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, unknown or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit for this key reached. Retry after the number of seconds in the Retry-After header." } } } }, "/tools/deadline_check": { "post": { "operationId": "deadline_check", "summary": "When does a departure deadline run out", "description": "For a country the person left, and the date they left or, where the clock runs from a death, the date of death: the date our deadline register's rule gives, by adding the period stated in the register row to that date.", "x-openai-isConsequential": false, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "type": "string", "minLength": 2, "maxLength": 80, "description": "The country left: ISO 3166 alpha-2 code or English name, for example \"JP\" or \"Japan\". Call with any value to get the list of countries we hold." }, "event": { "type": "string", "enum": [ "left", "died" ], "description": "\"left\": the date the person left that country. \"died\": the date of death, for clocks that run from a death. Optional when the country has only one." }, "date": { "type": "string", "minLength": 10, "maxLength": 10, "description": "The date, YYYY-MM-DD, not after today." }, "language": { "type": "string", "minLength": 2, "maxLength": 35, "description": "Optional. The language for our own sentences (notes, offer, labels, gap and register sentences), as an ISO 639-1 code: en, ar, da, de, es, fa, fr, hi, id, it, ja, ko, nb, nl, pl, pt, pt-BR, ro, ru, sv, th, tl, tr, zh, vi, uk, bg. Default en. pt is European Portuguese, pt-BR Brazilian, zh Simplified Chinese. Facts, numbers, dates, names and authority answers stay exactly as stored; a fact translation appears only from our committed table, marked translation: true. An unknown code is answered in English with a note." } }, "required": [ "country", "date" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Result. A result for researched countries ends with the report offer and an order link built for them; a result naming only mapped countries carries neither.", "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "type": "string" }, "iso2": { "type": "string" }, "event": { "type": "string", "enum": [ "left", "died" ] }, "date": { "type": "string", "description": "The date sent, YYYY-MM-DD." }, "today": { "type": "string", "description": "The day the result was computed, UTC, YYYY-MM-DD." }, "clocks": { "type": "array", "description": "Dates computed from register rows that state both the start event and the period.", "items": { "type": "object", "properties": { "rowId": { "type": "string", "description": "The row in our deadline register, https://pensionhunter.ai/deadlines." }, "rule": { "type": "string", "description": "The rule, as our register states it." }, "clockStarts": { "type": "string", "description": "What starts the clock, as the register row states it." }, "runsFor": { "type": "string", "description": "How long it runs, as the register row states it." }, "ifMissed": { "type": "string", "description": "What the register row says happens if it is missed." }, "sourceGap": { "type": [ "string", "null" ], "description": "What the official source does not say, as the register row records it." }, "source": { "type": "string", "description": "The domain of the official source." }, "read": { "type": "string", "description": "The date we read the source, YYYY-MM-DD." }, "quote": { "type": "object", "description": "The source's own wording, verbatim, and the English translation stored in our register where the original is not English.", "properties": { "text": { "type": "string" }, "translation": { "type": [ "string", "null" ] } }, "required": [ "text", "translation" ], "additionalProperties": false }, "freeOfficialRoute": { "type": "object", "description": "The free official route, first: the official page this rule was read from (its source), the official steps we hold from that body's own pages, and its contacts where we hold them, each with the page it was read from and the date we read it.", "properties": { "sourcePage": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "read": { "type": "string" } }, "required": [ "url", "read" ], "additionalProperties": false }, "steps": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Our English gloss of the official wording." }, "quote": { "type": "string", "description": "The official wording, verbatim." }, "quoteLang": { "type": "string" }, "publisher": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "read": { "type": "string" } }, "required": [ "text", "quote", "quoteLang", "publisher", "url", "read" ], "additionalProperties": false } }, "institution": { "type": [ "string", "null" ] }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "phone", "email", "form", "post", "web", "office" ] }, "value": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "sourceUrl": { "type": "string", "format": "uri" }, "read": { "type": "string" } }, "required": [ "kind", "value", "note", "sourceUrl", "read" ], "additionalProperties": false } }, "contactsNote": { "type": [ "string", "null" ], "description": "Set when we hold no checked contact for this body." } }, "required": [ "sourcePage", "steps", "institution", "contacts", "contactsNote" ], "additionalProperties": false }, "kind": { "type": "string", "enum": [ "window_ends", "transfer_from" ], "description": "window_ends: the period to act ends on endsOn. transfer_from: from endsOn the money can be moved away, on the conditions the rule states." }, "periodUsed": { "type": "string", "description": "The words of the register row the period was read from." }, "endsOn": { "type": "string", "description": "The date plus the period, YYYY-MM-DD." }, "status": { "type": "string", "enum": [ "open", "passed" ] }, "daysFromToday": { "type": "integer" } }, "required": [ "rowId", "rule", "clockStarts", "runsFor", "ifMissed", "sourceGap", "source", "read", "quote", "freeOfficialRoute", "kind", "periodUsed", "endsOn", "status", "daysFromToday" ], "additionalProperties": false } }, "rulesWithoutDate": { "type": "array", "description": "Rules we hold for this country and event whose start is not stated or is not the date given: shown with their source, no date.", "items": { "type": "object", "properties": { "rowId": { "type": "string", "description": "The row in our deadline register, https://pensionhunter.ai/deadlines." }, "rule": { "type": "string", "description": "The rule, as our register states it." }, "clockStarts": { "type": "string", "description": "What starts the clock, as the register row states it." }, "runsFor": { "type": "string", "description": "How long it runs, as the register row states it." }, "ifMissed": { "type": "string", "description": "What the register row says happens if it is missed." }, "sourceGap": { "type": [ "string", "null" ], "description": "What the official source does not say, as the register row records it." }, "source": { "type": "string", "description": "The domain of the official source." }, "read": { "type": "string", "description": "The date we read the source, YYYY-MM-DD." }, "quote": { "type": "object", "description": "The source's own wording, verbatim, and the English translation stored in our register where the original is not English.", "properties": { "text": { "type": "string" }, "translation": { "type": [ "string", "null" ] } }, "required": [ "text", "translation" ], "additionalProperties": false }, "freeOfficialRoute": { "type": "object", "description": "The free official route, first: the official page this rule was read from (its source), the official steps we hold from that body's own pages, and its contacts where we hold them, each with the page it was read from and the date we read it.", "properties": { "sourcePage": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "read": { "type": "string" } }, "required": [ "url", "read" ], "additionalProperties": false }, "steps": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Our English gloss of the official wording." }, "quote": { "type": "string", "description": "The official wording, verbatim." }, "quoteLang": { "type": "string" }, "publisher": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "read": { "type": "string" } }, "required": [ "text", "quote", "quoteLang", "publisher", "url", "read" ], "additionalProperties": false } }, "institution": { "type": [ "string", "null" ] }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "phone", "email", "form", "post", "web", "office" ] }, "value": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "sourceUrl": { "type": "string", "format": "uri" }, "read": { "type": "string" } }, "required": [ "kind", "value", "note", "sourceUrl", "read" ], "additionalProperties": false } }, "contactsNote": { "type": [ "string", "null" ], "description": "Set when we hold no checked contact for this body." } }, "required": [ "sourcePage", "steps", "institution", "contacts", "contactsNote" ], "additionalProperties": false }, "whyNoDate": { "type": "string" } }, "required": [ "rowId", "rule", "clockStarts", "runsFor", "ifMissed", "sourceGap", "source", "read", "quote", "freeOfficialRoute", "whyNoDate" ], "additionalProperties": false } }, "arithmetic": { "type": "string", "description": "How the date is worked out." }, "note": { "type": "string", "description": "Identification only; the official body decides." }, "next_step": { "type": "object", "description": "What we add to the free official route, as one structured field built from the finding: one line to pass on, the pre-filled order link with a source tag, the tier, the country and the fee from our price config. Country tier for one or two likely countries; Global only when three or more countries are likely. Absent when the result found nothing in a country we research, or names only mapped countries.", "properties": { "line": { "type": "string", "description": "One line to pass on to the person, with the fee." }, "order_url": { "type": "string", "format": "uri", "description": "Our order page with tier and countries filled in and utm_source=connector, utm_medium=mcp, utm_campaign=. Never personal data." }, "tier": { "type": "string", "enum": [ "country", "global" ] }, "country": { "type": "string", "description": "ISO 3166 alpha-2 code of the country, or the first of them." }, "countries": { "type": "array", "items": { "type": "string" }, "description": "Every country the step covers, ISO codes." }, "price_usd": { "type": "integer", "description": "The fee in whole US dollars, from our price config." }, "refund": { "type": "string", "description": "The refund promise, from our pricing config." }, "refund_url": { "type": "string", "format": "uri", "description": "The page that defines the refund promise." }, "compare": { "type": "object", "description": "For two likely countries: two Country reports against one Global report, both prices from our config. Global is best from 3 countries.", "properties": { "country_reports_usd": { "type": "integer" }, "global_usd": { "type": "integer" }, "recommended": { "type": "string", "enum": [ "country" ] }, "reason": { "type": "string" } }, "required": [ "country_reports_usd", "global_usd", "recommended", "reason" ], "additionalProperties": false } }, "required": [ "line", "order_url", "tier", "country", "countries", "price_usd", "refund", "refund_url" ], "additionalProperties": false }, "language": { "type": "object", "description": "Present when language was sent: the language served, its own name, and labels for source, read date, translation and original in that language. Our sentences in this result are translations of our own wording, review recommended.", "properties": { "requested": { "type": "string", "description": "The language as sent, when it reads as a language tag; empty otherwise." }, "served": { "type": "string", "enum": [ "en", "ar", "da", "de", "es", "fa", "fr", "hi", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sv", "th", "tl", "tr", "zh", "vi", "uk", "bg" ] }, "name": { "type": "string" }, "supported": { "type": "boolean", "description": "False when the language sent is not one of ours; the result is then in English." }, "note": { "type": [ "string", "null" ], "description": "Why the result is in English, when the language sent is not one we serve." }, "ourWording": { "type": "string", "description": "In the served language: these are translations of our own wording, review recommended." }, "facts": { "type": "string", "description": "In the served language: facts, numbers and dates are served exactly as stored." }, "labels": { "type": "object", "properties": { "source": { "type": "string" }, "read": { "type": "string" }, "translation": { "type": "string" }, "original": { "type": "string" } }, "required": [ "source", "read", "translation", "original" ], "additionalProperties": false } }, "required": [ "requested", "served", "name", "supported", "note", "ourWording", "facts", "labels" ], "additionalProperties": false }, "sample_report": { "type": "string", "format": "uri", "description": "Our sample report, to read what a report holds before ordering." } }, "required": [ "country", "iso2", "event", "date", "today", "clocks", "rulesWithoutDate", "arithmetic", "note", "next_step" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input. The error says how to fix the call.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, unknown or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit for this key reached. Retry after the number of seconds in the Retry-After header." } } } } }, "components": { "schemas": {}, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Your Pro API key. Keys are issued on application; apply at https://pensionhunter.ai/developers." } } } }