human-survey

Purpose

HumanSurvey is a feedback collection tool designed specifically for AI agents, with the core purpose of self-reported attribution. It solves the channel attribution problem that traditional tracking cannot cover: when exposure occurs inside the TikTok app, on Instagram, in podcasts, in communities, by word of mouth, or in AI assistants, tracking signals are lost, and asking users directly is the only signal that always works.

Main Capabilities

• Create forms: Store immutable configuration snapshots via PUT requests; forms render nothing before configuration. Platform labels, flags, and aliases come from GET /api/attribution/catalog, and are copied into the snapshot. The candidate creator set is provided by the user.
• Progressive disclosure: First POST the platform answer, then PATCH subsequent follow-ups. The first answer is persisted before the second question is asked, so respondents who abandon midway still contribute valid data.
• Default rotation: Sortable candidates are permuted by respondent, seeded by a client-generated render_id , ensuring raw shares are unbiased. Fixed order is also supported, but its bias is not hidden.
• Retroactive remapping: Free text is stored as-is and parsed on every read according to the remapping table; a single mapping can correct months of history without backfilling.
• Immutable configuration snapshots: Responses are linked to the version at render time; reconfiguration cannot rewrite historical records.
• A single connection key used bidirectionally:external_id can bring in revenue data and attribute each user back to their own user table.
• Cursor reads: Visible after the response is complete, emitted only once, and in final state, so downstream does not need upserts.

Usage

• Create and configure a form: First create the form, then use PUT to store the configuration snapshot.
• Read results: Use GET /api/attribution/forms/{id}/responses(cursor stream, or query a single identity via ?external_id= ),.../unresolved to view free text pending mapping,POST .../remaps for retroactive resolution. See the OpenAPI documentation for the complete request and response structures.
• Working with Claude Code: The server name is survey, and the package name is humansurvey-mcp. Its ten tools now use the attribution API. npm publishing is independent of this repository, and versions may lag.
• Documentation and API:
  • Documentation page:https://www.humansurvey.co/docs
  • OpenAPI：https://www.humansurvey.co/api/openapi.json
  • AI index:https://www.humansurvey.co/llms.txt

Applicable Scenarios

• A host embeds the form in its own registration or payment flow. In the payment flow, the respondent is already a paying customer, and answers can be associated with revenue without conversion ingestion; in the registration flow, you can see the people the channel brought in but who never paid. By calculating a channel's share among paying users divided by its share among registered users, you can determine whether conversion is better or worse (a ratio greater than 1 is better than average, less than 1 is worse than average), then multiply by the overall registration-to-payment conversion rate to get that channel's own conversion rate.
• An agent maintains the candidate list and reads the results.

Limitations

• Not suitable for general surveys: After the attribution pivot, arbitrary question types, Markdown authoring, and conditional logic have been removed.
• No human-facing analytics dashboard: Aggregated results are API resources; the agent is the dashboard.
• Does not reach audiences on your behalf: HumanSurvey never contacts respondents; the provided delivery methods (/s/{id} URL and iframe embedding) are controlled by the user.
• Anonymous key creation has been removed: every key belongs to an account from creation, which provides a key recovery path and makes rotation free.
• Scope discipline: new UI variants, analytics dashboards, and human operator features are generally out of scope.

Product principles

• AI-first I/O: agents configure the form and consume the results, with a human in the middle.
• Everything is an API: creator features must be available through authenticated HTTP and MCP.
• Narrow scope wins: one question, ask it well.
• No confident percentages: every number carries the denominator on which its calculation is based, and numbers that cannot be honestly calculated are null rather than smoothed over.