sunsiyuan/human-survey

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