An interview API for AI agents lets software ask real people why, not only what. The agent or service sends a brief, the platform recruits participants and moderates the interviews, and the code reads back findings tied to the quotes behind them.
This is the developer integration guide. It covers the integration patterns, then walks one study through every request and response: create, attach images, plan, estimate, launch, webhooks, report and the research library. For the brand team’s side, where an agent runs claim tests and brand-switching studies in conversation, read the consumer research API guide. Field names come from the published OpenAPI specification, and IDs and URLs in the snippets are examples marked EXAMPLE.
What does an interview API do, versus a survey API?
A survey API delivers questionnaires: structured prompts with fixed-choice or short-text responses. Survey APIs are fast, cheap per response, and statistically tractable at large n. They are the right tool when you need to measure what share of shoppers would buy a new size, how satisfaction tracks over time, or whether a respondent belongs to a segment.
An interview API launches AI-moderated conversations that probe, follow up on unexpected answers, and surface the reasoning behind behavior. The output is not a distribution of choices. It is a body of explained positions, each tied to the people who gave it.
For AI agents, the gap is simple: a survey API cannot probe. When a respondent says “I prefer pack B,” a survey records that. A moderated interview follows up: “What about pack A didn’t land?” “What would pack B need to do to make you switch from your usual brand?” The reasoning is what changes decisions. Both belong in a complete research stack; they are not substitutes.
What does a developer integrate?
An interview API reduces to a short contract. The study is the unit of work, and every later call hangs off its ID. The saved plan is the artifact a person approves, and its learning goal IDs reappear in the report. The estimate is the price, returned with an estimate_id and an expiry, and a launch that names that ID runs at the price the approver saw. Webhooks are the clock: signed deliveries announce completed interviews and ready reports, and a stable event ID makes them safe to deduplicate. The report is the payload: findings with prevalence as n of N, quotes that resolve through a references array to the interview and its recording, and a coverage judgment for each learning goal. Fielding progress and the research library are reads against the same IDs, so a study an agent starts in Claude can be monitored by a backend service without a second integration.
Which integration patterns do agents use?
| Pattern | Where it runs | What it does | Best for |
|---|---|---|---|
| REST API | Backend services, scripts, CI | The full lifecycle, with launch against a saved estimate | Studies inside your own workflow or product |
| MCP server | Claude, ChatGPT, Claude Code, Codex, Cursor | The full lifecycle as tool calls, with a person approving the plan and estimate | An agent running research in conversation |
| CLI | A terminal or a scheduled script | Estimates, fielding inspection and results | Monitoring, reporting and scripted reads |
Paid panels launch from an MCP client or the REST launch-panel endpoint. In an MCP client, the agent shows you the saved plan and a cost estimate before anything is spent; in Claude you approve with one click, elsewhere you confirm in the conversation. Over the API, your code launches against a saved estimate.
The MCP research API reference covers what each tool does, and MCP vs REST API for customer research covers when to pick each interface.
Worked integration: a pack test over REST, end to end
The scenario: a brand has two front-of-pack designs for an oat milk line and wants to know which one shoppers read correctly at a glance, and why. A service runs the study for the brand manager. Every request goes to https://api.userintuition.ai with an API key in the Authorization: Bearer header.
Step 1: Create the study
The service creates a draft. Only name and recruiting_method are required.
POST /api/public/v1/studies/
Authorization: Bearer $USERINTUITION_API_KEY
Content-Type: application/json
{
"name": "Oat milk front-of-pack test",
"study_type": "concept-test",
"recruiting_method": "panel",
"interview_format": "voice"
}
The 201 response returns the study with its ID and status fields, abridged here:
{
"id": "study_EXAMPLE_01",
"study_type": "concept-test",
"recruiting_method": "panel",
"interview_format": "voice",
"provisioning_status": "draft",
"fielding_status": "not_started"
}
Step 2: Customize the brief with the pack image
Attach each design with a label participants and the report can refer to. From a hosted file:
POST /api/public/v1/studies/study_EXAMPLE_01/concept-images/from-url
{ "url": "https://assets.example.com/oat-pack-a.png", "label": "Design A" }
{ "id": "img_EXAMPLE_A", "url": "https://assets.example.com/oat-pack-a.png", "label": "Design A" }
A local file goes to the concept-images endpoint as multipart form data, up to 10 MB. Then the service sends the brief to the planning agent, the same planning step the dashboard uses:
POST /api/public/v1/studies/study_EXAMPLE_01/customize-plan
{
"message": "Compare Design A and Design B for our oat milk line. Learn what shoppers notice first, what they think the product is, whether 'barista' reads as a benefit, and which design they would pick up and why.",
"decisions": "human"
}
With decisions set to human, the planner returns questions for the person to answer instead of guessing:
{
"response_type": "question",
"message": "A few choices before I write the plan.",
"questions": [
{ "id": "q_EXAMPLE_1", "text": "Who should we recruit?", "options": ["Current oat milk buyers", "All plant-milk buyers"] }
],
"study": { "id": "study_EXAMPLE_01", "provisioning_status": "draft" }
}
The service relays the questions, sends the answers on the next turn, and the planner replies with response_type: "study_plan" once the plan is written. Set decisions to agent only when the person has delegated design choices; the response then lists the assumptions it made. A single image can also travel inside this call as a base64 concept_image.
Step 3: Review the saved plan
GET /api/public/v1/studies/study_EXAMPLE_01
The study now carries the persisted plan and both images:
{
"id": "study_EXAMPLE_01",
"provisioning_status": "provisioned",
"study_plan": {
"objectives": "Identify which front-of-pack design shoppers read correctly ...",
"conversation_flow": "1. Warm-up on how they shop the dairy aisle ...",
"learning_goals_structured": [
{ "id": "lg_EXAMPLE_1", "question": "What do shoppers notice first on each design?" }
]
},
"concept_images": [
{ "id": "img_EXAMPLE_A", "url": "https://assets.example.com/oat-pack-a.png", "label": "Design A" },
{ "id": "img_EXAMPLE_B", "url": "https://assets.example.com/oat-pack-b.png", "label": "Design B" }
]
}
This is the artifact a human approves. The learning goal IDs matter later: they match the learning_goal_id values in the report, so the service can map every finding back to the question it answers. A provisioning_status of provisioned means the interviewer is ready for fieldwork. Concepts appear to participants in upload order, and the moderator decides when to surface each one.
Step 4: Estimate the panel
POST /api/public/v1/studies/study_EXAMPLE_01/estimate-panel
{ "target": 30, "incident_rate": 40, "country_code": "US", "frequency": "one-time" }
incident_rate is the share of panelists expected to qualify, in percentage points. The response is read-only:
{
"study_id": "study_EXAMPLE_01",
"target": 30,
"country_code": "US",
"sufficient_credits": true,
"estimate_id": "est_EXAMPLE_01",
"expires_at": "2026-10-28T15:00:00Z"
}
The same response carries estimated_total_cost_usd, estimated_total_cost_per_interview_usd, card_hold_usd, available_credit_balance and estimated_timeline_hours, which is everything a budget owner needs to approve. A 30-interview panel study is $1,800, recruiting included.
Step 5: Launch against the estimate
Over the API, your code launches against the saved estimate, so the price the approver saw is the price that applies. Send the same body with the estimate_id and dry_run set to false:
POST /api/public/v1/studies/study_EXAMPLE_01/launch-panel
{ "target": 30, "incident_rate": 40, "country_code": "US", "frequency": "one-time", "estimate_id": "est_EXAMPLE_01", "dry_run": false }
Send an Idempotency-Key header with the launch and reuse the same key if you retry after an uncertain response, so a retried request does not launch a second panel. In a backend, store the estimate with the study ID, route it to the budget owner, and launch on their approval, which leaves an audit trail of who approved which plan.
Step 6: Listen for webhooks
Register one signed webhook per study, or one for the account:
POST /api/public/v1/webhooks/
{ "hook_url": "https://research-bot.example.com/ui-events", "study_id": "study_EXAMPLE_01", "event_types": ["interview.completed", "report.ready"] }
The signing_secret appears only in this creation response, so store it then. Deliveries look like this:
{ "id": "evt_EXAMPLE_01", "type": "report.ready", "study_id": "study_EXAMPLE_01", "data": { "report_id": "rpt_EXAMPLE_01" } }
Verify X-UI-Signature against the raw body and X-UI-Timestamp, return any 2xx, and deduplicate on the event id. Between events, GET /api/public/v1/studies/study_EXAMPLE_01/fielding-progress returns completed interviews against target, the quality mix and an expected finish time. Other events cover screening, quality scoring, quotas and pause or stop.
Step 7: Generate and read the report
POST /api/public/v1/studies/study_EXAMPLE_01/report queues analysis and returns a job to poll; report.ready fires when it finishes. Then read the findings:
GET /api/public/v1/studies/study_EXAMPLE_01/report?view=study_findings
The response groups findings under study_findings.learning_goals, keyed by the learning_goal_id values from the saved plan. To show a real finding rather than invented pack-test results, the snippet below is example output from a User Intuition study of 43 Walmart shoppers, each reconstructing one recent trip in a voice interview, abridged to one finding:
{
"study_id": "study_EXAMPLE_02",
"interview_count": 43,
"study_findings": {
"learning_goals": [
{
"learning_goal_id": "lg_EXAMPLE_1",
"findings": [
{
"finding_id": "f_EXAMPLE_1",
"heading": "The shelf shaped the trip",
"content": "19 of 43 shoppers named the shelf as the moment that shaped the trip, and the shelf carried 20 of 51 friction moments.",
"prevalence": { "n": 19, "of": 43 },
"quotes": [
{
"text": "We couldn't find the Roku at first. We thought we were gonna have to ask somebody, but then we found where the device were located.",
"reference_id": "ref_EXAMPLE_4",
"interview_id": "int_EXAMPLE_12"
}
]
}
]
}
]
}
}
Each learning goal also carries its learning_goal text, and each finding can carry supporting_evidence, contrary_evidence and limitations. Each reference_id resolves through the report’s references array to the interview, the audio or video recording URL and, when stored timing exists, the start time of the quoted moment. Other views return participant_profiles, participant_responses, evidence_coverage and recommended_next_steps, or full for everything at once.
Three habits keep a service’s summaries trustworthy:
- Quote, don’t paraphrase. Pull the
quotesarray into the summary with its reference link, so a reader can open the interview and hear the participant. - Carry the contrary evidence.
contrary_evidenceandlimitationson each finding say who disagreed, and a decision should know that before it ships. - Check coverage before concluding.
evidence_coverageevaluates each learning goal and returnssample_adequacy, with anadditional_interviewsjudgment of recommended, conditional or not prioritized, plus a list ofevidence_gaps. If a gap touches the decision, scope a follow-up fromrecommended_next_stepsinstead of overstating the result.
For each finding your service keeps, store the study ID, finding ID, prevalence, quote and reference. A brief can then cite a consumer finding the way an engineering spec cites a ticket.
Step 8: Ask the research library before the next study
Before commissioning new fieldwork, the service can ask what earlier studies already found:
POST /api/public/v1/research/answer/
{ "question": "What shaped the trip for these shoppers?", "filters": { "study_ids": ["study_EXAMPLE_02"] } }
The answer comes back with numbered citations to the source findings and an insufficient_evidence flag, which is the service’s signal to propose a new study rather than stretch an old one. A citation to a participant response carries its interview_id, and GET /api/public/v1/interviews/{interview_id} returns that interview with its transcript messages. How cited answers work across a whole library is covered in ask questions across past research.
How does recruiting work through the API?
The human picks the audience when the study is created. Set recruiting_method to panel to recruit from User Intuition’s vetted 4M+ consumer panel, or to byop to invite your own participants by email or study link. B2B audiences, such as IT buyers or clinicians, are recruited to order per study.
For panel studies, targeting_attributes takes qualification_id values from the catalog at GET /api/public/v1/targeting-attributes/, such as age, region or category purchase, and screener_questions adds study-specific screening. The country goes in country_code on the estimate and the launch. Most panel studies fill within 24 hours, and the estimate shows the expected timeline for your audience and country before you approve.
Synthetic respondents are also available for a directional first read, in chat, before a real study fields. For the recruitment half on its own, including how marketplace APIs differ, see the participant recruitment API guide.
How do voice AI APIs compare with research-specific APIs?
Voice AI platforms such as ElevenLabs provide real-time voice synthesis and conversation infrastructure. They are the right choice when the product is the conversation: support agents, voice assistants, and interactive voice response. Their API surface is built for real-time call handling, with low-latency audio, call routing, and transcript capture.
A research-specific API serves a different goal. The conversation is a means to an end, and the end is structured qualitative evidence.
| Dimension | Voice AI API | Research API |
|---|---|---|
| Participant supply | You bring your own | Vetted 4M+ consumer panel or your own participants |
| Conversation design | Real-time, open-ended | Moderated research methodology |
| Output format | Raw transcript | Findings, prevalence, and verbatim quotes |
| Recruitment | Not included | Screener, invitation, and rewards via API |
| Knowledge layer | None | Research library with cited answers |
| Primary use case | The product is the conversation | Research produces evidence |
For agents that only need to talk with people the product already serves, a voice AI API can be enough. For agents that need to recruit qualified participants, run research-methodology conversations, and return evidence they can analyze, the research-specific API is the right layer. Some architectures use both: a voice AI layer for real-time support and a research API for periodic research programs.
How does User Intuition handle agent-driven interviews?
User Intuition’s AI moderator runs 20–30 minute interviews that ladder 5–7 levels deep, moving from what a participant did to why it mattered, in voice, chat or video and in 80+ languages. Concept tests use an image; prototype tests use a live link in voice or video. Reports return findings grouped by learning goal with prevalence counts, verbatim quotes, participant profiles, evidence coverage and recommended next steps.
Trust is part of the payload a service stores. Every panelist call is reviewed by the User Intuition team, panelists pass a video identity check, and only interviews that pass quality scoring are billed; see how quality works. Participants rate the experience at 98% satisfaction, and the platform holds 4.9/5 on G2 and 5/5 on Capterra.
The research API and MCP server for AI agents covers the product for teams that run research from an agent. Teams embedding studies inside their own product should start with the qualitative research API. The MCP reference covers tool schemas, the API reference covers REST, and the examples repository has runnable code.
How do you connect an agent or a service?
For a service, create an API key and call https://api.userintuition.ai as shown in the worked integration above. For an agent, connect it in Claude, ChatGPT, Codex or Cursor in a few minutes (setup). For scripts and scheduled reads, the CLI docs cover installing @userintuition-ai/mcp, and the CLI estimates, inspects fielding and reads results.
Every path starts from the same account. Signup includes 3 free interviews with your own participants; panel recruiting is billed separately. Create a free account to get an API key.