法人番号 API ドキュメント
全 5 エンドポイントの仕様・レスポンス・エラー・上限
ベース URL: https://shirabe.dev。キーなしで月 5,000 回まで利用できます。
製品概要と料金はこちら。
クイックスタート
curl -X POST https://shirabe.dev/api/v1/corporation/lookup \
-H "Content-Type: application/json" \
-d '{"law_id": "7000012050002"}'有料プランのキーは X-API-Key ヘッダーで渡します(キーなし = 匿名 Free 扱い)。
エンドポイント一覧
| メソッド | パス | 説明 |
|---|---|---|
POST | /api/v1/corporation/lookup | 法人番号 → 法人情報 |
POST | /api/v1/corporation/search | 商号の前方一致検索(都道府県・市区町村で絞り込み可) |
POST | /api/v1/corporation/validate | 法人番号の形式・checksum・実在の 3 段判定 |
POST | /api/v1/corporation/normalize | 商号表記の正規化 + 法人種別の分離 |
POST | /api/v1/corporation/batch | 複数法人番号の一括 lookup(最大 100 件) |
GET | /api/v1/corporation/health | ヘルスチェック(認証不要・カウント対象外) |
POST /api/v1/corporation/lookup
リクエスト: { "law_id": "7000012050002" }(13 桁法人番号)
レスポンス(実例):
{
"corporation": {
"lawId": "7000012050002",
"name": "国税庁",
"nameKana": "コクゼイチョウ",
"nameEnglish": "National Tax Agency",
"corpType": "101",
"prefecture": "東京都",
"city": "千代田区",
"street": "霞が関３丁目１－１",
"prefectureCode": "13",
"cityCode": "101",
"postalCode": "1000013",
"assignedAt": "2015-10-05",
"closedAt": null,
"closedReason": null,
"successorLawId": null,
"latest": true,
"searchExcluded": false
},
"attribution": {
"source": "国税庁法人番号公表サイト",
"provider": "国税庁"
}
}
閉鎖済み法人は closedAt / closedReason / 承継先 successorLawId が入ります。
未登録の法人番号は 404 NOT_FOUND。
POST /api/v1/corporation/search
リクエスト(name のみ必須):
{
"name": "トヨタ自動車",
"prefecture_code": "23",
"city_code": null,
"limit": 10,
"offset": 0
}
レスポンスは results 配列(各要素は lookup の corporation と同じ形)。
商号の前方一致で、prefecture_code / city_code で絞り込み、
limit / offset でページングします。
POST /api/v1/corporation/validate
リクエスト: { "law_id": "7000012050002" }
レスポンス(実例):
{
"lawId": "7000012050002",
"formatValid": true,
"checksumValid": true,
"valid": true,
"existsInRegistry": true
}
形式(13 桁)→ checksum(mod-9)→ 登録簿の実在、の 3 段で判定します。
KYC・入力バリデーションでは existsInRegistry までの確認を推奨します。
POST /api/v1/corporation/normalize
リクエスト: { "name": "ﾄﾖﾀ自動車(株)" }
レスポンス(実例):
{
"input": "ﾄﾖﾀ自動車(株)",
"normalized": "トヨタ自動車株式会社",
"corpType": "株式会社",
"corpTypePosition": "suffix",
"baseName": "トヨタ自動車"
}
半角カナ・略記(「(株)」等)を正規化し、法人種別と固有名部分(baseName)を分離します。
search の前処理に使うとヒット率が上がります。
POST /api/v1/corporation/batch
リクエスト(最大 100 件。超過は 400 BATCH_TOO_LARGE):
{ "law_ids": ["7000012050002", "1234567890123"] }
checksum 不正な番号もエラーにせず、要素ごとに valid: false として入力順で返します
(一括照合でパイプラインが止まらない設計)。カウントは要素数 N = N 回分です。
エラー
エラーは全て次の形で返ります:
{ "error": { "code": "...", "message": "..." } }| HTTP | code(代表) | 意味と対処 |
|---|---|---|
| 400 | INVALID_REQUEST / INVALID_LAW_ID / BATCH_TOO_LARGE | 入力不正。カウントされません |
| 404 | NOT_FOUND | 登録簿に存在しない法人番号(lookup) |
| 401 | INVALID_API_KEY | 形式不正・未登録のキー。キーを外すと匿名 Free で通ります |
| 429 | USAGE_LIMIT_EXCEEDED | 月間上限。Retry-After と次プランへの next_plan.checkout_path(→ /corporation/buy)を同梱 |
| 503 | SERVICE_UNAVAILABLE | データ層の一時障害。カウントされません。リトライしてください |
上限とカウント規則
| プラン | 月間上限 |
|---|---|
| Free | 5,000 回 |
| Starter | 200,000 回 |
| Pro | 2,000,000 回 |
| Enterprise | 無制限 |
- lookup / search / validate / normalize = 1 リクエスト 1 カウント、batch = 要素数 N カウント
- 400 系・401・404・503 はカウントされません(無料枠を消費しない)
- 月間カウントは毎月 1 日 0:00 UTC にリセット
データ出典と更新
- 出典: 国税庁法人番号公表サイト(公共データ利用規約)。レスポンスに
attributionを常に同梱 - 収録: 全国の公表法人 約 579 万社(閉鎖法人情報を含む)
AI 統合・機械可読仕様
- OpenAPI 3.1:
https://shirabe.dev/api/v1/corporation/openapi.yaml