---
name: japan-corporate-number-api
display_name: Japan Corporate-Number (法人番号) Lookup & Verification
description: Look up, search, and name-match Japanese corporations against the official 国税庁 (National Tax Agency) corporate-number registry. Resolve a 13-digit 法人番号 to a company, search by trade name and location, or reconcile a name + address to its corporate number with a confidence score.
version: 1.0.0
license: proprietary
provider: MAMETA
base_url: https://houjin.agentic-jp.com
payment: x402
networks:
  - eip155:8453
  - eip155:137
  - solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp   # Solana mainnet
assets:
  - USDC (Base)
  - USDC (Polygon)
  - USDC (Solana)
discovery: /.well-known/x402
skill_url: /.well-known/skill.md
data_attribution:
  - "Powered by 国税庁法人番号公表サイト (National Tax Agency of Japan). 商用利用可・出典表示。"
tags:
  - japan
  - jp
  - corporate
  - houjin
  - company
  - registry
  - kyc
---

# Japan Corporate-Number (法人番号) API — Agent Usage Guide

## When to use this skill

- You have a 13-digit Japanese corporate number (法人番号) and need the
  company's official name and registered address
- You need to find a Japanese company by trade name and/or location
- You are doing **KYC / KYB**, vendor onboarding, or invoice verification and
  must confirm a counterparty against the official registry
- You are reconciling a list of company names (**名寄せ**) — a CRM export, a
  spreadsheet of vendors — to canonical corporate numbers
- You are building any assistant that researches or verifies Japanese
  companies

Every corporation registered in Japan has a unique 13-digit 法人番号 assigned
by the 国税庁 (National Tax Agency). This API serves that public dataset.

## Corporate numbers (法人番号)

A 法人番号 is **13 digits**: a 1-digit check digit followed by a 12-digit base
number. This API validates the check digit before any lookup, so an obvious
typo returns `400 INVALID_CORPORATE_NUMBER` instead of a misleading "not
found". Hyphens and spaces in the input are tolerated.

## Endpoints

All paid endpoints require an x402 payment. `/health` and `/.well-known/*` are
free.

| Method | Path | Price | Purpose |
|---|---|---|---|
| GET  | `/corporation/:number` | $0.005 | Look up one company by 法人番号 |
| POST | `/search` | $0.005 + $0.0002/result | Search by name / location |
| POST | `/verify` | $0.005 | Name-match → corporate number + confidence |
| POST | `/report` | $0.25 | **One-call KYB report** (record + status + readings + risk flags) |
| GET  | `/stats` | $0.001 | Dataset coverage metadata |
| POST | `/batch` | $0.002 × items × 0.8 | Look up many numbers at once |

### GET /corporation/:number

```
GET /corporation/7000012050002
→ {
    "corporate_number": "7000012050002",
    "name": "国立印刷局",
    "name_kana": null,
    "name_en": null,
    "prefecture": "東京都",
    "city": "港区",
    "street": "虎ノ門二丁目2番5号",
    "address_full": "東京都港区虎ノ門二丁目2番5号",
    "address_en": null,
    "postal_code": "1058445",
    "prefecture_code": "13",
    "corp_kind": "101",
    "corp_kind_label": "National government agency",
    "process_kind": "01",
    "status": "active",
    "close_cause": null,
    "close_cause_label": null,
    "close_date": null,
    "successor_corporate_number": null,
    "assignment_date": "2015-10-05",
    "update_date": "2018-04-02",
    "change_date": "2015-10-05"
  }
```

`status` is `"active"` or `"closed"`. A closed corporation (dissolution,
merger, liquidation) carries `close_cause`/`close_date` and, after a merger,
`successor_corporate_number`. KYC callers must not treat `"closed"` as a live
counterparty.

### POST /search

```
POST /search
  { "name": "トヨタ", "prefecture": "愛知県", "limit": 20 }
→ { "count": 12, "truncated": false, "query": { ... },
    "results": [ { "corporate_number": "...", "name": "...", ... } ] }
```

Provide at least one of `name`, `prefecture`, `city`, `corp_kind`.
`name` is a partial match with width/abbreviation normalization.
`prefecture` accepts a name (`東京都`) or a JIS code (`13`).
`limit` is 1–50 (default 50). `truncated: true` means the cap was hit — refine
the query. Dynamic price scales with the requested `limit`.

### POST /verify  ← the name-matching / KYC endpoint

```
POST /verify
  { "name": "(株)サンプル商事", "prefecture": "東京都", "city": "千代田区" }
→ {
    "query": { ... },
    "verified": true,
    "best": {
      "corporation": { "corporate_number": "...", "name": "株式会社サンプル商事", ... },
      "confidence": 0.96,
      "matched": { "name": true, "name_exact": true,
                   "prefecture": true, "city": true }
    },
    "candidate_count": 1,
    "candidates": [ { "corporation": { ... }, "confidence": 0.96, ... } ]
  }
```

`verify` reconciles a company name (+ optional address) to its 法人番号. It
normalizes corporate-form variation (`株式会社` / `(株)` / `㈱`, full-width vs
half-width) and scores each candidate 0–1.

- `verified: true` — a single, unambiguous high-confidence match (≥ 0.85 and
  clearly ahead of the runner-up). Safe to auto-accept.
- `verified: false` — review `candidates` yourself; the top one may still be
  right, just not certain.
- Pass an optional `corporate_number` to confirm a specific number against the
  supplied name/address.

### POST /report — $0.25 · the one-call KYB answer

Full due-diligence report from a single call. Accepts either a 13-digit
corporate number, or a company name (+ optional prefecture/city) resolved
through the same matcher as `/verify`.

```json
{ "corporate_number": "7000012050002" }
// or
{ "name": "株式会社サンプル商事", "prefecture": "東京都" }
```

Returns in one response what would otherwise take 3-4 calls:
- the authoritative 国税庁 registry record (Japanese + English renderings)
- check-digit validation and lifecycle `status` (`active`/`closed`), with
  successor corporate number on mergers
- `name_readings` — カナ from the registry plus a romaji transliteration
- `risk_flags[]` — machine-actionable: `REGISTRY_CLOSED`, `HAS_SUCCESSOR`,
  `RECENTLY_REGISTERED` (≤180 days), `RECENT_REGISTRY_CHANGE` (≤90 days),
  `INCOMPLETE_ADDRESS`
- `summary_en` — one-line English conclusion
- `data_as_of` — dataset vintage, so you can judge freshness

Use for supplier onboarding, counterparty checks before payment, invoice
fraud screening, or enriching CRM records.

### POST /batch

```
POST /batch
  { "items": [ { "id": "a", "corporate_number": "7000012050002" },
               { "id": "b", "corporate_number": "1010001000001" } ] }
→ { "count": 2, "results": [
     { "id": "a", "success": true, "data": { ... } },
     { "id": "b", "success": false,
       "error": { "code": "CORPORATION_NOT_FOUND", "message": "..." } } ] }
```

Up to 50 items. Each number is resolved independently — a bad number fails
only that item, never the whole batch.

## Notes

- `400 INVALID_CORPORATE_NUMBER` (not 13 digits, or a failed check digit) and
  `400 INVALID_INPUT` are not retryable — fix the request.
- `404 CORPORATION_NOT_FOUND` means the (valid) number is not in the loaded
  dataset; the dataset may not cover that prefecture.
- `503 SERVICE_UNAVAILABLE` means the operator has not yet built the
  corporate-number dataset — retry later.
- Coverage is prefecture-scoped. Call `GET /stats` to see which prefectures
  are loaded.
- Data is from the 国税庁 法人番号公表サイト — commercial use is permitted with
  attribution.