{
  "openapi": "3.1.0",
  "info": {
    "title": "Japan My Number Card Expiry Check API",
    "version": "1.0.0",
    "description": "When does my My Number Card (マイナンバーカード) expire, and what do I have to do before then? Foreign residents' cards end with the period of stay and do not extend when the visa is renewed: get the exact date, the city-hall deadline, the one-time 2-month extension while a renewal is pending, the e-certificate date and the マイナ保険証 grace.\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-mynumber-card-check.vercel.app"
    }
  ],
  "paths": {
    "/api/check": {
      "get": {
        "operationId": "japanMyNumberCardExpiryCheck",
        "summary": "When does a Japan My Number Card (マイナンバーカード) expire, and what must the holder do before then?",
        "description": "Applies the My Number Card ordinance (総務省令第85号) art. 26 (10th birthday after the card is made, 5th if under 18; age line 20 for cards made by 2022-03-31; Feb 29 → Feb 28), art. 27 (foreign residents with a period of stay: card ends on the period-of-stay expiry and is NOT extended automatically by a visa renewal; city-hall extension to the new period up to the 10th-birthday cap; one-time extension to the end of the 2-month special period while a renewal is pending) and art. 29 (renew from the day fewer than 3 months remain; new card runs to the 11th / 6th birthday). Also: e-certificate expiry (5th birthday, capped at card expiry), the マイナ保険証 grace (to the end of the 3rd month after the e-certificate's expiry month), the 特定在留カード (since 2026-06-14) and PR / HSP (ii) residence-card renewal. Returns verdict (ok | renew_window_open | extend_before_expiry | no_action_needed | expired), card {expiry, renewFrom, maxExtendableTo, newExpiryAfterAction}, specialExtension, ecert {expiry, renewFrom, status, insuranceGraceEnds}, dated actions (from, by, where, fee), warnings, sources and a disclaimer.\n\nExample: https://japan-mynumber-card-check.vercel.app/api/check?holder=mid_long&birthDate=1992-04-10&cardIssueDate=2024-03-01&residenceExpiry=2026-12-15&renewal=pending",
        "parameters": [
          {
            "name": "holder",
            "in": "query",
            "required": true,
            "description": "mid_long (foreign resident with a period of stay: work, student, spouse…), permanent, hsp2, spr (special permanent resident), japanese. Aliases: pr, student, work, citizen…",
            "schema": {
              "type": "string",
              "description": "mid_long (foreign resident with a period of stay: work, student, spouse…), permanent, hsp2, spr (special permanent resident), japanese. Aliases: pr, student, work, citizen…",
              "enum": [
                "mid_long",
                "permanent",
                "hsp2",
                "spr",
                "japanese"
              ]
            }
          },
          {
            "name": "birthDate",
            "in": "query",
            "required": true,
            "description": "YYYY-MM-DD date of birth.",
            "schema": {
              "type": "string",
              "description": "YYYY-MM-DD date of birth."
            }
          },
          {
            "name": "cardIssueDate",
            "in": "query",
            "required": true,
            "description": "YYYY-MM-DD the card was made / issued (発行日 on the card).",
            "schema": {
              "type": "string",
              "description": "YYYY-MM-DD the card was made / issued (発行日 on the card)."
            }
          },
          {
            "name": "residenceExpiry",
            "in": "query",
            "required": false,
            "description": "mid_long: YYYY-MM-DD period-of-stay expiry (在留期限) that applied when the card was made or last extended. Required for mid_long unless cardExpiry is given.",
            "schema": {
              "type": "string",
              "description": "mid_long: YYYY-MM-DD period-of-stay expiry (在留期限) that applied when the card was made or last extended. Required for mid_long unless cardExpiry is given."
            }
          },
          {
            "name": "renewal",
            "in": "query",
            "required": false,
            "description": "mid_long: visa renewal / change status: none | pending (applied, no decision) | granted (new residence card received).",
            "schema": {
              "type": "string",
              "description": "mid_long: visa renewal / change status: none | pending (applied, no decision) | granted (new residence card received).",
              "enum": [
                "none",
                "pending",
                "granted"
              ],
              "default": "none"
            }
          },
          {
            "name": "newResidenceExpiry",
            "in": "query",
            "required": false,
            "description": "YYYY-MM-DD new period-of-stay expiry when renewal=granted.",
            "schema": {
              "type": "string",
              "description": "YYYY-MM-DD new period-of-stay expiry when renewal=granted."
            }
          },
          {
            "name": "specificCard",
            "in": "query",
            "required": false,
            "description": "true if you hold (or ISA just issued you) a 特定在留カード / 特定特別永住者証明書 combining the residence card and My Number Card.",
            "schema": {
              "type": "boolean",
              "description": "true if you hold (or ISA just issued you) a 特定在留カード / 特定特別永住者証明書 combining the residence card and My Number Card.",
              "default": false
            }
          },
          {
            "name": "cardExpiry",
            "in": "query",
            "required": false,
            "description": "Optional YYYY-MM-DD expiry printed on the card; overrides the computed date.",
            "schema": {
              "type": "string",
              "description": "Optional YYYY-MM-DD expiry printed on the card; overrides the computed date."
            }
          },
          {
            "name": "ecertExpiry",
            "in": "query",
            "required": false,
            "description": "Optional YYYY-MM-DD e-certificate expiry (J-LIS notice / Mynaportal); default: 5th birthday after issue, capped at card expiry.",
            "schema": {
              "type": "string",
              "description": "Optional YYYY-MM-DD e-certificate expiry (J-LIS notice / Mynaportal); default: 5th birthday after issue, capped at card expiry."
            }
          },
          {
            "name": "issuedAsRenewal",
            "in": "query",
            "required": false,
            "description": "true if this card was made as a renewal while fewer than 3 months were left on the old one (11th / 6th birthday rule).",
            "schema": {
              "type": "boolean",
              "description": "true if this card was made as a renewal while fewer than 3 months were left on the old one (11th / 6th birthday rule).",
              "default": false
            }
          },
          {
            "name": "residenceCardExpiry",
            "in": "query",
            "required": false,
            "description": "permanent / hsp2: YYYY-MM-DD expiry of the residence card itself, to get its renewal window.",
            "schema": {
              "type": "string",
              "description": "permanent / hsp2: YYYY-MM-DD expiry of the residence card itself, to get its renewal window."
            }
          },
          {
            "name": "today",
            "in": "query",
            "required": false,
            "description": "Override today's date (default: today in Japan).",
            "schema": {
              "type": "string",
              "description": "Override today's date (default: today in Japan)."
            }
          }
        ],
        "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": "japanMyNumberCardExpiryCheckPost",
        "summary": "When does a Japan My Number Card (マイナンバーカード) expire, and what must the holder do before then? (JSON body)",
        "description": "Applies the My Number Card ordinance (総務省令第85号) art. 26 (10th birthday after the card is made, 5th if under 18; age line 20 for cards made by 2022-03-31; Feb 29 → Feb 28), art. 27 (foreign residents with a period of stay: card ends on the period-of-stay expiry and is NOT extended automatically by a visa renewal; city-hall extension to the new period up to the 10th-birthday cap; one-time extension to the end of the 2-month special period while a renewal is pending) and art. 29 (renew from the day fewer than 3 months remain; new card runs to the 11th / 6th birthday). Also: e-certificate expiry (5th birthday, capped at card expiry), the マイナ保険証 grace (to the end of the 3rd month after the e-certificate's expiry month), the 特定在留カード (since 2026-06-14) and PR / HSP (ii) residence-card renewal. Returns verdict (ok | renew_window_open | extend_before_expiry | no_action_needed | expired), card {expiry, renewFrom, maxExtendableTo, newExpiryAfterAction}, specialExtension, ecert {expiry, renewFrom, status, insuranceGraceEnds}, dated actions (from, by, where, fee), warnings, sources and a disclaimer.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "holder",
                  "birthDate",
                  "cardIssueDate"
                ],
                "properties": {
                  "holder": {
                    "type": "string",
                    "description": "mid_long (foreign resident with a period of stay: work, student, spouse…), permanent, hsp2, spr (special permanent resident), japanese. Aliases: pr, student, work, citizen…",
                    "enum": [
                      "mid_long",
                      "permanent",
                      "hsp2",
                      "spr",
                      "japanese"
                    ]
                  },
                  "birthDate": {
                    "type": "string",
                    "description": "YYYY-MM-DD date of birth."
                  },
                  "cardIssueDate": {
                    "type": "string",
                    "description": "YYYY-MM-DD the card was made / issued (発行日 on the card)."
                  },
                  "residenceExpiry": {
                    "type": "string",
                    "description": "mid_long: YYYY-MM-DD period-of-stay expiry (在留期限) that applied when the card was made or last extended. Required for mid_long unless cardExpiry is given."
                  },
                  "renewal": {
                    "type": "string",
                    "description": "mid_long: visa renewal / change status: none | pending (applied, no decision) | granted (new residence card received).",
                    "enum": [
                      "none",
                      "pending",
                      "granted"
                    ],
                    "default": "none"
                  },
                  "newResidenceExpiry": {
                    "type": "string",
                    "description": "YYYY-MM-DD new period-of-stay expiry when renewal=granted."
                  },
                  "specificCard": {
                    "type": "boolean",
                    "description": "true if you hold (or ISA just issued you) a 特定在留カード / 特定特別永住者証明書 combining the residence card and My Number Card.",
                    "default": false
                  },
                  "cardExpiry": {
                    "type": "string",
                    "description": "Optional YYYY-MM-DD expiry printed on the card; overrides the computed date."
                  },
                  "ecertExpiry": {
                    "type": "string",
                    "description": "Optional YYYY-MM-DD e-certificate expiry (J-LIS notice / Mynaportal); default: 5th birthday after issue, capped at card expiry."
                  },
                  "issuedAsRenewal": {
                    "type": "boolean",
                    "description": "true if this card was made as a renewal while fewer than 3 months were left on the old one (11th / 6th birthday rule).",
                    "default": false
                  },
                  "residenceCardExpiry": {
                    "type": "string",
                    "description": "permanent / hsp2: YYYY-MM-DD expiry of the residence card itself, to get its renewal window."
                  },
                  "today": {
                    "type": "string",
                    "description": "Override today's date (default: today in Japan)."
                  }
                }
              }
            }
          }
        },
        "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": "japanMyNumberCardRules",
        "summary": "Japan My Number Card expiry rules: 10th/5th birthday, foreign residents (period of stay, extension, 2-month special extension), renewal window, e-certificates, マイナ保険証 grace, 特定在留カード, sources",
        "description": "Returns the rules the checker applies, with ordinance articles, official sources and disclaimer. No inputs.",
        "responses": {
          "200": {
            "description": "Rules JSON with rulesAsOf and sources.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    }
  }
}