How to Get Real Human Survey Responses Programmatically (API and MCP)

Many developer tools can create a survey form. Far fewer can put that form in front of real, targeted people and return their answers to your code. That second step, recruiting respondents, is what this guide covers. It explains how to go from a script or an AI agent to completed responses from real humans, using Chorus Research's REST API or MCP server.

Who this guide is for

• Developers who want survey research as a step in a product or data pipeline.
• AI-agent builders whose agent needs to ask real people a question instead of guessing.
• Founders and researchers who want repeatable, scripted studies rather than clicking through a dashboard each time.

Form tools vs. respondent recruitment

Most search results for "survey API" describe form builders. You create questions, share a link, and collect answers from people you already reach yourself. That works when you have an audience.

If you have no audience, you need a recruitment step: someone must find respondents who match your criteria and show them the survey. Chorus combines both steps. You define the survey and the audience, see the price before launch, and pay per survey, with no subscription.

Real respondents vs. synthetic responses

Language models can generate "synthetic respondents" in seconds. These are useful for drafting and testing questions. But they are model outputs, not observations of what real people think or do. If a decision depends on real preferences, such as pricing, messaging or whether a problem exists, collect responses from real people and label synthetic data as synthetic.

How the flow works

1. Connect: connect an MCP client to Chorus, or set up access to the REST API.
2. Create: define the survey questions.
3. Target and estimate: define the target audience and see the price before launching.
4. Launch and pay: you pay when you launch, and fielding starts.
5. Collect: retrieve responses from real respondents.

Who drafts the survey depends on the surface. In the web app and over MCP (the design_survey prompt and the build_audience tool), AI drafts the survey and audience for you to review. Over the REST API, you send the survey JSON yourself to POST /surveys (up to 10 questions).

Step 1: Connect

Chorus offers two MCP options and a REST API. They differ in how you pay, so choose deliberately.

• Hosted remote MCP server (OAuth, no API key):https://mcp.chorusresearch.io/mcp. It never charges.
• Local stdio package (API key): @chorus-research/mcp, run with npx. It uses an in-tool estimate and confirm step that charges your saved payment method.
• REST API: covers surveys, audiences, pricing and responses. See the API documentation for authentication and request formats. Keep credentials in an environment variable, never in client-side code.

Setup for Claude and other MCP clients is in the MCP documentation.

Step 2: Create a survey

Keep the first study small: a few questions, including one screening question and one open-text question. Short surveys are easier to check. Over MCP, describe your goal to your agent, let it draft the survey with design_survey, and review the draft before continuing. Over the REST API, send the survey JSON to POST /surveys.

Step 3: Define the audience and check the price

Define who should answer. Over MCP, build_audience drafts the audience. Then check the price, which Chorus shows before launch. Treat the price as a gate in your code or agent instructions: if it exceeds your budget, stop.

price = get_price(survey)        # see the API or MCP docs for the call
if price > MAX_BUDGET: stop()

Step 4: Launch and pay

Launching commits money and starts fielding. How payment happens depends on the surface:

• Hosted remote MCP server: no tool call moves money. estimate_launch returns a secure browser checkout link, and you pay on the Chorus website.
• Local stdio package and REST API: confirming the estimate launches the survey and charges the saved payment method.

Before any autonomous agent can launch, require human confirmation or a hard budget cap. Agents should never be able to spend without limits.

Step 5: Collect responses

Responses can be exported as structured JSON over MCP or the REST API, ready for your own models and dashboards. Charts and AI-written findings are shown in the app as responses arrive.

Quality checks before you trust the data

• Include one attention-check or consistency question.
• Read the open-text answers yourself. Low-effort or copied text is a warning sign.
• Compare the screener answers to your targeting.
• Record the date the study was fielded, the audience and the sample size next to any conclusion.

Using this from an AI agent responsibly

• Test the survey with synthetic responses first. Launch to real people only after that.
• Require the price to fit a fixed budget, and require approval before launch.
• Keep real and synthetic results in separately labeled datasets.
• Never present generated answers as human responses.

Next steps

Create an account, run one small study, and read the getting-started guide, the API documentation and the MCP documentation.