Import API

Import API は、CSV などの持ち込みデータを account-scoped Import として保存し、行を canonical company_id に解決するための grouped 入出力 です。

手順全体を進める場合は 持ち込みImport を使ってください。このページは HTTP API と CLI JSON の返り値 の確認用です。

契約サマリー

production は API key 必須です。Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY> か x-api-key: <SIGNAL_FOUNDRY_API_KEY> を使います。通常 accountId / account_id は送りません。

resolve と select は クレジットを使う書き込みなので、HTTP では Idempotency-Key と maxCredits、CLI では --max-credits <n> --json を必ず付けます。

リクエスト

Create

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/imports" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-create-20260501-001" \
  -d '{
    "name": "展示会リード",
    "originalFilename": "companies.csv",
    "contentSha256": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
    "headers": ["会社名", "法人番号", "URL"],
    "rows": [
      {
        "会社名": "株式会社サンプル",
        "法人番号": "1234567890123",
        "URL": "https://example.com"
      }
    ]
  }'

行

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/imports/<importId>/rows" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>"

Map

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/imports/<importId>/map" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "company",
    "columns": {
      "name": "会社名",
      "corporate_number": "法人番号",
      "domain": "URL"
    }
  }'

columns の key は corporate_number domain name ticker です。entity は現時点では company のみです。

Resolve

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/imports/<importId>/resolve" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-resolve-<importId>-001" \
  -d '{
    "execute": true,
    "maxCredits": 100
  }'

行 needing review

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/imports/<importId>/rows?status=multiple_candidates&limit=50" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>"

status は repeated または comma separated で送れます。主な値は matched multiple_candidates not_found invalid unresolved です。

Select

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/imports/<importId>/select" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-select-<importRowId>-001" \
  -d '{
    "row": "<importRowId>",
    "companyId": "jpx_1234",
    "maxCredits": 1
  }'

companyId は、その 行の resolve_candidates[] に含まれる候補だけ指定できます。

Save

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/imports/<importId>/save" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "展示会リード"
  }'

save は、解決済み Import を 保存済みリストにします。解決できなかった 行 も Import 行 として保持され、黙って捨てられません。

レスポンス

共通 envelope

Import endpoint は成功時に次の共通 key を返します。

{
  "ok": true,
  "command": "import.resolve",
  "object": "import",
  "status": "completed",
  "import": {
    "import_id": "<importId>",
    "status": "resolved",
    "row_count": 3,
    "headers": ["会社名", "法人番号", "URL"],
    "mapping": {
      "entity": "company",
      "columns": {
        "name": "会社名"
      }
    },
    "resolve_summary": {
      "matched": 2,
      "multiple_candidates": 1,
      "not_found": 0,
      "invalid": 0,
      "total": 3
    }
  },
  "next_actions": [
    "sf import rows <importId> --status multiple_candidates --json"
  ]
}

Create / 行 / map

見る key:

• import.import_id
• import.row_count
• import.headers
• import.detected_identifier_columns
• import.mapping
• import.sample_rows
• deduplicated
• next_actions[]

Resolve

見る key:

• import.resolve_summary.matched
• import.resolve_summary.multiple_candidates
• import.resolve_summary.not_found
• resolution.matched
• resolution.multiple_candidates
• resolution.not_found
• resolution.resolved_count
• resolution.multiple_candidates_count
• resolution.not_found_count
• resolution.review_required_count
• run.resolved_count
• run.multiple_candidates_count
• run.not_found_count
• run.review_required_count
• billing.credits_used
• billing.max_credits
• next_actions[]

run.*_count は エージェント向けの stable count 入出力 です。resolution.*_count は同じ値の互換 alias です。run.resolved_count は matched 行数、run.review_required_count は multiple_candidates / not_found / invalid / unresolved の合計です。件数は billing から推測しないでください。

行

見る key:

• review.statuses
• review.total_reviewable_rows
• review.unresolved_rows_remaining
• rows[].import_row_id
• rows[].resolve_status
• rows[].resolve_candidates
• rows[].candidate_count
• rows[].needs_human

multiple_candidates は canonical data へ自動昇格しません。エージェントは rows[].resolve_candidates を人間に見せ、明示された候補だけ select します。

Select

見る key:

• selected.import_row_id
• selected.company_id
• selected.candidate
• billing.credits_used
• billing.deduplicated
• review.multiple_candidates_remaining
• next_actions[]

同じ行 / 会社 / idempotency key の再試行では二重消費しません。

行 status lifecycle

復旧方法

credit_balance_insufficient が出た場合は、sf credits balance --json または GET /credits/balance で今実行できるかを確認してください。

Next

• 手順全体を確認する: 持ち込みImport
• 保存済みリスト化後の API を確認する: リストAPI
• クレジット台帳 を確認する: GET /credits