Human Survey

HumanSurvey

Website: humansurvey.co · Docs: humansurvey.co/docs · FAQ: humansurvey.co/faq

[human-survey MCP server]

Attribution for the channels that have no referrer.

HumanSurvey asks one question — how did you hear about us — inside the host's own signup or payment flow, at a granularity that is actually actionable: the platform first, then which creator, podcast, event or store.

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

What is this?

An API and MCP server for self-reported attribution. TikTok in-app, Instagram, podcasts, communities, word of mouth, AI assistants: the exposure happens where tracking cannot reach, and asking a human is the only always-on signal that survives every referrer leak.

Two placements answer different questions. In the payment flow, the respondent is already a paying customer, so the answer joins to revenue with no conversion ingest at all. In the signup flow, it is the only way to see the people a channel sends who never pay. Divide a channel's share of the paying population by its share of the signup population. Above 1 it converts better than your average, below 1 worse. Multiply that ratio by your overall signup-to-paid rate to get the channel's own rate.

It is designed for:

• hosts embedding a form in their own onboarding or checkout
• agents that keep the candidate list current and read the results back

It is not designed for:

• general-purpose surveys — arbitrary question types, Markdown authoring and conditional logic were removed in the attribution pivot
• a human-facing analytics dashboard: the aggregates are an API resource, and the agent is the dashboard
• reaching your audience for you — HumanSurvey never contacts respondents; the transports it offers (the /s/{id} URL and the iframe embed) are ones you control

Features

• Progressive disclosure, not pagination — POST the platform answer, PATCH the follow-up. The first answer is durable before the second is asked, and a respondent who abandons the follow-up is still real data.
• Rotation by default — the orderable candidates are permuted per respondent, seeded by a client-minted render_id, so the raw share is unbiased by construction. fixed order exists for callers who want it and does not hide its bias.
• Retroactive remapping — free text is stored verbatim and resolved against the remap table on every read, so one mapping fixes months of history with no backfill.
• Immutable config snapshots — a response is joined to the version it was rendered against, so reconfiguring cannot rewrite what history says was shown.
• One join key, both directions — external_id brings revenue in and carries per-user attribution back out to your own user table.
• Cursor reads — a response becomes visible once it is complete, is emitted exactly once, and is final when emitted. Nothing downstream has to upsert.

Product Principles

• AI-first I/O: agents configure the form and consume the results; humans are in the middle.
• Everything is an API: creator functionality must be available over authenticated HTTP and MCP.
• Narrow scope wins: one question, asked well. A feature that mainly serves a human survey operator probably does not belong here.
• No confident percentages: every number ships beside the denominator it was computed over, and a number we cannot compute honestly is null rather than smoothed.

Quick Start

Get an API key

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" }'

Anonymous key creation is gone. Every key belongs to an account from birth, which is what gives a lost key a recovery path and makes rotation free.

Create a form, then configure it

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"]}

A form renders nothing until it has a config. PUT stores one as an immutable snapshot:

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" }        ]      }    ]  }'

Platform labels, marks and aliases come from GET /api/attribution/catalog and are copied into the snapshot. Creator candidates are yours: the product renders a candidate set and returns the id that was chosen, and matching a vague description against a creator database is upstream work.

Read the results

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_..."

Also on the read side: GET /api/attribution/forms/{id}/responses (cursor stream, or one identity via ?external_id=), .../unresolved for free text awaiting a mapping, and POST .../remaps to resolve it retroactively. Full request and response shapes are in the OpenAPI document.

Use with Claude Code

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

The server name stays survey and the package stays humansurvey-mcp — both sit inside every existing user's config. Its ten tools now speak the attribution API — see packages/mcp-server/README.md. npm publishes separately from this repo, so the version on npm can lag what is here.

Public Surface

• Docs page: https://www.humansurvey.co/docs
• OpenAPI: https://www.humansurvey.co/api/openapi.json
• AI index: https://www.humansurvey.co/llms.txt

Tech Stack

Project Structure

├── 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

Contributing

Read CONTRIBUTING.md before opening a PR. The most important rule is scope discipline: new UI variants, analytics dashboards, and human-operator features are usually out of scope.

Development

pnpm installpnpm dev               # Start Next.js dev serverpnpm test              # node --test over apps/web/lib/**/*.test.tspnpm build             # Build all packages

License

MIT