持ち込みImport

CSV や外部行を持ち込み、正規化済みの会社に解決して、保存済みリスト と 列 / export まで進めます。

いつ使うか

• 展示会リード、既存顧客、外部調査の CSV を Signal Foundry の ワークスペースに置きたい
• CSV の会社名、法人番号、証券コード、domain を canonical company_id に解決したい
• multiple_candidates を人間が確認してから 保存済みリストにしたい
• 保存後に website 列を足し、CSV で export したい

自然文から会社群を探す場合は、このページではなく リスト作成ループ を使います。

CSV shape before import

CSV には、会社を識別できる 列を少なくとも 1 つ含めます。精度を上げるには、会社名だけでなく法人番号、証券コード、domain を足してください。

会社名,法人番号,証券コード,URL
株式会社サンプル,1234567890123,1234,https://example.com

CSV 例に API key、顧客秘密情報、private URL、raw transcript を入れないでください。エージェントに渡す sample は匿名化した値にしてください。

Import

まず CSV を Import として保存します。

sf import csv ./companies.csv --name "展示会リード" --json

見る key:

• import.import_id
• import.row_count
• actions[]

import.import_id を以後の <importId> として使います。import csv / 行は クレジットを消費しません。

行

headers、行 count、現在の resolve 状態を確認します。

sf import rows <importId> --json

見る key:

• import.import_id
• import.row_count
• rows[]
• review

ここで必須 列 が足りない場合は、CSV を直して import し直します。会社名だけで曖昧になりそうな行は、法人番号、証券コード、domain のどれかを追加してください。

Resolve with クレジット cap

import 行を 正規化済みの会社に解決します。

sf import resolve <importId> --max-credits 100 --json

必要に応じて --max-credits <n> で上限を明示します。

見る key:

• resolution.resolved_count
• resolution.multiple_candidates_count
• resolution.not_found_count
• resolution.review_required_count
• cost.credits_used
• billing

クレジットは matched 行の Basic クレジットで発生します。エージェントは billing から件数を推測せず、resolution.*_count を読みます。multiple_candidates は勝手に 1 社へ確定しません。

Review and select ambiguous 行

multiple_candidates が 1 件でもある場合は、review で候補を確認します。

sf import rows <importId> --status multiple_candidates --json

見る key:

• review.total_reviewable_rows
• rows[].import_row_id
• rows[].resolve_status
• rows[].resolve_candidates
• rows[].needs_human

人間が候補を選んだ 行だけ select します。

sf import select <importId> --row <rowId> --company <companyId> --max-credits 1 --json

見る key:

• selected.import_row_id
• selected.company_id
• billing.credits_used
• review.multiple_candidates_remaining
• next_actions

import select は新しく確定する 行にだけ Basic クレジットを使います。候補に含まれない company_id は指定しないでください。

Create リスト

resolve 済み 行 から 保存済みリストを作ります。

sf import save <importId> --name "展示会リード" --json

見る key:

• list.list_id
• list.row_count
• import.import_id
• import_rows
• billing.credits_used

この時点で 保存済みリストになり、UI では リスト / 行 / 根拠 / 実行を確認できます。preview ではないため、次に 列 と export へ進めます。

Add more 行 later

既存の 保存済みリストに直接 行を append する 公開 command はまだありません。追加会社を持ち込む場合は、新しい Import として作り、resolve 後に新しい 保存済みリスト として保存します。

sf import csv ./more-companies.csv --name "追加リード" --json
sf import resolve <importId> --max-credits 100 --json
sf import save <importId> --name "追加リード" --json

見る key:

• import.import_id
• resolution.resolved_count
• resolution.multiple_candidates_count
• list.list_id
• billing.credits_used

sf list append --help / sf import append --help も同じ recovery を返します。直接 append を前提にした command を エージェントが作らないようにしてください。

列 / export

website 列は estimate してから実行します。

sf list column add <listId> website_presence --estimate --json
sf list column add <listId> website_presence --execute --max-credits 100 --json
sf list export <listId> --format csv --output ./exports/imported-leads.csv --json

見る key:

• column.column_key
• estimate.total_rows
• estimate.target_rows
• run.run_id
• run.found_count
• run.not_found_count
• billing.credits_used
• export.path
• export.row_count
• export.sha256

column add は追加列 / 実行を作るため、実行時に クレジット 境界があります。export は 保存済みリスト から出力します。preview や unresolved 行は export 前に確定してください。

確認する key

このワークフロー 全体では、次の key を順番に確認します。

• import.import_id
• import.row_count
• resolution.resolved_count
• resolution.multiple_candidates_count
• resolution.not_found_count
• resolution.review_required_count
• cost.credits_used
• list.list_id
• import_rows
• run.run_id
• export.sha256

If it fails

必要な列が足りない場合:

1. sf import rows <importId> --json を実行します。
2. rows[] と import の warning を確認します。
3. CSV header 名を直して sf import csv ... --json からやり直します。

max_credits_exceeded が返る場合:

1. resolution.resolved_count と billing を確認します。
2. 行を分割するか、--max-credits <n> を見積もり以上にして再実行します。
3. クレジット残量が不明なら sf credits balance --json を実行します。

multiple_candidates が残る場合:

1. sf import rows <importId> --status multiple_candidates --json を実行します。
2. rows[].resolve_candidates を人間に見せます。
3. 自動確定せず、明示された候補だけ sf import select ... --json で確定します。

not_found が多い場合:

1. 会社名だけでなく、法人番号、証券コード、domain を CSV に追加します。
2. CSV を更新して sf import csv から再実行します。
3. それでも候補がない 行は company_not_found として扱い、silent 0 件にしないでください。

Next

• import API の入出力 を確認する: Import API
• 保存済みリストの標準 loop を確認する: リスト作成ループ
• export まで含めた リスト API を確認する: リストAPI