{ "openapi": "3.1.0", "info": { "title": "Japan PR Guideline Check API", "version": "1.0.0", "description": "Japan revised its permanent residence (永住) guideline on October 1, 2026. Your filing date decides which rules apply: until March 31, 2027 most of the old rules still count (spouses: 3 years of marriage + 1 year in Japan, a 3-year visa counts), but the stricter household-income rule already applies. From April 1, 2027: spouses need 5 + 3 years, intra-company transferee years stop counting, and no trip abroad of 6+ months or 2.5 years in total. Check your dates.\n\nFree, no API key, CORS open. Fair use: about 120 requests per minute per IP. Also available as MCP tools at https://free-agent-tools.vercel.app/mcp" }, "servers": [ { "url": "https://japan-pr-check.vercel.app" } ], "paths": { "/api/check": { "get": { "operationId": "japanPermanentResidencyCheck", "summary": "Which Japan permanent residence (PR, 永住) guideline applies to my filing date, and do I meet its objective factors?", "description": "Japan's Immigration Services Agency revised its permanent residence guideline on 2026-10-01. Filed up to 2026-03-31: 2026-02-24 guideline. Filed 2026-04-01 to 2027-03-31: 2026-02-24 guideline plus the revised income (household income above the Japanese average for the household size) and not-a-public-burden factors (also for cases pending on 2026-10-01). Filed from 2027-04-01: revised guideline in full — spouses of Japanese/PRs need 5 years of marriage + 3 years in Japan (was 3 + 1), children 3 years (was 1), Intra-company Transferee and Employment for Skill Development no longer count as work status, a 3-year period of stay counts as 'longest' only under a narrow transition, and new factors: no single trip abroad of 6+ months or 2.5+ years in total in the last 10 years, Japanese at CEFR B1, projected pension, rules understanding, school attendance. Returns summary (objective_issue / need_more_info / no_objective_blocker — never an approval prediction), the guideline band, checks[] with status (issue/review/unknown/meets/not_considered/info) and official sources, the time requirement with the earliest date you meet it, an old-vs-new filing window for spouse/child routes, absence analysis, key dates with day counts, the ¥200,000 PR fee, notes and a disclaimer.\n\nExample: https://japan-pr-check.vercel.app/api/check?route=spouse&applicationDate=2027-02-15&residenceSince=2025-09-01&marriageDate=2023-06-10&periodOfStay=3y", "parameters": [ { "name": "route", "in": "query", "required": true, "description": "PR route: general (10 years), spouse (of a Japanese national / PR / SPR), child, long_term_resident, refugee, hsp70, hsp80, special_hsp, contribution, special_zone_regional.", "schema": { "type": "string", "description": "PR route: general (10 years), spouse (of a Japanese national / PR / SPR), child, long_term_resident, refugee, hsp70, hsp80, special_hsp, contribution, special_zone_regional.", "enum": [ "general", "spouse", "child", "long_term_resident", "refugee", "hsp70", "hsp80", "special_hsp", "contribution", "special_zone_regional" ] } }, { "name": "applicationDate", "in": "query", "required": false, "description": "YYYY-MM-DD you filed or plan to file. Decides which guideline applies. Default: today in Japan.", "schema": { "type": "string", "description": "YYYY-MM-DD you filed or plan to file. Decides which guideline applies. Default: today in Japan." } }, { "name": "residenceSince", "in": "query", "required": false, "description": "YYYY-MM-DD your continuous residence in Japan began (alternative: yearsInJapan).", "schema": { "type": "string", "description": "YYYY-MM-DD your continuous residence in Japan began (alternative: yearsInJapan)." } }, { "name": "yearsInJapan", "in": "query", "required": false, "description": "Years of continuous residence in Japan at filing (used if residenceSince is not given).", "schema": { "type": "number", "description": "Years of continuous residence in Japan at filing (used if residenceSince is not given).", "minimum": 0, "maximum": 100 } }, { "name": "workOrResidenceYears", "in": "query", "required": false, "description": "General route: continuous years on a qualifying work or residence status (excluding Technical Intern Training, Specified Skilled Worker (i), and from 2027-04-01 also Intra-company Transferee and Employment for Skill Development).", "schema": { "type": "number", "description": "General route: continuous years on a qualifying work or residence status (excluding Technical Intern Training, Specified Skilled Worker (i), and from 2027-04-01 also Intra-company Transferee and Employment for Skill Development).", "minimum": 0, "maximum": 100 } }, { "name": "currentStatus", "in": "query", "required": false, "description": "Current status of residence, to flag statuses that do not count as work status (aliases: gijinkoku, ict, ssw1, titp).", "schema": { "type": "string", "description": "Current status of residence, to flag statuses that do not count as work status (aliases: gijinkoku, ict, ssw1, titp).", "enum": [ "engineer_humanities", "intra_company_transferee", "highly_skilled_professional", "business_manager", "skilled_labor", "specified_skilled_worker_2", "specified_skilled_worker_1", "technical_intern_training", "employment_for_skill_development", "spouse_of_japanese", "spouse_of_permanent_resident", "long_term_resident", "dependent", "student", "designated_activities", "other_work" ] } }, { "name": "periodOfStay", "in": "query", "required": false, "description": "Period of stay on your residence card: 5y, 3y, 1y, 6m, 3m, unlimited, other.", "schema": { "type": "string", "description": "Period of stay on your residence card: 5y, 3y, 1y, 6m, 3m, unlimited, other.", "enum": [ "5y", "3y", "1y", "6m", "3m", "unlimited", "other" ] } }, { "name": "periodExpiry", "in": "query", "required": false, "description": "YYYY-MM-DD your current period of stay expires (needed for the 3-year transition from 2027-04-01).", "schema": { "type": "string", "description": "YYYY-MM-DD your current period of stay expires (needed for the 3-year transition from 2027-04-01)." } }, { "name": "marriageDate", "in": "query", "required": false, "description": "Spouse route: YYYY-MM-DD the substantive marriage began.", "schema": { "type": "string", "description": "Spouse route: YYYY-MM-DD the substantive marriage began." } }, { "name": "qualifyingSince", "in": "query", "required": false, "description": "Special routes: YYYY-MM-DD the qualifying period began (Long-Term Resident status, refugee recognition, HSP points, ...).", "schema": { "type": "string", "description": "Special routes: YYYY-MM-DD the qualifying period began (Long-Term Resident status, refugee recognition, HSP points, ...)." } }, { "name": "trips", "in": "query", "required": false, "description": "Trips abroad in the last 10 years. GET: comma-separated depart_return pairs, e.g. 2024-01-05_2024-03-01,2025-07-01_2026-02-01. POST: array of {depart, return}.", "schema": { "type": "string", "description": "Trips abroad in the last 10 years. GET: comma-separated depart_return pairs, e.g. 2024-01-05_2024-03-01,2025-07-01_2026-02-01. POST: array of {depart, return}." } }, { "name": "longestTripDays", "in": "query", "required": false, "description": "If you do not list trips: days of your longest single trip abroad in the last 10 years.", "schema": { "type": "number", "description": "If you do not list trips: days of your longest single trip abroad in the last 10 years.", "minimum": 0 } }, { "name": "totalAbsenceDays", "in": "query", "required": false, "description": "If you do not list trips: total days abroad in the last 10 years.", "schema": { "type": "number", "description": "If you do not list trips: total days abroad in the last 10 years.", "minimum": 0 } }, { "name": "japaneseB1", "in": "query", "required": false, "description": "Japanese at CEFR B1 level or above (true/false; omit if unknown).", "schema": { "type": "boolean", "description": "Japanese at CEFR B1 level or above (true/false; omit if unknown)." } }, { "name": "b1Exemption", "in": "query", "required": false, "description": "B1 not considered for: hsp_or_family, schooling_6y (6+ years of elementary/secondary schooling in Japan), pr_child_born_in_japan.", "schema": { "type": "string", "description": "B1 not considered for: hsp_or_family, schooling_6y (6+ years of elementary/secondary schooling in Japan), pr_child_born_in_japan.", "enum": [ "none", "hsp_or_family", "schooling_6y", "pr_child_born_in_japan" ], "default": "none" } }, { "name": "schoolAgeChildren", "in": "query", "required": false, "description": "School-age children and whether they attend elementary / junior high school.", "schema": { "type": "string", "description": "School-age children and whether they attend elementary / junior high school.", "enum": [ "none", "all_in_school", "not_in_school" ], "default": "none" } }, { "name": "taxesPaidOnTime", "in": "query", "required": false, "description": "All taxes paid by their original due dates.", "schema": { "type": "boolean", "description": "All taxes paid by their original due dates." } }, { "name": "pensionInsurancePaidOnTime", "in": "query", "required": false, "description": "Pension and health insurance premiums paid on time.", "schema": { "type": "boolean", "description": "Pension and health insurance premiums paid on time." } }, { "name": "firstPrApplication", "in": "query", "required": false, "description": "This is your first PR application filed from 2027-04-01 (for the 3-year transition).", "schema": { "type": "boolean", "description": "This is your first PR application filed from 2027-04-01 (for the 3-year transition).", "default": true } } ], "responses": { "200": { "description": "Result as JSON. Always includes a `disclaimer` field.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Missing or invalid input. The body explains what to send and gives an example." }, "429": { "description": "Too many requests from one IP. Retry after the Retry-After seconds." } } }, "post": { "operationId": "japanPermanentResidencyCheckPost", "summary": "Which Japan permanent residence (PR, 永住) guideline applies to my filing date, and do I meet its objective factors? (JSON body)", "description": "Japan's Immigration Services Agency revised its permanent residence guideline on 2026-10-01. Filed up to 2026-03-31: 2026-02-24 guideline. Filed 2026-04-01 to 2027-03-31: 2026-02-24 guideline plus the revised income (household income above the Japanese average for the household size) and not-a-public-burden factors (also for cases pending on 2026-10-01). Filed from 2027-04-01: revised guideline in full — spouses of Japanese/PRs need 5 years of marriage + 3 years in Japan (was 3 + 1), children 3 years (was 1), Intra-company Transferee and Employment for Skill Development no longer count as work status, a 3-year period of stay counts as 'longest' only under a narrow transition, and new factors: no single trip abroad of 6+ months or 2.5+ years in total in the last 10 years, Japanese at CEFR B1, projected pension, rules understanding, school attendance. Returns summary (objective_issue / need_more_info / no_objective_blocker — never an approval prediction), the guideline band, checks[] with status (issue/review/unknown/meets/not_considered/info) and official sources, the time requirement with the earliest date you meet it, an old-vs-new filing window for spouse/child routes, absence analysis, key dates with day counts, the ¥200,000 PR fee, notes and a disclaimer.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "route" ], "properties": { "route": { "type": "string", "description": "PR route: general (10 years), spouse (of a Japanese national / PR / SPR), child, long_term_resident, refugee, hsp70, hsp80, special_hsp, contribution, special_zone_regional.", "enum": [ "general", "spouse", "child", "long_term_resident", "refugee", "hsp70", "hsp80", "special_hsp", "contribution", "special_zone_regional" ] }, "applicationDate": { "type": "string", "description": "YYYY-MM-DD you filed or plan to file. Decides which guideline applies. Default: today in Japan." }, "residenceSince": { "type": "string", "description": "YYYY-MM-DD your continuous residence in Japan began (alternative: yearsInJapan)." }, "yearsInJapan": { "type": "number", "description": "Years of continuous residence in Japan at filing (used if residenceSince is not given).", "minimum": 0, "maximum": 100 }, "workOrResidenceYears": { "type": "number", "description": "General route: continuous years on a qualifying work or residence status (excluding Technical Intern Training, Specified Skilled Worker (i), and from 2027-04-01 also Intra-company Transferee and Employment for Skill Development).", "minimum": 0, "maximum": 100 }, "currentStatus": { "type": "string", "description": "Current status of residence, to flag statuses that do not count as work status (aliases: gijinkoku, ict, ssw1, titp).", "enum": [ "engineer_humanities", "intra_company_transferee", "highly_skilled_professional", "business_manager", "skilled_labor", "specified_skilled_worker_2", "specified_skilled_worker_1", "technical_intern_training", "employment_for_skill_development", "spouse_of_japanese", "spouse_of_permanent_resident", "long_term_resident", "dependent", "student", "designated_activities", "other_work" ] }, "periodOfStay": { "type": "string", "description": "Period of stay on your residence card: 5y, 3y, 1y, 6m, 3m, unlimited, other.", "enum": [ "5y", "3y", "1y", "6m", "3m", "unlimited", "other" ] }, "periodExpiry": { "type": "string", "description": "YYYY-MM-DD your current period of stay expires (needed for the 3-year transition from 2027-04-01)." }, "marriageDate": { "type": "string", "description": "Spouse route: YYYY-MM-DD the substantive marriage began." }, "qualifyingSince": { "type": "string", "description": "Special routes: YYYY-MM-DD the qualifying period began (Long-Term Resident status, refugee recognition, HSP points, ...)." }, "trips": { "type": "string", "description": "Trips abroad in the last 10 years. GET: comma-separated depart_return pairs, e.g. 2024-01-05_2024-03-01,2025-07-01_2026-02-01. POST: array of {depart, return}." }, "longestTripDays": { "type": "number", "description": "If you do not list trips: days of your longest single trip abroad in the last 10 years.", "minimum": 0 }, "totalAbsenceDays": { "type": "number", "description": "If you do not list trips: total days abroad in the last 10 years.", "minimum": 0 }, "japaneseB1": { "type": "boolean", "description": "Japanese at CEFR B1 level or above (true/false; omit if unknown)." }, "b1Exemption": { "type": "string", "description": "B1 not considered for: hsp_or_family, schooling_6y (6+ years of elementary/secondary schooling in Japan), pr_child_born_in_japan.", "enum": [ "none", "hsp_or_family", "schooling_6y", "pr_child_born_in_japan" ], "default": "none" }, "schoolAgeChildren": { "type": "string", "description": "School-age children and whether they attend elementary / junior high school.", "enum": [ "none", "all_in_school", "not_in_school" ], "default": "none" }, "taxesPaidOnTime": { "type": "boolean", "description": "All taxes paid by their original due dates." }, "pensionInsurancePaidOnTime": { "type": "boolean", "description": "Pension and health insurance premiums paid on time." }, "firstPrApplication": { "type": "boolean", "description": "This is your first PR application filed from 2027-04-01 (for the 3-year transition).", "default": true } } } } } }, "responses": { "200": { "description": "Result as JSON. Always includes a `disclaimer` field.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Missing or invalid input. The body explains what to send and gives an example." }, "429": { "description": "Too many requests from one IP. Retry after the Retry-After seconds." } } } }, "/api/rules": { "get": { "operationId": "japanPermanentResidencyRules", "summary": "Japan permanent residence guideline rules: filing-date bands, time requirements old vs revised, work-status exclusions, 3-year period transition, absence rule, new factors, fee", "description": "Returns the dated rules of ISA's permanent residence guideline (2026-02-24 and the 2026-10-01 revision) and which applies by filing date, with sources and disclaimer. No inputs.", "responses": { "200": { "description": "Rules JSON with rulesAsOf and sources.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } } } }