{
  "openapi": "3.1.0",
  "info": {
    "title": "Japan Overseas Dependents Check API",
    "version": "1.0.0",
    "description": "Supporting family abroad from Japan? Check if a parent, spouse, child or sibling living outside Japan qualifies for the 2026 dependent deduction (国外居住親族の扶養控除), the ¥380,000 remittance test for ages 30-69, the deduction amount under the new ¥620,000 income limit, and which documents to hand your employer.\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-overseas-dependents.vercel.app"
    }
  ],
  "paths": {
    "/api/check": {
      "get": {
        "operationId": "japanOverseasDependentCheck",
        "summary": "Can a Japan-resident taxpayer claim a relative living outside Japan as a dependent or spouse, how much is the deduction, and which documents are needed?",
        "description": "Applies Japan's National Tax Agency rules for relatives living abroad (国外居住親族に係る扶養控除等, Q&A revised Aug 2026) to one relative. Returns verdict (eligible | conditional | short_of_380k | not_eligible), ageAtYearEnd, ageBand, route (age_16_29 | age_70_plus | studying_abroad | disabled | support_380k | spouse), deductions[] (dependent ¥380k / specified 19-22 ¥630k / elderly ¥480k, specified-relative special 19-22 by income, spouse or spouse special by both incomes, disability ¥270k/¥400k), totalDeduction, optional estimatedIncomeTaxSaving, remittance (¥380,000 minimum for ages 30-69 unless studying abroad or disabled, shortfall, valid-method note, the 3+ payments statement option), documents.withForm and documents.atYearEnd, forms, steps, warnings, sources, disclaimer. 2026 uses the new ¥620,000 income limit (R8 reform); 2025 uses ¥580,000. Income tax only.\n\nExample: https://japan-overseas-dependents.vercel.app/api/check?relationship=parent&age=62&remittanceTotal=450000&remittanceCount=6&marginalRate=10",
        "parameters": [
          {
            "name": "relationship",
            "in": "query",
            "required": true,
            "description": "spouse, child, parent (incl. parent-in-law), grandparent, sibling, grandchild, other. Aliases: mother, father, wife, son, 母, 妻…",
            "schema": {
              "type": "string",
              "description": "spouse, child, parent (incl. parent-in-law), grandparent, sibling, grandchild, other. Aliases: mother, father, wife, son, 母, 妻…",
              "enum": [
                "spouse",
                "child",
                "parent",
                "grandparent",
                "sibling",
                "grandchild",
                "other"
              ]
            }
          },
          {
            "name": "age",
            "in": "query",
            "required": false,
            "description": "Relative's age on Dec 31 of the tax year. Give age or birthDate.",
            "schema": {
              "type": "number",
              "description": "Relative's age on Dec 31 of the tax year. Give age or birthDate."
            }
          },
          {
            "name": "birthDate",
            "in": "query",
            "required": false,
            "description": "YYYY-MM-DD (age is computed as of Dec 31; born Jan 1 counts a year older).",
            "schema": {
              "type": "string",
              "description": "YYYY-MM-DD (age is computed as of Dec 31; born Jan 1 counts a year older)."
            }
          },
          {
            "name": "year",
            "in": "query",
            "required": false,
            "description": "Tax year: 2026 (default) or 2025.",
            "schema": {
              "type": "number",
              "description": "Tax year: 2026 (default) or 2025.",
              "default": 2026
            }
          },
          {
            "name": "relativeIncome",
            "in": "query",
            "required": false,
            "description": "Relative's total income (合計所得金額) in yen. For a non-resident usually only Japan-source income, so 0 if none.",
            "schema": {
              "type": "number",
              "description": "Relative's total income (合計所得金額) in yen. For a non-resident usually only Japan-source income, so 0 if none.",
              "default": 0
            }
          },
          {
            "name": "taxpayerIncome",
            "in": "query",
            "required": false,
            "description": "Your own total income in yen (spouse amounts depend on it; default assumes ≤ ¥9,000,000).",
            "schema": {
              "type": "number",
              "description": "Your own total income in yen (spouse amounts depend on it; default assumes ≤ ¥9,000,000)."
            }
          },
          {
            "name": "studyingAbroad",
            "in": "query",
            "required": false,
            "description": "Relative lived in Japan and left to study abroad with a student-equivalent status (ages 30-69 route).",
            "schema": {
              "type": "boolean",
              "description": "Relative lived in Japan and left to study abroad with a student-equivalent status (ages 30-69 route).",
              "default": false
            }
          },
          {
            "name": "disability",
            "in": "query",
            "required": false,
            "description": "Disabled under Japanese criteria: none | disabled | special.",
            "schema": {
              "type": "string",
              "description": "Disabled under Japanese criteria: none | disabled | special.",
              "enum": [
                "none",
                "disabled",
                "special"
              ],
              "default": "none"
            }
          },
          {
            "name": "remittanceTotal",
            "in": "query",
            "required": false,
            "description": "Yen you paid directly to this relative in the year (sending date counts). Omit if unknown → verdict conditional.",
            "schema": {
              "type": "number",
              "description": "Yen you paid directly to this relative in the year (sending date counts). Omit if unknown → verdict conditional."
            }
          },
          {
            "name": "remittanceCount",
            "in": "query",
            "required": false,
            "description": "Number of payments (3+ unlocks the statement option).",
            "schema": {
              "type": "number",
              "description": "Number of payments (3+ unlocks the statement option)."
            }
          },
          {
            "name": "firstLastTotal",
            "in": "query",
            "required": false,
            "description": "Sum of the first and last payments of the year (matters for the ¥380,000 test with the statement option).",
            "schema": {
              "type": "number",
              "description": "Sum of the first and last payments of the year (matters for the ¥380,000 test with the statement option)."
            }
          },
          {
            "name": "method",
            "in": "query",
            "required": false,
            "description": "How you paid: bank | credit_card | electronic_payment (valid) or cash | via_representative | joint_account (not valid proof).",
            "schema": {
              "type": "string",
              "description": "How you paid: bank | credit_card | electronic_payment (valid) or cash | via_representative | joint_account (not valid proof).",
              "enum": [
                "bank",
                "credit_card",
                "electronic_payment",
                "cash",
                "via_representative",
                "joint_account"
              ],
              "default": "bank"
            }
          },
          {
            "name": "marginalRate",
            "in": "query",
            "required": false,
            "description": "Your income-tax bracket in percent (5, 10, 20, 23, 33, 40 or 45), to estimate the saving (incl. 2.1% reconstruction surtax).",
            "schema": {
              "type": "number",
              "description": "Your income-tax bracket in percent (5, 10, 20, 23, 33, 40 or 45), to estimate the saving (incl. 2.1% reconstruction surtax)."
            }
          }
        ],
        "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": "japanOverseasDependentCheckPost",
        "summary": "Can a Japan-resident taxpayer claim a relative living outside Japan as a dependent or spouse, how much is the deduction, and which documents are needed? (JSON body)",
        "description": "Applies Japan's National Tax Agency rules for relatives living abroad (国外居住親族に係る扶養控除等, Q&A revised Aug 2026) to one relative. Returns verdict (eligible | conditional | short_of_380k | not_eligible), ageAtYearEnd, ageBand, route (age_16_29 | age_70_plus | studying_abroad | disabled | support_380k | spouse), deductions[] (dependent ¥380k / specified 19-22 ¥630k / elderly ¥480k, specified-relative special 19-22 by income, spouse or spouse special by both incomes, disability ¥270k/¥400k), totalDeduction, optional estimatedIncomeTaxSaving, remittance (¥380,000 minimum for ages 30-69 unless studying abroad or disabled, shortfall, valid-method note, the 3+ payments statement option), documents.withForm and documents.atYearEnd, forms, steps, warnings, sources, disclaimer. 2026 uses the new ¥620,000 income limit (R8 reform); 2025 uses ¥580,000. Income tax only.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "relationship"
                ],
                "properties": {
                  "relationship": {
                    "type": "string",
                    "description": "spouse, child, parent (incl. parent-in-law), grandparent, sibling, grandchild, other. Aliases: mother, father, wife, son, 母, 妻…",
                    "enum": [
                      "spouse",
                      "child",
                      "parent",
                      "grandparent",
                      "sibling",
                      "grandchild",
                      "other"
                    ]
                  },
                  "age": {
                    "type": "number",
                    "description": "Relative's age on Dec 31 of the tax year. Give age or birthDate."
                  },
                  "birthDate": {
                    "type": "string",
                    "description": "YYYY-MM-DD (age is computed as of Dec 31; born Jan 1 counts a year older)."
                  },
                  "year": {
                    "type": "number",
                    "description": "Tax year: 2026 (default) or 2025.",
                    "default": 2026
                  },
                  "relativeIncome": {
                    "type": "number",
                    "description": "Relative's total income (合計所得金額) in yen. For a non-resident usually only Japan-source income, so 0 if none.",
                    "default": 0
                  },
                  "taxpayerIncome": {
                    "type": "number",
                    "description": "Your own total income in yen (spouse amounts depend on it; default assumes ≤ ¥9,000,000)."
                  },
                  "studyingAbroad": {
                    "type": "boolean",
                    "description": "Relative lived in Japan and left to study abroad with a student-equivalent status (ages 30-69 route).",
                    "default": false
                  },
                  "disability": {
                    "type": "string",
                    "description": "Disabled under Japanese criteria: none | disabled | special.",
                    "enum": [
                      "none",
                      "disabled",
                      "special"
                    ],
                    "default": "none"
                  },
                  "remittanceTotal": {
                    "type": "number",
                    "description": "Yen you paid directly to this relative in the year (sending date counts). Omit if unknown → verdict conditional."
                  },
                  "remittanceCount": {
                    "type": "number",
                    "description": "Number of payments (3+ unlocks the statement option)."
                  },
                  "firstLastTotal": {
                    "type": "number",
                    "description": "Sum of the first and last payments of the year (matters for the ¥380,000 test with the statement option)."
                  },
                  "method": {
                    "type": "string",
                    "description": "How you paid: bank | credit_card | electronic_payment (valid) or cash | via_representative | joint_account (not valid proof).",
                    "enum": [
                      "bank",
                      "credit_card",
                      "electronic_payment",
                      "cash",
                      "via_representative",
                      "joint_account"
                    ],
                    "default": "bank"
                  },
                  "marginalRate": {
                    "type": "number",
                    "description": "Your income-tax bracket in percent (5, 10, 20, 23, 33, 40 or 45), to estimate the saving (incl. 2.1% reconstruction surtax)."
                  }
                }
              }
            }
          }
        },
        "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": "japanOverseasDependentRules",
        "summary": "Japan overseas-dependent deduction rules: who qualifies by age, ¥380,000 test, amounts, spouse and specified-relative tables, documents, sources",
        "description": "Returns the rules the checker applies, with NTA sources and disclaimer. No inputs.",
        "responses": {
          "200": {
            "description": "Rules JSON with rulesAsOf and sources.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    }
  }
}