Human Survey

HumanSurvey

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

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

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": "you@example.com" }'

curl -X POST https://www.humansurvey.co/api/auth/verify \ -H "Content-Type: application/json" \ -d '{ "email": "you@example.com", "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 install

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

License

MIT