API と Webhook

API キーで評価と結果の取得をし、変化を受け取る

API キーで、対象を集める・評価する・結果を読むことができます。Yoom・Make・n8n・Zapier などから HTTP で呼べます。

基本

URL: https://app.bizfetch.net/api/v1 に、下のパスを続けます
認証: Authorization: Bearer <API キー>（「組織と契約」の「API キーを発行」）。キーは組織ごとです
本文と応答: JSON（Content-Type: application/json）
エラー: {"error":{"code","message","request_id"}}。問い合わせのときは request_id を添えてください
出典: 公開情報を返す応答には attributions（提供元ごとの出典の文と URL）が付きます。BizFetch の外で使うときは、この文と URL を一緒に載せてください

評価の流れ

対象を集める
会社の一覧から対象を作ります。input_record_ref は呼ぶ側の行の番号（文字列）で、結果に同じ値が返ります。
```
POST /object-sets
{
  "template": "partner_check",
  "entry_kind": "list",
  "criteria": {},
  "items": [
    { "corporate_number": "1234567890123", "input_record_ref": "row-1" },
    { "name": "株式会社サンプル精工", "input_record_ref": "row-2" }
  ]
}
```
行ごとに、法人番号（corporate_number）か会社名（name）のどちらかを入れます。template は目的（sales・subsidy・tender・partner_check・company_check・disclosure_ip）です。会社の一覧から作るときは、entry_kind を list、criteria を空にします。
応答の object_set.id を控えます。会社名から会社を 1 つに決められなかった行があれば、GET /object-sets/{id} で状態を確かめます。
会社の一覧を送るほかに、次の集め方があります。items は送らず、entry_kind と criteria を指定します。
gbiz_search（営業対象を探す）
地域と規模で会社を探します。prefectures（都道府県の番号 01〜47。最大 10 件）、city（都道府県を 1 つにしたときの市区町村。全国地方公共団体コードの 3〜5 桁目）、corporate_types（法人の種類の番号。国税庁の法人番号の法人種別。301 株式会社・302 有限会社・305 合同会社など）、capital_stock_from・capital_stock_to（資本金、円）、employee_number_from・employee_number_to（従業員数、人）。1 回に 5,000 社まで
subsidies（補助金を探す）
criteria は空（{}）。BizFetch が毎日取得している募集中の公募を対象にします
tenders（入札案件を探す）
prefectures（都道府県の名前。1 つ以上）、date_from・date_to（期間、YYYY-MM-DD）
filings・applications（開示・知財情報を探す）
開示書類を見るときは filings、特許・意匠・商標だけを見るときは applications。rights（patent・design・trademark）、doc_types（EDINET の書類種別コード。120 有価証券報告書・140 四半期報告書・180 臨時報告書・350 大量保有報告書など。開示書類のとき）、companies（法人番号。空なら全部の会社）、date_from・date_to（期間、YYYY-MM-DD）
```
POST /object-sets
{
  "template": "tender",
  "entry_kind": "tenders",
  "criteria": { "prefectures": ["愛知県"], "date_from": "2026-10-01", "date_to": "2026-10-31" }
}
```
評価を始める
条件 ID（条件の画面のアドレスの /profiles/ の後ろ）と、対象の一覧を指定します。purpose は full にします。件数が少なければ 200 で結果まで返し、多ければ 202 で評価の情報だけを返します。どちらも応答の run.id を控えます。
```
POST /runs
{
  "profile_id": "<条件 ID>",
  "object_set_id": "<対象の一覧の ID>",
  "purpose": "full"
}
```

進み具合を読む

GET /runs/{id}
→ { "run": { "id", "seq", "status", "done", "total", ... } }

status が done になったら終わりです。

結果を読む
```
GET /runs/{id}/judgments?limit=50&offset=0
GET /judgments/{id}
```
一覧は対象ごとの総合の適合度と判定項目、内訳は判定項目ごとの判定・確率・判定の根拠の公開情報と出典を返します。候補は GET /marks?profile_id=<条件 ID>&kind=candidate、変化は GET /diff-events で読めます。

CSV

GET /runs/{id}/export.csv?set=candidates   # 候補にしたもの
GET /runs/{id}/export.csv?set=threshold    # 候補の目安以上
GET /runs/{id}/export.csv?set=all          # 評価したすべて

Webhook

「連携先」で種類に Webhook を選び、送り先の URL（https）を入れて追加します。署名の鍵は追加した直後に 1 回だけ出ます（API で作るときは POST /sinks の応答の webhook_signing_key）。鍵は組織ごとに 1 つです。

次の 2 種類を POST で送ります。受け取れなかったときは、24 時間まで送り直します。

run.done: 評価が終わった（本文に run と、対象の番号・書き出す項目）
diff.detected: 変化を見つけた（本文に diff_event と、対象の番号・書き出す項目）

署名を確かめる

要求には次のヘッダーが付きます。

X-BizFetch-Event: run.done か diff.detected
X-BizFetch-Timestamp: 送った時刻（UNIX 時間の秒）
X-BizFetch-Signature: v1= と、署名の 16 進

署名は、時刻.本文（ヘッダーの時刻、ピリオド、受け取った本文そのもの）を、署名の鍵で HMAC-SHA256 にかけたものです。同じ計算をして比べ、時刻が古すぎる要求は捨ててください（どこまでを古いとするかは、受け取る側で決めてください）。

// Node.js の例
import { createHmac, timingSafeEqual } from 'node:crypto';
const expected = 'v1=' + createHmac('sha256', signingKey).update(`${timestamp}.${rawBody}`).digest('hex');
const ok = expected.length === signature.length && timingSafeEqual(Buffer.from(expected), Buffer.from(signature));

API と Webhook

基本

評価の流れ

対象を集める

評価を始める

進み具合を読む

結果を読む

CSV

Webhook

署名を確かめる