API REFERENCE

Bango API ドキュメント

法人番号APIとインボイスAPIを統合した7エンドポイントの仕様をまとめています。実行確認は Playground を利用してください。

概要

法人番号APIとインボイスAPIを統合し、法人と個人事業主の両ケースをJSONで返します。

データ更新方針

国税庁の「法人番号公表サイト」と「適格請求書発行事業者公表サイト」の公表データを出典とし、日次で差分同期しています。取り込んだデータは統合・正規化・名寄せを行って提供します。反映のタイミングは国税庁の公表状況に依存するため、常に最新であることを保証するものではありません。各レスポンスの meta.source では、データの出典（name）と、取得できる場合は更新日（updated_at）を確認できます。Bango APIは国税庁の公表データを加工して提供するサービスであり、国税庁が本サービスの内容を保証するものではありません。

認証

x-api-key ヘッダーにAPIキーを指定します。キーはダッシュボードから発行・失効できます。

レート制限

Freeプランは通常4エンドポイント（法人番号検索・T番号検索・過去日付有効性確認・法人名検索）を月500コールまで利用できます。バッチ名寄せはGrowth以上が必要です。

エラー

公開APIのエラーは RFC 9457 の application/problem+json で返します。エラーコード全17種と、それぞれの意味・発生条件・回復手順はエラーリファレンスを参照してください。

仕様の正

本ドキュメントとOpenAPI仕様に矛盾がある場合はOpenAPIが正です。フィールドの有無・型・enum値の最終的な参照先はOpenAPI仕様（/v1/openapi.json）とします。

機械可読リソース

OpenAPI仕様とAIエージェント向けの概要を公開しています。

クイックスタート

最短で疎通確認するための手順です。まずは統合レスポンス `GET /v1/companies/{corporate_number}` で法人情報とインボイス情報をまとめて確認します。

1. x-api-key を発行してヘッダーに設定します。
2. GET /v1/companies/{corporate_number} を実行します。
3. 返却された法人情報とインボイス情報（invoice.*）を実装側の型に反映します。
補足: curlの出力を整形する場合は | jq . を使うと日本語のまま表示できます。python3 -m json.tool は既定の設定で日本語を \uXXXX にエスケープ表示しますが、APIの返却値自体はUTF-8の日本語のままです。

クイックスタートをPlaygroundで試す

バッチ名寄せの使い方

大量データは `POST /v1/batch/match` を起点に非同期で処理します。進捗確認とダウンロード導線までを一連で確認できます。

1. companies に企業名を複数行で入力してジョブを作成します。
2. GET /v1/batch/{job_id} を2秒間隔で確認し status が completed になるまで待ちます。
3. 完了後に GET /v1/batch/{job_id}/download で json / csv を取得します。

バッチ名寄せの使い方をPlaygroundで試す

個人事業主への対応

個人事業主ケースでは、Bango APIのプライバシー保護方針により個人を識別しうる情報を公開レスポンスで非開示とするため、表示・保存ロジックの分岐を事前に設計します。

GET /v1/invoice/{registration_number} で kind = individual の場合、corporate_number name name_kana name_en address trade_name popular_name は意図的に null で返します。
これは取得失敗やデータ欠損を意味しません。元データ側または内部DBで値を取得・保持できる場合でも、Bango APIでは個人情報・プライバシー保護のため公開APIから再配布しない方針です。
インボイス登録番号、登録状態、登録日、取消日、失効日、有効性、country、updated_at など、個人を直接識別する情報に当たらない現行フィールドは引き続き返します。
アプリ側では null 前提で表示をフォールバックし、インボイス有効性 (invoice.*) を中心に業務判定を行ってください。

個人事業主への対応をPlaygroundで試す

過去日付での有効性確認

`date=YYYY-MM-DD` を渡すことで、過去時点での登録有効性を判定できます。監査・経費精算用途では必須の確認です。

GET /v1/invoice/{registration_number}/valid?date=2024-10-01 のように実行します。
date は時刻・タイムゾーンを持たない暦日（YYYY-MM-DD）です。
date を省略した場合はJST（日本標準時）の今日を判定基準日とし、レスポンスの date に解決後の日付を返します。現在時点の有効性を確認したいときは date なしで実行できます。
取消日・失効日は当日から無効として判定されます。
返却される valid と cancel_date expire_date を使って、対象日での取引妥当性を判断します。

過去日付での有効性確認をPlaygroundで試す

GET

/v1/companies/{corporate_number}

法人番号検索

13桁の法人番号から法人情報とインボイス情報を返します。

パラメータ

name	in	type	required	description
corporate_number	path	string	Yes	13桁の法人番号

リクエスト例

curl -H 'x-api-key: YOUR_API_KEY' \
  'https://api.bango-api.jp/v1/companies/1180301018771'

レスポンス例

{
  "object": "company",
  "schema_version": "2026-08",
  "data": {
    "corporate_number": "1180301018771",
    "name": "トヨタ自動車株式会社",
    "name_kana": "トヨタジドウシャ",
    "name_en": null,
    "kind": "株式会社",
    "kind_code": "301",
    "address": {
      "prefecture": "愛知県",
      "city": "豊田市",
      "full": "愛知県豊田市トヨタ町１番地"
    },
    "active": true,
    "closure": null,
    "assignment_date": "2015-10-05",
    "updated_at": "2019-04-23",
    "invoice": {
      "found": true,
      "registration_number": "T1180301018771",
      "registered": true,
      "registration_date": "2023-10-01",
      "cancel_date": null,
      "expire_date": null,
      "valid": true
    }
  },
  "links": {
    "self": "https://api.bango-api.jp/v1/companies/1180301018771",
    "docs": "https://bango-api.jp/docs",
    "invoice": "https://api.bango-api.jp/v1/invoice/T1180301018771"
  },
  "meta": {
    "source": { "name": "nta", "updated_at": "2019-04-23" },
    "rate_limit": {
      "unlimited": false,
      "limit": 600,
      "remaining": 598,
      "reset": "2026-01-15T00:01:00Z"
    },
    "quota": {
      "api_requests": { "unlimited": false, "limit": 10000, "remaining": 9876 },
      "batch_rows": null
    }
  }
}

レスポンス項目

field	type	nullable	description
object	string	No	オブジェクト種別（例: company / invoice_issuer / batch_job）
schema_version	string	No	現行構造の最終変更年月（YYYY-MM・情報提供専用）
data	object	No	レスポンス本体。以降のフィールドは data 内側の構造
links	object	No	関連リンク。self/docs は常設、関連キー（invoice/company/next 等）はエンドポイント別で値なしはnull
meta	object	No	source（NTA更新日）・rate_limit・quota（api_requests/batch_rows）。batch_rows は batch系のみnon-null
corporate_number	string	No	13桁の法人番号
name	string	No	商号または名称
name_kana	string	Yes	商号または名称（カナ表記）
name_en	string	Yes	商号または名称（英語表記）
kind	string	No	法人種別（例: 株式会社）
address.full	string	Yes	本店所在地の完全住所
active	boolean	No	現時点で活動中かどうか
assignment_date	string	Yes	法人番号指定日（YYYY-MM-DD）
updated_at	string	Yes	最終更新日（YYYY-MM-DD）
invoice.found	boolean	No	インボイス情報が見つかったかどうか
invoice.registration_number	string	Yes	インボイス登録番号（T + 13桁）
invoice.registered	boolean	No	適格請求書発行事業者として登録されているか
invoice.registration_date	string	Yes	登録日（YYYY-MM-DD）
invoice.cancel_date	string	Yes	取消日（YYYY-MM-DD）
invoice.expire_date	string	Yes	失効日（YYYY-MM-DD）
invoice.valid	boolean	Yes	現時点で有効な登録番号かどうか

このエンドポイントをPlaygroundで試す

GET

/v1/invoice/{registration_number}

T番号検索

T番号から法人情報または個人事業主情報（個人情報はnull）を返します。

パラメータ

name	in	type	required	description
registration_number	path	string	Yes	T + 13桁の登録番号

リクエスト例

curl -H 'x-api-key: YOUR_API_KEY' \
  'https://api.bango-api.jp/v1/invoice/T1180301018771'

レスポンス例

{
  "object": "invoice_issuer",
  "schema_version": "2026-08",
  "data": {
    "corporate_number": null,
    "kind": "individual",
    "name": null,
    "address": null,
    "invoice": {
      "found": true,
      "registration_number": "T6810924593403",
      "registration_date": "2026-01-01",
      "valid": true
    }
  },
  "links": {
    "self": "https://api.bango-api.jp/v1/invoice/T6810924593403",
    "docs": "https://bango-api.jp/docs",
    "company": null
  },
  "meta": {
    "source": { "name": "nta", "updated_at": "2026-01-13" },
    "rate_limit": {
      "unlimited": false,
      "limit": 600,
      "remaining": 598,
      "reset": "2026-01-15T00:01:00Z"
    },
    "quota": {
      "api_requests": { "unlimited": false, "limit": 10000, "remaining": 9876 },
      "batch_rows": null
    }
  }
}

レスポンス項目

field	type	nullable	description
object	string	No	オブジェクト種別（例: company / invoice_issuer / batch_job）
schema_version	string	No	現行構造の最終変更年月（YYYY-MM・情報提供専用）
data	object	No	レスポンス本体。以降のフィールドは data 内側の構造
links	object	No	関連リンク。self/docs は常設、関連キー（invoice/company/next 等）はエンドポイント別で値なしはnull
meta	object	No	source（NTA更新日）・rate_limit・quota（api_requests/batch_rows）。batch_rows は batch系のみnon-null
corporate_number	string	Yes	法人の場合は13桁の法人番号、個人事業主はnull
kind	string	No	種別（法人または individual）
name	string	Yes	名称。個人事業主ケースではnull
name_kana	string	Yes	名称カナ。個人事業主ケースではnull
trade_name	string	Yes	個人事業主の屋号。存在しない場合はnull
popular_name	string	Yes	個人事業主の通称・旧姓。存在しない場合はnull
address	object	Yes	所在地情報。個人事業主ケースではnull
invoice.found	boolean	No	インボイス情報が見つかったかどうか
invoice.registration_number	string	No	インボイス登録番号（T + 13桁）
invoice.registration_date	string	Yes	登録日（YYYY-MM-DD）
invoice.cancel_date	string	Yes	取消日（YYYY-MM-DD）
invoice.expire_date	string	Yes	失効日（YYYY-MM-DD）
invoice.valid	boolean	No	現時点で有効な登録番号かどうか

注意事項

個人事業主ケースでは name / address / trade_name / popular_name は null です。

このエンドポイントをPlaygroundで試す

GET

/v1/invoice/{registration_number}/valid

過去日付有効性確認

指定日付時点で登録番号が有効かを判定します。

パラメータ

name	in	type	required	description
registration_number	path	string	Yes	T + 13桁
date	query	string	No	判定対象の暦日（YYYY-MM-DD、時刻・タイムゾーンなし）。省略時はJST今日で判定します。

リクエスト例

curl -G -H 'x-api-key: YOUR_API_KEY' \
  --data-urlencode 'date=2024-10-01' \
  'https://api.bango-api.jp/v1/invoice/T1180301018771/valid'

レスポンス例

{
  "object": "invoice_validity",
  "schema_version": "2026-08",
  "data": {
    "registration_number": "T1180301018771",
    "date": "2024-10-01",
    "valid": true,
    "registration_date": "2023-10-01",
    "expire_date": null,
    "cancel_date": null
  },
  "links": {
    "self": "https://api.bango-api.jp/v1/invoice/T1180301018771/valid",
    "docs": "https://bango-api.jp/docs",
    "invoice": "https://api.bango-api.jp/v1/invoice/T1180301018771"
  },
  "meta": {
    "source": { "name": "nta", "updated_at": "2021-10-28" },
    "rate_limit": {
      "unlimited": false,
      "limit": 600,
      "remaining": 598,
      "reset": "2026-01-15T00:01:00Z"
    },
    "quota": {
      "api_requests": { "unlimited": false, "limit": 10000, "remaining": 9876 },
      "batch_rows": null
    }
  }
}

レスポンス項目

field	type	nullable	description
object	string	No	オブジェクト種別（例: company / invoice_issuer / batch_job）
schema_version	string	No	現行構造の最終変更年月（YYYY-MM・情報提供専用）
data	object	No	レスポンス本体。以降のフィールドは data 内側の構造
links	object	No	関連リンク。self/docs は常設、関連キー（invoice/company/next 等）はエンドポイント別で値なしはnull
meta	object	No	source（NTA更新日）・rate_limit・quota（api_requests/batch_rows）。batch_rows は batch系のみnon-null
registration_number	string	No	判定対象の登録番号（T + 13桁）
date	string	No	判定対象日（YYYY-MM-DD）
valid	boolean	No	対象日での有効性
registration_date	string	Yes	登録日（YYYY-MM-DD）
expire_date	string	Yes	失効日（YYYY-MM-DD）
cancel_date	string	Yes	取消日（YYYY-MM-DD）

注意事項

date は時刻を持たない暦日として扱います。取消日・失効日は当日から無効です。
date を省略した場合はJST（日本標準時）の今日を判定基準日とし、レスポンスの date にその解決後の日付を返します。

このエンドポイントをPlaygroundで試す

GET

/v1/companies/search

法人名検索

部分一致（partial）または法人格除去完全一致（exact）で検索します。

パラメータ

name	in	type	required	description
q	query	string	Yes	検索クエリ（1文字以上200文字以内）
mode	query	string	No	partial / exact
prefecture_code	query	string	No	都道府県コード（2桁）
limit	query	number	No	件数（1〜50）

リクエスト例

curl -G -H 'x-api-key: YOUR_API_KEY' \
  --data-urlencode 'q=トヨタ自動車' \
  --data-urlencode 'mode=partial' \
  --data-urlencode 'limit=2' \
  'https://api.bango-api.jp/v1/companies/search'

レスポンス例

{
  "object": "list",
  "item": "company_summary",
  "schema_version": "2026-08",
  "data": [
    {
      "object": "company_summary",
      "corporate_number": "1180301018771",
      "name": "トヨタ自動車株式会社",
      "name_kana": "トヨタジドウシャ",
      "prefecture_code": "23",
      "city_code": "23211",
      "score": 0.857143
    },
    {
      "object": "company_summary",
      "corporate_number": "1430005009042",
      "name": "トヨタ自動車北海道労働組合",
      "name_kana": "トヨタジドウシャホッカイドウ",
      "prefecture_code": "01",
      "city_code": "01213",
      "score": 0.857143
    }
  ],
  "has_more": true,
  "offset": 0,
  "limit": 2,
  "facets": null,
  "links": {
    "self": "https://api.bango-api.jp/v1/companies/search?q=...",
    "docs": "https://bango-api.jp/docs",
    "next": "https://api.bango-api.jp/v1/companies/search?q=...&limit=2&offset=2"
  },
  "meta": {
    "source": { "name": "nta", "updated_at": null },
    "rate_limit": {
      "unlimited": false,
      "limit": 600,
      "remaining": 598,
      "reset": "2026-01-15T00:01:00Z"
    },
    "quota": {
      "api_requests": { "unlimited": false, "limit": 10000, "remaining": 9876 },
      "batch_rows": null
    }
  }
}

レスポンス項目

field	type	nullable	description
object	string	No	一覧エンベロープ種別（list 固定）
item	string	No	data 配列要素のオブジェクト種別（例: company_summary / batch_result_row）。各要素の object も同値
schema_version	string	No	現行構造の最終変更年月（YYYY-MM・情報提供専用）
data	array	No	一致した要素の配列。以降のフィールドは各要素（item）の構造
has_more	boolean	No	続きの実在を示す。offset+limit が上限に達した場合 links.next はnull（打ち切り）
offset	number	No	取得開始位置（0起点）
limit	number	No	取得件数上限
links	object	No	self/docs は常設、next は最終ページ/打ち切り時はnull
meta	object	No	source（一覧では updated_at=null）・rate_limit・quota。batch_rows は batch系のみnon-null
facets	object	Yes	facetsパラメータ指定時のみnon-null（軸名→{value,count}[]）。それ以外はnull
corporate_number	string	No	候補企業の法人番号
name	string	No	候補企業の名称
name_kana	string	Yes	候補企業の名称カナ
prefecture_code	string	Yes	都道府県コード（2桁）
city_code	string	Yes	市区町村コード
score	number	No	検索順位付けに使う相対スコア（0〜1）。正解確率・信頼度ではなく、mode=partial では接頭辞一致などで複数候補が同値になりうる。

注意事項

mode=partial で q が1文字の場合は 400 VALIDATION_ERROR です。
mode=exact は1文字でも検索できます。

このエンドポイントをPlaygroundで試す

POST

/v1/batch/match

バッチ名寄せ受付

企業名リストを投稿して非同期ジョブを作成します。

パラメータ

name	in	type	required	description
companies	body	string[]	Yes	企業名配列（最大1,000件）

リクエスト例

curl -X POST -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"companies":["株式会社サンプル","合同会社サンプル"]}' \
  'https://api.bango-api.jp/v1/batch/match'

レスポンス例

{
  "object": "batch_job",
  "schema_version": "2026-08",
  "data": {
    "job_id": "batch_abc123",
    "status": "queued"
  },
  "links": {
    "self": "https://api.bango-api.jp/v1/batch/match",
    "docs": "https://bango-api.jp/docs",
    "status": "https://api.bango-api.jp/v1/batch/batch_abc123"
  },
  "meta": {
    "source": { "name": "nta", "updated_at": null },
    "rate_limit": {
      "unlimited": false,
      "limit": 600,
      "remaining": 598,
      "reset": "2026-01-15T00:01:00Z"
    },
    "quota": {
      "api_requests": { "unlimited": false, "limit": 10000, "remaining": 9876 },
      "batch_rows": { "unlimited": false, "limit": 10000, "remaining": 9000 }
    }
  }
}

レスポンス項目

field	type	nullable	description
object	string	No	オブジェクト種別（例: company / invoice_issuer / batch_job）
schema_version	string	No	現行構造の最終変更年月（YYYY-MM・情報提供専用）
data	object	No	レスポンス本体。以降のフィールドは data 内側の構造
links	object	No	関連リンク。self/docs は常設、関連キー（invoice/company/next 等）はエンドポイント別で値なしはnull
meta	object	No	source（NTA更新日）・rate_limit・quota（api_requests/batch_rows）。batch_rows は batch系のみnon-null
job_id	string	No	作成されたバッチジョブID
status	string	No	初期状態（queued）

このエンドポイントをPlaygroundで試す

GET

/v1/batch/{job_id}

バッチ進捗取得

job_id の進捗と結果を取得します。

パラメータ

name	in	type	required	description
job_id	path	string	Yes	バッチジョブID

リクエスト例

curl -H 'x-api-key: YOUR_API_KEY' \
  'https://api.bango-api.jp/v1/batch/job_00000000-0000-4000-8000-000000000000'

レスポンス例

{
  "object": "batch_job",
  "schema_version": "2026-08",
  "data": {
    "job_id": "batch_abc123",
    "status": "processing",
    "progress": { "done": 450, "total": 1000 }
  },
  "links": {
    "self": "https://api.bango-api.jp/v1/batch/batch_abc123",
    "docs": "https://bango-api.jp/docs",
    "download": null
  },
  "meta": {
    "source": { "name": "nta", "updated_at": null },
    "rate_limit": {
      "unlimited": false,
      "limit": 600,
      "remaining": 598,
      "reset": "2026-01-15T00:01:00Z"
    },
    "quota": {
      "api_requests": { "unlimited": false, "limit": 10000, "remaining": 9876 },
      "batch_rows": { "unlimited": false, "limit": 10000, "remaining": 9000 }
    }
  }
}

レスポンス項目

field	type	nullable	description
object	string	No	オブジェクト種別（例: company / invoice_issuer / batch_job）
schema_version	string	No	現行構造の最終変更年月（YYYY-MM・情報提供専用）
data	object	No	レスポンス本体。以降のフィールドは data 内側の構造
links	object	No	関連リンク。self/docs は常設、関連キー（invoice/company/next 等）はエンドポイント別で値なしはnull
meta	object	No	source（NTA更新日）・rate_limit・quota（api_requests/batch_rows）。batch_rows は batch系のみnon-null
job_id	string	No	対象バッチジョブID
status	string	No	ジョブ状態（queued / processing / completed / failed）
progress.done	number	Yes	処理済み件数
progress.total	number	Yes	総件数
summary.confident	number	Yes	confident 判定件数（completed時）
summary.review	number	Yes	review 判定件数（completed時）
summary.unmatched	number	Yes	unmatched 判定件数（completed時）

このエンドポイントをPlaygroundで試す

GET

/v1/batch/{job_id}/download

バッチ結果ダウンロード

完了済みジョブの結果を json または csv で取得します。

パラメータ

name	in	type	required	description
job_id	path	string	Yes	バッチジョブID
format	query	string	No	json / csv

リクエスト例

curl -G -H 'x-api-key: YOUR_API_KEY' \
  --data-urlencode 'format=csv' \
  'https://api.bango-api.jp/v1/batch/job_00000000-0000-4000-8000-000000000000/download'

レスポンス例

{
  "object": "list",
  "item": "batch_result_row",
  "schema_version": "2026-08",
  "data": [
    {
      "object": "batch_result_row",
      "row_index": 1,
      "input_name": "株式会社サンプル",
      "prefecture_code": "13",
      "confidence": "confident",
      "score": 0.97,
      "candidate_count": 1,
      "matched_corporate_number": "1234567890123",
      "candidates": [
        {
          "corporate_number": "1234567890123",
          "name": "株式会社サンプル",
          "name_kana": "カブシキガイシャサンプル",
          "score": 0.97
        }
      ]
    }
  ],
  "has_more": false,
  "offset": 0,
  "limit": 10,
  "links": {
    "self": "https://api.bango-api.jp/v1/batch/batch_abc123/download",
    "docs": "https://bango-api.jp/docs"
  },
  "meta": {
    "source": { "name": "nta", "updated_at": null },
    "rate_limit": {
      "unlimited": false,
      "limit": 600,
      "remaining": 598,
      "reset": "2026-01-15T00:01:00Z"
    },
    "quota": {
      "api_requests": { "unlimited": false, "limit": 10000, "remaining": 9876 },
      "batch_rows": { "unlimited": false, "limit": 10000, "remaining": 9000 }
    }
  }
}

レスポンス項目

field	type	nullable	description
object	string	No	一覧エンベロープ種別（list 固定）
item	string	No	data 配列要素のオブジェクト種別（例: company_summary / batch_result_row）。各要素の object も同値
schema_version	string	No	現行構造の最終変更年月（YYYY-MM・情報提供専用）
data	array	No	一致した要素の配列。以降のフィールドは各要素（item）の構造
has_more	boolean	No	続きの実在を示す。offset+limit が上限に達した場合 links.next はnull（打ち切り）
offset	number	No	取得開始位置（0起点）
limit	number	No	取得件数上限
links	object	No	self/docs は常設、next は最終ページ/打ち切り時はnull
meta	object	No	source（一覧では updated_at=null）・rate_limit・quota。batch_rows は batch系のみnon-null
row_index	number	No	入力行番号（0起点または1起点）
input_name	string	No	入力した企業名
prefecture_code	string	Yes	入力から抽出した都道府県コード（任意）
confidence	string	No	判定区分（confident / review / unmatched）
score	number	No	最良候補の一致スコア（0〜1）
candidate_count	number	No	候補件数
matched_corporate_number	string	Yes	確定した法人番号（未確定時はnull）
candidates[].corporate_number	string	No	候補の法人番号
candidates[].name	string	No	候補の名称
candidates[].name_kana	string	Yes	候補の名称カナ
candidates[].score	number	No	候補の一致スコア（0〜1）

注意事項

上記は format=json（既定）かつ completed 時のレスポンスで、data 配列に各行（batch_result_row）を並べた一覧エンベロープです。format=csv では同じ結果をCSV文字列で返します。
status=queued/processing では 409 BATCH_NOT_COMPLETED を返します。
status=failed では 409 BATCH_FAILED を返します。

このエンドポイントをPlaygroundで試す

概要

データ更新方針

認証

レート制限

エラー

仕様の正

機械可読リソース

関連ガイド

パラメータ

リクエスト例

レスポンス例

レスポンス項目

関連ガイド

パラメータ

リクエスト例

レスポンス例

レスポンス項目

注意事項

関連ガイド

パラメータ

リクエスト例

レスポンス例

レスポンス項目

注意事項

関連ガイド

パラメータ

リクエスト例

レスポンス例

レスポンス項目

注意事項

関連ガイド

パラメータ

リクエスト例

レスポンス例

レスポンス項目

関連ガイド

パラメータ

リクエスト例

レスポンス例

レスポンス項目

関連ガイド

パラメータ

リクエスト例

レスポンス例

レスポンス項目

注意事項