human-survey

HumanSurvey

ウェブサイト: humansurvey.co · ドキュメント: humansurvey.co/docs · よくある質問: humansurvey.co/faq

リファラーがないチャネルのアトリビューション。

HumanSurveyは、ホスト自身の登録または決済フロー内で「どこで知りましたか？」という質問をします。実際にアクションにつなげられる粒度で、まずプラットフォームを尋ね、次にどのクリエイター、ポッドキャスト、イベント、店舗なのかを尋ねます。

Agent configures a form   → platforms from the catalog, creators supplied by the caller
Host embeds /s/{id}       → in its signup flow, its payment flow, or both
Respondent answers        → picks a platform; that pick expands the follow-up in place
Host pushes conversions   → POST /api/attribution/events, keyed on its own user id
Agent reads back          → rollup, raw response stream, free text awaiting a mapping

これは何ですか？

自己申告型アトリビューションのためのAPIおよびMCP サーバーです。TikTokアプリ内、Instagram、ポッドキャスト、コミュニティ、口コミ、AI アシスタントなど、トラッキングが届かない場所で接触が発生する場合、リファラー情報の漏れを超えて常に得られる唯一のシグナルは、人に尋ねることです。

2つの設置場所で、それぞれ異なる質問に答えられます。決済フローでは、回答者はすでに有料顧客であるため、コンバージョンデータの取り込みを一切行わずに、回答を売上に結び付けられます。登録フローでは、チャネルから流入したものの支払いに至らなかった人を把握できる唯一の方法です。有料ユーザー全体に占めるチャネルの割合を、登録ユーザー全体に占めるそのチャネルの割合で割ります。1を超える場合は平均よりコンバージョン率が高く、1を下回る場合は低くなります。この比率に全体の登録から有料への転換率を掛けると、そのチャネル独自の転換率が得られます。

次の用途向けに設計されています。

• ホスト自身のオンボーディングまたはチェックアウトにフォームを埋め込む場合
• 候補リストを最新の状態に保ち、結果を読み取るエージェント

次の用途向けには設計されていません。

• 汎用アンケート — アトリビューションに方針転換した際に、任意の質問形式、Markdownでの作成、条件付きロジックは削除されました
• 人間向けの分析ダッシュボード — 集計データはAPIリソースであり、エージェントがダッシュボードです
• オーディエンスへの代行連絡 — HumanSurveyが回答者に連絡することはありません。提供する配信方法（/s/{id} URLとiframe埋め込み）は、いずれもお客様が管理します

機能

• ページネーションではなく、段階的な情報開示 — プラットフォームの回答をPOSTし、追加質問への回答をPATCHします。最初の回答は2つ目の質問をする前に確実に保存され、追加質問の途中で離脱した回答者の回答も有効なデータとして残ります。
• デフォルトで順序を入れ替え — 順序を並べ替え可能な候補は、クライアントが生成したrender_idをシードとして回答者ごとに並べ替えられるため、生の構成比は仕組み上偏りません。呼び出し元が希望する場合はfixed順序も利用できますが、その場合の偏りは隠されません。
• 事後的な再マッピング — 自由入力はそのまま保存され、読み取りのたびに再マッピングテーブルと照合されるため、1つのマッピングでバックフィルなしに数か月分の履歴を修正できます。
• 不変の設定スナップショット — 回答は表示時に使われたバージョンに結び付けられるため、設定を変更しても、過去に表示された内容は書き換わりません。
• 双方向に使える1つの結合キー — external_idを使って売上データを取り込み、ユーザーごとのアトリビューションを自社のユーザーテーブルに反映できます。
• カーソルによる読み取り — 回答は完了すると表示され、厳密に1回だけ出力されます。出力後は確定済みです。後続の処理でupsertする必要はありません。

プロダクト原則

• AIファーストの入出力：エージェントがフォームを設定して結果を利用し、人間はその間に入ります。
• すべてをAPIに：作成者向けの機能はすべて、認証済みHTTPおよびMCP経由で利用できる必要があります。
• 対象範囲を絞る：質問は1つ、丁寧に尋ねます。主に人間のアンケート運用者向けの機能は、ここには不要である可能性が高いです。
• 根拠のない確信に満ちたパーセンテージを出さない：すべての数値には、計算に使った分母を併記します。誠実に計算できない数値は、平滑化せずnullにします。

クイックスタート

APIキーを取得する

curl -X POST https://www.humansurvey.co/api/auth/code \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]" }'

curl -X POST https://www.humansurvey.co/api/auth/verify \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "code": "481920", "grant": "api_key" }'

匿名でのキー作成は廃止されました。すべてのキーは作成時からアカウントに紐付くため、キーを紛失しても復旧でき、無料でローテーションできます。

フォームを作成してから設定する

curl -X POST https://www.humansurvey.co/api/attribution/forms \
  -H "Authorization: Bearer hs_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Checkout — how did you hear about us",
    "allowed_origins": ["https://app.example.com"]
  }'

{
  "id": "abc123efgh45",
  "form_url": "https://www.humansurvey.co/s/abc123efgh45",
  "warnings": ["this form has no config yet; PUT /api/attribution/forms/abc123efgh45 with {nodes} before embedding it"]
}

フォームは、設定がないと何も表示しません。PUT で不変のスナップショットとして保存します。

curl -X PUT https://www.humansurvey.co/api/attribution/forms/abc123efgh45 \
  -H "Authorization: Bearer hs_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "nodes": [
      {
        "id": "channel",
        "prompt": "Where did you first hear about us?",
        "candidates": [
          { "id": "tiktok", "catalog_slug": "tiktok", "expands": "creator" },
          { "id": "reddit", "catalog_slug": "reddit" },
          { "id": "friend", "label": "A friend or colleague" },
          { "id": "dunno", "label": "I don'\''t remember", "pinned": "end", "dont_remember": true }
        ]
      },
      {
        "id": "creator",
        "prompt": "Which account was it?",
        "candidates": [
          { "id": "oecuid_8812", "label": "Jade", "handle": "@jade.work0" }
        ]
      }
    ]
  }'

プラットフォームのラベル、マーク、別名は GET /api/attribution/catalog から取得され、スナップショットにコピーされます。クリエイター候補はご自身で用意してください。プロダクトは候補セットを表示して、選択された ID を返します。曖昧な説明をクリエイターのデータベースと照合する作業は、上流側で行います。

結果を読み取る

curl "https://www.humansurvey.co/api/attribution/rollup?form_id=abc123efgh45&by=candidate&from=2026-07-01&to=2026-08-01" \
  -H "Authorization: Bearer hs_sk_..."

読み取り側には、GET /api/attribution/forms/{id}/responses（カーソルストリーム、または ?external_id= による単一の ID の取得）、マッピングを待つ自由記述テキストを取得する .../unresolved、および過去にさかのぼって解決する POST .../remaps もあります。リクエストとレスポンスの形式については、OpenAPI ドキュメントをご覧ください。

Claude Code で使う

{
  "mcpServers": {
    "survey": {
      "command": "npx",
      "args": ["-y", "humansurvey-mcp"],
      "env": {
        "HUMANSURVEY_API_KEY": "hs_sk_your_key_here"
      }
    }
  }
}

サーバー名は survey のまま、パッケージ名は humansurvey-mcp のままです。どちらも既存のすべてのユーザーの設定に含まれています。10 個のツールは現在、アトリビューション API を利用します。詳しくは packages/mcp-server/README.md をご覧ください。npm での公開はこのリポジトリとは別に行われるため、npm 上のバージョンはここにあるものより古い場合があります。

公開情報

• ドキュメントページ：https://www.humansurvey.co/docs
• OpenAPI：https://www.humansurvey.co/api/openapi.json
• AI インデックス：https://www.humansurvey.co/llms.txt

技術スタック

コンポーネント	技術
フレームワーク	Next.js（App Router）
データベース	Neon（サーバーレス Postgres）
フロントエンド	React + Tailwind CSS
MCP サーバー	@modelcontextprotocol/sdk
デプロイ	Vercel

プロジェクト構成

├── apps/web/            # Next.js app (API + respondent page + site)
│   ├── lib/attribution/ # config, responses, reads, rollup, remap
│   └── supabase/migrations/  # applied through scripts/migrate.sh, with a ledger
├── packages/mcp-server/ # MCP server for Claude Code
└── docs/                # architecture, roadmap, design docs

コントリビューション

PR を作成する前に CONTRIBUTING.md をお読みください。最も重要なルールは、スコープを厳守することです。新しい UI バリエーション、分析ダッシュボード、人間のオペレーター向け機能は、通常スコープ外です。

開発

pnpm install
pnpm dev               # Start Next.js dev server
pnpm test              # node --test over apps/web/lib/**/*.test.ts
pnpm build             # Build all packages

ライセンス

MIT