データエンリッチメント

概要

• record_id を指定して、Sanka上の既存会社レコードを更新する方法
• seed を指定して、Sankaレコードなしで dry_run の候補だけ確認する方法

認証

• 外部連携では Authorization: Bearer <access_token> を使います
• OAuth経由の呼び出しでは、レコード更新に companies:write 権限が必要です
• seed を使った dry_run リクエストでは companies:read 権限で呼び出せます
• Sanka内部ツールでは X-Workspace-Code による認証も使えます

使う場面

• 企業プロフィールの不足項目を補完したいとき
• 古くなった会社情報をWeb上の情報で更新したいとき
• CRMレコードを更新する前に、項目ごとの根拠を確認したいとき

• object_type: company を指定します
• record_id または seed のどちらか片方を指定します
• record_id: Sanka上の既存会社レコードを補完するときのUUIDです
• seed: Sankaレコードを使わずに候補だけ確認したいときの一時的な会社情報です。name または url のどちらかが必要です

対応範囲

• v1では object_type=company のみ対応しています
• dry_run を使うと書き込みなしで更新候補を確認できます
• force_refresh を使うと既存値への上書き判定を行えます
• seed モードでは、Sankaの会社レコードがなくても会社名やURLだけを渡して試せます
• seed モードは dry_run のみで、Sanka上にエンリッチ実行履歴は保存されません

リクエストを送る

curl -X POST "https://api.sanka.com/v1/enrich" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "object_type": "company",
    "record_id": "11111111-2222-3333-4444-555555555555",
    "custom_field_map": {
      "industry": "cf_12345",
      "employee_count": "cf_67890"
    }
  }'

{
  "object_type": "company",
  "seed": {
    "name": "Acme",
    "external_id": "row_123"
  },
  "dry_run": true
}

レスポンスを確認する

• updated_builtin_fields: 実行中に更新された標準項目
• updated_custom_fields: 更新されたマッピング済みカスタム項目
• proposed_fields: パイプラインが候補として見つけた値
• field_evidence: 採用された値ごとの根拠情報
• skipped_fields: 信頼度や上書き条件を満たさず反映されなかった項目
• provider_meta: エンリッチメント提供元に関するメタ情報

{
  "data": {
    "company_id": "<company_uuid_or_null>",
    "seed_external_id": "<external_id_or_null>",
    "run_id": "<run_uuid>",
    "pipeline_version": "v1",
    "updated_builtin_fields": {},
    "updated_custom_fields": {},
    "proposed_fields": {},
    "field_evidence": {},
    "skipped_fields": {},
    "provider_meta": {}
  },
  "message": "ok",
  "ctx_id": "<ctx_id>"
}

dry_runとforce_refresh

{
  "object_type": "company",
  "record_id": "11111111-2222-3333-4444-555555555555",
  "dry_run": true
}

{
  "object_type": "company",
  "record_id": "11111111-2222-3333-4444-555555555555",
  "force_refresh": true
}