Skip to main content

​
概要

営業リストAPIには POST /v1/prospect/companies エンドポイントと、その動作を確認できるPlaygroundが含まれます。POST /v1/prospect/companies を使うと、自由文の検索条件や構造化フィルタをもとに、外部ソースから条件に合う会社候補を見つけられます。たとえば「東京の製造業で従業員200名以上」のような条件を渡すと、APIが検索条件を整理し、候補企業の一覧を返します。

​
認証

  • 外部連携では Authorization: Bearer <access_token> を使います
  • OAuth経由の呼び出しでは companies:read 権限が必要です
  • Sanka内部ツールでは X-Workspace-Code による認証も使えます

​
使う場面

次のような場面で利用します。
  • 条件に合う新規企業を検索して、営業候補を洗い出したいとき
  • 自然文の指示をそのままAPIに渡して候補一覧を取得したいとき
  • 会社名だけでなく、所在地、業種、従業員規模でも絞り込みたいとき
主な入力項目:
  • query: 自然文の検索条件
  • location: 地域や都市名
  • industry: 業種
  • min_employee_count と max_employee_count: 従業員数の範囲
  • limit: 返す件数。1 から 20 の範囲です
  • sources: 利用したい外部ソース。省略時は ["exa"] です

​
対応範囲

  • v1では会社候補の検索に対応しています
  • query または構造化フィルタのどちらかが必須です
  • レスポンスには、解釈された検索条件を示す parsed_filters が含まれます
  • このAPIは候補一覧を返す読み取り系APIで、Sanka上の会社レコードは作成・更新しません

​
リクエストを送る

curl -X POST "https://api.sanka.com/v1/prospect/companies" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "東京都の製造業で従業員200名以上の会社を探して",
    "limit": 10,
    "sources": ["exa"]
  }'
自然文を使わずに、構造化フィルタだけで検索することもできます。
{
  "location": "Tokyo",
  "industry": "manufacturing",
  "min_employee_count": 200,
  "limit": 10
}
同じリクエストは、このページのOpenAPIリファレンスにあるPlaygroundからも試せます。

​
レスポンスを確認する

レスポンスには次の情報が含まれます。
  • query: 実行時に使われた検索文字列
  • parsed_filters: APIが解釈した所在地、業種、従業員数の条件
  • results: 会社候補の一覧
  • count: 返された候補件数
  • provider_meta: ソース利用状況や抽出時のメタ情報
会社候補ごとに、会社名、URL、ドメイン、業種、従業員数、説明、根拠URL、関連する match_reasons などが返ります。
{
  "data": {
    "query": "東京都の製造業で従業員200名以上の会社を探して",
    "parsed_filters": {
      "location": "Tokyo",
      "industry": "manufacturing",
      "min_employee_count": 200
    },
    "results": [
      {
        "name": "Acme Manufacturing",
        "domain": "acme.example",
        "employee_count": 350,
        "source_urls": ["https://acme.example/about"],
        "match_reasons": ["industry match", "employee count match"]
      }
    ],
    "count": 1,
    "provider_meta": {}
  },
  "message": "Company prospecting completed",
  "ctx_id": "<ctx_id>"
}

​
利用できるソース

  • v1で実行される検索ソースは exa です
  • sources に複数の名前を渡せますが、未対応の名前は実行されません
  • たとえば google_maps を含めた場合は、provider_meta.unsupported_sources に記録されます
  • 利用状況は provider_meta.requested_sources、provider_meta.supported_sources、provider_meta.unsupported_sources で確認できます