{
 "openapi": "3.1.0",
 "info": {
  "title": "Japan Corporate-Number (法人番号) API",
  "description": "Look up, search, and name-match Japanese corporations against the official 国税庁 (National Tax Agency) corporate-number registry. x402-enabled for AI agents doing KYC, vendor reconciliation (名寄せ), invoice verification, or company research in Japan.",
  "version": "1.0.0",
  "contact": {
   "name": "MAMETA",
   "url": "https://github.com/Mameta29/agentic-market-jp"
  }
 },
 "servers": [
  {
   "url": "https://houjin.agentic-jp.com"
  }
 ],
 "tags": [
  {
   "name": "japan"
  },
  {
   "name": "jp"
  },
  {
   "name": "corporate"
  },
  {
   "name": "houjin"
  },
  {
   "name": "company"
  },
  {
   "name": "registry"
  },
  {
   "name": "kyc"
  }
 ],
 "paths": {
  "/corporation/{number}": {
   "get": {
    "operationId": "GET__corporation_number",
    "summary": "Look up a Japanese corporation by corporate number",
    "description": "Japanese company lookup by 13-digit corporate number (法人番号) — official trade name (Japanese and registered English), registered address, postal code, corporation kind, and lifecycle status. `status` is \"active\" or \"closed\"; a closed record carries the closure cause/date and the successor's 法人番号 after a merger. Sourced from the 国税庁 (National Tax Agency) corporate registry. The leading check digit is validated before lookup.",
    "x-payment-info": {
     "pricingMode": "fixed",
     "price": "0.005",
     "currency": "USD",
     "protocols": [
      "x402"
     ]
    },
    "responses": {
     "200": {
      "description": "Successful response",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "402": {
      "description": "Payment required (x402). Payment requirements are in the base64-encoded Payment-Required response header."
     }
    },
    "parameters": [
     {
      "name": "number",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "13-digit Japanese corporate number (e.g. 7000012050002)"
     }
    ]
   }
  },
  "/verify": {
   "post": {
    "operationId": "POST__verify",
    "summary": "Verify a company name against the JP registry (KYB)",
    "description": "KYB / KYC verification of a Japanese company: reconcile a company name (+ optional address) against the official JP corporate registry (名寄せ). Returns ranked candidate 法人番号 with a 0-1 confidence score, handling 株式会社 / (株) / ㈱ spelling variation and matching Japanese or English names. A dissolved corporation is never reported as `verified` even on an exact name match. Use it to confirm a vendor, customer, or invoice counterparty.",
    "x-payment-info": {
     "pricingMode": "fixed",
     "price": "0.005",
     "currency": "USD",
     "protocols": [
      "x402"
     ]
    },
    "responses": {
     "200": {
      "description": "Successful response",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "402": {
      "description": "Payment required (x402). Payment requirements are in the base64-encoded Payment-Required response header."
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "properties": {
         "name": {
          "type": "string",
          "description": "Corporation name to reconcile against the registry. Required."
         },
         "prefecture": {
          "type": "string",
          "description": "Prefecture, to disambiguate. Optional."
         },
         "city": {
          "type": "string",
          "description": "City / ward, to disambiguate. Optional."
         },
         "corporate_number": {
          "type": "string",
          "description": "A 法人番号 the caller wants confirmed against the name/address. Optional."
         }
        },
        "required": [
         "name"
        ],
        "type": "object"
       },
       "example": {
        "name": "株式会社サンプル商事",
        "prefecture": "東京都",
        "city": "千代田区"
       }
      }
     }
    }
   }
  },
  "/stats": {
   "get": {
    "operationId": "GET__stats",
    "summary": "Get statistics of the Japanese corporate registry",
    "description": "Dataset metadata for this Japanese (JP) corporate-number API — how many corporations are loaded and which prefectures are covered.",
    "x-payment-info": {
     "pricingMode": "fixed",
     "price": "0.001",
     "currency": "USD",
     "protocols": [
      "x402"
     ]
    },
    "responses": {
     "200": {
      "description": "Successful response",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "402": {
      "description": "Payment required (x402). Payment requirements are in the base64-encoded Payment-Required response header."
     }
    }
   }
  },
  "/search": {
   "post": {
    "operationId": "POST__search",
    "summary": "Search the Japanese corporate registry by name",
    "description": "Japanese company search: look up companies in the official JP corporate registry by trade name and/or location. Partial-name match on both the Japanese and registered English name, with width/abbreviation normalization, filterable by prefecture, city, and corporation kind. Returns up to 50 corporations with their 法人番号 and lifecycle status. Dynamic pricing: a base fee plus a small per-result fee.",
    "x-payment-info": {
     "pricingMode": "quote",
     "currency": "USD",
     "protocols": [
      "x402"
     ],
     "description": "$0.005 base + $0.0002 × result limit"
    },
    "responses": {
     "200": {
      "description": "Successful response",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "402": {
      "description": "Payment required (x402). Payment requirements are in the base64-encoded Payment-Required response header."
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "properties": {
         "name": {
          "type": "string",
          "description": "Partial trade-name match (商号の部分一致). Width/abbreviation normalized."
         },
         "prefecture": {
          "type": "string",
          "description": "Prefecture name (\"東京都\") or JIS prefecture code (\"13\")."
         },
         "city": {
          "type": "string",
          "description": "City / ward substring (\"港区\")."
         },
         "corp_kind": {
          "type": "string",
          "description": "3-digit corporation-kind code (e.g. \"301\" = stock company)."
         },
         "limit": {
          "type": "number",
          "description": "Max results, 1-50 (default 50)."
         }
        },
        "required": [],
        "type": "object"
       },
       "example": {
        "name": "トヨタ",
        "prefecture": "愛知県",
        "limit": 20
       }
      }
     }
    }
   }
  },
  "/batch": {
   "post": {
    "operationId": "POST__batch",
    "summary": "Look up corporate numbers in bulk (up to 100)",
    "description": "Look up many Japanese (JP) corporate numbers (法人番号) in one request (up to 50). Dynamic pricing by item count with a volume discount.",
    "x-payment-info": {
     "pricingMode": "quote",
     "currency": "USD",
     "protocols": [
      "x402"
     ],
     "description": "$0.002 × item count × 0.8"
    },
    "responses": {
     "200": {
      "description": "Successful response",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "402": {
      "description": "Payment required (x402). Payment requirements are in the base64-encoded Payment-Required response header."
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "properties": {
         "items": {
          "type": "array",
          "description": "Corporate numbers to look up in one call (max 50). Each item has an `id` (echoed back) and a 13-digit `corporate_number`."
         }
        },
        "required": [
         "items"
        ],
        "type": "object"
       },
       "example": {
        "items": [
         {
          "id": "a",
          "corporate_number": "7000012050002"
         },
         {
          "id": "b",
          "corporate_number": "1010001000001"
         }
        ]
       }
      }
     }
    }
   }
  },
  "/report": {
   "post": {
    "operationId": "POST__report",
    "summary": "Get a one-call KYB report on a Japanese corporation",
    "description": "Japanese company KYB report in one call — company lookup + verification from a corporate number or company name. Returns the official 国税庁 registry record, lifecycle status, kana + romaji name readings, risk flags (closed registry, recent registration/changes), an English summary, and the dataset vintage. Use for counterparty due diligence, supplier onboarding, or invoice fraud checks — replaces 3-4 separate lookups.",
    "x-payment-info": {
     "pricingMode": "fixed",
     "price": "0.25",
     "currency": "USD",
     "protocols": [
      "x402"
     ]
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "corporate_number": {
          "type": "string",
          "description": "13-digit Japanese corporate number (法人番号). Either this or name is required."
         },
         "name": {
          "type": "string",
          "description": "Company trade name (Japanese or English) to resolve when the number is unknown",
          "maxLength": 128
         },
         "prefecture": {
          "type": "string",
          "description": "Optional prefecture filter for name resolution"
         },
         "city": {
          "type": "string",
          "description": "Optional city/ward filter for name resolution"
         }
        }
       },
       "example": {
        "corporate_number": "7000012050002"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "KYB report",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  }
 }
}