Public API request examples

These examples use the production API. Replace the sample IDs with IDs returned by your own account. Set your API key once before running the commands:

export API_KEY='ui_sk_your_key'
export STUDY_ID='study_id_from_create_response'
export PARTICIPANT_ID='participant_id_from_create_response'
export INTERVIEW_ID='interview_id_from_list_response'
export REQUEST_ID='request_id_from_feasibility_response'

All requests need Authorization: Bearer $API_KEY. Requests with JSON bodies also need Content-Type: application/json. A 422 response means a field or value failed request validation; the response’s detail identifies it. Path IDs go in the URL, not the JSON body, unless a schema explicitly includes an ID field.

Studies

List studies · `GET /api/public/v1/studies/`

curl -G 'https://api.userintuition.ai/api/public/v1/studies/' \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode 'page=1' \
  --data-urlencode 'page_size=20' \
  --data-urlencode 'name=Pricing'

page starts at 1; page_size can be 1–1000 and defaults to 100. name filters by study name and is optional. Omit the query parameters to list the first page with defaults. The response has studies, total_count, page, and page_size; use a study’s id for later requests. Use get-by-ID to retrieve its full plan and screeners.

Create a study · `POST /api/public/v1/studies/`

This example creates a configured BYOP chat study about a recent appliance purchase. study_plan.objectives and study_plan.conversation_flow are both required when study_plan is present. expected_duration_seconds is a planned maximum in seconds and must be at least 300; 300 means five minutes. The custom screener disqualifies respondents who choose “No.”

curl -X POST 'https://api.userintuition.ai/api/public/v1/studies/' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Recent appliance purchases",
    "study_type": "in-depth-interview",
    "recruiting_method": "byop",
    "interview_format": "chat",
    "voice": "male",
    "language": "en",
    "expected_duration_seconds": 300,
    "study_plan": {
      "objectives": "Understand what triggered one recent blender or microwave purchase, which alternatives were considered, and how price and reliability affected the choice.",
      "conversation_flow": "Ask for the participant’s purchase story. Explore the need that triggered it, the closest alternative, the price-versus-reliability tradeoff, and satisfaction after using the appliance.",
      "background": "Exploratory research into household appliance purchase decisions."
    },
    "screener_questions": [{
      "text": "Have you bought a blender or microwave in the past year?",
      "type": "single_select",
      "options": [
        {"text": "Yes", "disqualify": false},
        {"text": "No", "disqualify": true}
      ]
    }]
  }'

Valid study_type values are in-depth-interview, concept-test, and prototype-test. Valid recruiting_method values are byop and panel; if omitted, the study defaults to BYOP. Valid interview_format values are chat, video, and voice; prototype tests cannot use chat. voice is male (Elliot) or female (Clara). Use a supported two-letter language code such as en, or auto. The name has a 40-character limit. screener_questions can also use multi_select or text_input; multi-select options must each set selection_rule to must_select, may_select, or reject. Save the returned id as STUDY_ID. Check provisioning_status: draft means missing_requirements lists what to add; ready means configured but not yet provisioned; provisioned means interviews can run. study_link is the participant interview URL when available, and dashboard_url is the management URL. Creation does not accept byop_config; set BYOP incentives with PATCH after creation.

Create a study and invite participants · `POST /api/public/v1/studies/create-with-participants`

Pass a complete BYOP study plus 1–100 participants. Emails must be unique, ignoring case. silent: true creates an invitation without sending its invitation email. This endpoint requires the new study to be provisioned before invitations are created; if it cannot be provisioned or an invitation fails, the new study is rolled back.

curl -X POST 'https://api.userintuition.ai/api/public/v1/studies/create-with-participants' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "study": {
      "name": "AI research tool shortlist",
      "study_type": "in-depth-interview",
      "recruiting_method": "byop",
      "interview_format": "voice",
      "voice": "male",
      "language": "en",
      "expected_duration_seconds": 1080,
      "study_plan": {
        "objectives": "Understand what makes startup CEOs shortlist an AI research tool and what proof they need before considering one seriously.",
        "conversation_flow": "Ask about a recent customer-research decision, the trigger to look for an AI tool, alternatives considered, trust concerns, and proof needed to shortlist a provider."
      }
    },
    "participants": [
      {"email": "alex@example.com"},
      {"email": "sam@example.com", "silent": true}
    ]
  }'

The response contains study and participants. Use study.id for study operations and each participants[].id for participant operations. Neither study.byop_config nor a top-level byop_config is accepted.

Get a study · `GET /api/public/v1/studies/{study_id}`

curl "https://api.userintuition.ai/api/public/v1/studies/$STUDY_ID" \
  -H "Authorization: Bearer $API_KEY"

Use the full response to inspect study_plan, screener_questions, targeting_attributes, provisioning_status, missing_requirements, and the participant study_link.

Customize the study plan · `POST /api/public/v1/studies/{study_id}/customize-plan`

Send one user turn at a time. The server stores the conversation ID on the study; the next call only needs a new message. Relay a returned response_type: "question" to the person designing the study and pass their answer in the next request. A response_type: "study_plan" means the generated plan was saved.

curl -X POST "https://api.userintuition.ai/api/public/v1/studies/$STUDY_ID/customize-plan" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "We want to understand how households choose a blender or microwave. Ask about one recent purchase, what triggered it, the closest alternative, and how they weighed price against reliability."
  }'

message must be 1–20,000 characters. To attach a concept image to the same turn, add concept_image with data_base64 (base64 image bytes, not a data URL), filename, content_type (image/png, image/jpeg, image/gif, or image/webp), and a participant-facing label. The decoded file must be at most 10 MB. For example, the optional object is {"data_base64":"<base64 bytes>","filename":"checkout.png","content_type":"image/png","label":"Checkout screen"}.

Change only selected study fields · `PATCH /api/public/v1/studies/{study_id}`

Use PATCH for a partial change. This example turns on a

25 BYOP incentive and automatic rewards. `byop_config` is accepted on update, but not on creation; `incentive_amount` must be

5–$500. Only provided fields change.

curl -X PATCH "https://api.userintuition.ai/api/public/v1/studies/$STUDY_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "byop_config": {
      "incentive_amount": 25,
      "is_incentives_enabled": true,
      "auto_send_incentives": true
    }
  }'

For a draft missing interviewer settings, a PATCH such as {"voice":"female","language":"en"} supplies those fields without clearing its existing plan. For a fielding Panel study, first pause or stop it; an edit otherwise returns 409 with the allowed actions.

Replace a study · `PUT /api/public/v1/studies/{study_id}`

PUT describes the full desired state; fields you omit are cleared. Fetch the study first, then send every field you want to retain. In particular, include study_plan, screeners, and panel targeting attributes if they should stay. This example replaces a simple BYOP study without screeners or incentives.

curl -X PUT "https://api.userintuition.ai/api/public/v1/studies/$STUDY_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Updated buyer interviews",
    "study_type": "in-depth-interview",
    "recruiting_method": "byop",
    "interview_format": "voice",
    "voice": "female",
    "language": "en",
    "expected_duration_seconds": 1200,
    "study_plan": {
      "objectives": "Understand subscription buying decisions.",
      "conversation_flow": "Discuss the most recent decision, alternatives, and acceptable prices."
    },
    "screener_questions": []
  }'

Delete, pause, resume, or stop a study

These operations use the path ID and an authorization header; they take no JSON body.

curl -X POST "https://api.userintuition.ai/api/public/v1/studies/$STUDY_ID/pause" -H "Authorization: Bearer $API_KEY"
curl -X POST "https://api.userintuition.ai/api/public/v1/studies/$STUDY_ID/resume" -H "Authorization: Bearer $API_KEY"
curl -X POST "https://api.userintuition.ai/api/public/v1/studies/$STUDY_ID/stop" -H "Authorization: Bearer $API_KEY"
curl -X DELETE "https://api.userintuition.ai/api/public/v1/studies/$STUDY_ID" -H "Authorization: Bearer $API_KEY"

pause temporarily blocks new responses and preserves an existing panel; resume continues it. stop ends recruitment and settles the panel hold. DELETE deletes the study. Run only the operation you intend; the four commands above are alternatives, not a sequence.

Panels, targeting, and feasibility

Find panel qualifications · `GET /api/public/v1/targeting-attributes/`

curl -G 'https://api.userintuition.ai/api/public/v1/targeting-attributes/' \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode 'name=Gender'

name is an optional case-insensitive search. category is an optional case-insensitive exact category filter; omit both to list the catalog. Use returned qualification_id and options[].option_id values in study targeting_attributes and panel option_targets. Do not invent these IDs.

Find supported countries · `GET /api/public/v1/panel-countries/`

curl -G 'https://api.userintuition.ai/api/public/v1/panel-countries/' \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode 'language=EN'

Pass either language=EN to list countries supporting that language or country=US to inspect one country’s language_options; passing both returns 400. Omit both to list all. Panel requests require a supported country_code, and the country must support the study’s interview language.

Estimate or launch a panel for an existing study · `POST /api/public/v1/studies/{study_id}/launch-panel`

First create or update a Panel study (recruiting_method: "panel"). This request reserves 8 of 20 completed interviews for option ID 1 of qualification ID 2; the remaining 12 remain open to other eligible options. Replace the catalog IDs with IDs returned by the targeting endpoint and configure qualification 2 on the study before launch.

curl -X POST "https://api.userintuition.ai/api/public/v1/studies/$STUDY_ID/launch-panel" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "target": 20,
    "incident_rate": 25,
    "country_code": "US",
    "frequency": "one-time",
    "dry_run": true,
    "targeting_attributes": [{
      "qualification_id": 2,
      "option_targets": [{"option_id": 1, "target": 8}]
    }]
  }'

target is a positive whole number of completed interviews. incident_rate is a percentage from 0–100; 25 means 25%, not 0.25. Rates below 10% need a feasibility request before direct panel launch. frequency is one-time, weekly, monthly, or quarterly. dry_run: true returns a cost and timeline estimate without fielding; review estimated_total_cost_usd and estimated_timeline_hours. Set dry_run: false only when ready to field a provisioned study and pay for the panel. targeting_attributes is optional; omit it for an untargeted panel.

Create a study and estimate or launch its panel · `POST /api/public/v1/studies/create-and-launch-panel`

This is a single request with separate study and panel objects. For a dry run, it estimates without creating a study. For a real launch, the study must contain enough settings to provision its interviewer; the example supplies name, plan, voice, and language. This example targets the C-level/owner option for the job-title qualification; verify its IDs in the targeting catalog before sending the request. The backend forces Panel recruitment regardless of the optional study.recruiting_method.

curl -X POST 'https://api.userintuition.ai/api/public/v1/studies/create-and-launch-panel' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "study": {
      "name": "Startup CEO AI tool shortlist",
      "study_type": "in-depth-interview",
      "recruiting_method": "panel",
      "interview_format": "voice",
      "voice": "male",
      "language": "en",
      "expected_duration_seconds": 1200,
      "study_plan": {
        "objectives": "Understand what triggers startup CEOs to evaluate AI-powered research tools, how they build a shortlist, and what proof makes a provider credible.",
        "conversation_flow": "Discuss the last important customer-research decision, how the CEO gathered input, why they considered an AI tool, alternatives they compared, trust thresholds, and evidence needed to shortlist one."
      },
      "targeting_attributes": [{
        "qualification_id": 89,
        "allowed_options": [1],
        "disallowed_options": []
      }],
      "screener_questions": [{
        "text": "Are you the founder or CEO of a startup?",
        "type": "single_select",
        "options": [
          {"text": "Yes", "disqualify": false},
          {"text": "No", "disqualify": true}
        ]
      }]
    },
    "panel": {
      "target": 20,
      "incident_rate": 25,
      "country_code": "US",
      "dry_run": true
    }
  }'

The dry-run response has study: null and an estimated panel. To create and field, change panel.dry_run to false; the response includes the new study and panel status. study.byop_config is not accepted here. In this example, qualification 89 is job title and option 1 is the C-level/owner answer; the custom screener narrows that broader qualification to founders and CEOs. Panel option quotas, if needed, go in panel.targeting_attributes as shown above; quotas require at least two eligible options for that qualification.

Submit a low-incidence or niche audience · `POST /api/public/v1/feasibility-requests/`

curl -X POST 'https://api.userintuition.ai/api/public/v1/feasibility-requests/' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "target_audience": "US startup CEOs who have evaluated AI tools for customer research in the past six months",
    "country_code": ["US"],
    "target": 20,
    "incident_rate": 8.5
  }'

target_audience is a nonblank description. country_code is an optional array of supported two-letter codes; omit it for no country restriction. target must be positive. incident_rate is percentage points, so 8.5 means 8.5%. Add study_id only if you already have a study and want to attach this request to it. The response’s id is the feasibility request ID, and status starts at RECEIVED.

List or get feasibility requests

curl 'https://api.userintuition.ai/api/public/v1/feasibility-requests/' -H "Authorization: Bearer $API_KEY"
curl "https://api.userintuition.ai/api/public/v1/feasibility-requests/$REQUEST_ID" -H "Authorization: Bearer $API_KEY"

The list is an array of your account’s requests, newest first. The get request takes the id returned by submit or list and returns its current status (RECEIVED or RESPONDED) and any available estimate. Neither GET takes a JSON body.

Participants

List participants · `GET /api/public/v1/participants/`

curl -G 'https://api.userintuition.ai/api/public/v1/participants/' \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode 'study_id=study_id_from_create_response' \
  --data-urlencode 'page=1' \
  --data-urlencode 'page_size=20'

Replace study_id_from_create_response with the actual study ID. study_id and email are optional filters. page starts at 1; page_size can be 1–100 and defaults to 10. The response has participants, total_count, page, and page_size. These are your own invited participants; Panel respondents are not synthesized into participant records.

Invite participants · `POST /api/public/v1/participants/`

Use a provisioned BYOP study. Send 1–100 distinct emails. silent: true creates the participant without sending an invitation email. The response is an array of created participants; keep each id for get, update, or reward operations.

curl -X POST 'https://api.userintuition.ai/api/public/v1/participants/' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "study_id": "study_id_from_create_response",
    "participants": [
      {"email": "alex@example.com", "silent": false},
      {"email": "sam@example.com", "silent": true}
    ]
  }'

Get or change a participant

curl "https://api.userintuition.ai/api/public/v1/participants/$PARTICIPANT_ID" \
  -H "Authorization: Bearer $API_KEY"

curl -X PUT "https://api.userintuition.ai/api/public/v1/participants/$PARTICIPANT_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"email":"alex.new@example.com"}'

The GET has no body. The PUT accepts email as its only JSON field; the participant ID comes from the URL. The response shows the current email, invitation timestamps, and reward state.

Send a BYOP reward · `POST /api/public/v1/participants/{participant_id}/reward`

curl -X POST "https://api.userintuition.ai/api/public/v1/participants/$PARTICIPANT_ID/reward" \
  -H "Authorization: Bearer $API_KEY"

This operation takes no JSON body. It sends the study’s configured incentive to this BYOP participant and returns 202 Accepted when queued. Set the incentive with study PATCH first; check reward_sent and reward_sent_at on the participant response. This is a payment action, so select the intended participant ID carefully.

Interviews and reports

List interviews · `GET /api/public/v1/interviews/`

curl -G 'https://api.userintuition.ai/api/public/v1/interviews/' \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode 'study_id=study_id_from_create_response' \
  --data-urlencode 'status=completed' \
  --data-urlencode 'quality=Good' \
  --data-urlencode 'quality=Excellent' \
  --data-urlencode 'page=1' \
  --data-urlencode 'page_size=20'

Replace the study ID. study_id, status, and quality are optional filters; repeat quality for more than one label. Quality labels are Excellent, Good, Fair, and Poor. page starts at 1; page_size can be 1–100 and defaults to 10. The response has interviews, total_count, page, and page_size; use an interview’s id for get or delete.

Get or delete an interview

curl "https://api.userintuition.ai/api/public/v1/interviews/$INTERVIEW_ID" \
  -H "Authorization: Bearer $API_KEY"

curl -X DELETE "https://api.userintuition.ai/api/public/v1/interviews/$INTERVIEW_ID" \
  -H "Authorization: Bearer $API_KEY"

GET returns the full public interview, including available messages, quality, recording URLs, and screener responses. DELETE soft-deletes it and returns 204 No Content. Both use the path ID and take no JSON body; run DELETE only if you intend to remove that interview.

Generate or fetch a study report

curl -X POST "https://api.userintuition.ai/api/public/v1/studies/$STUDY_ID/report" \
  -H "Authorization: Bearer $API_KEY"

curl "https://api.userintuition.ai/api/public/v1/studies/$STUDY_ID/report" \
  -H "Authorization: Bearer $API_KEY"

POST generates a report from the study’s interviews; GET retrieves the saved report. Both use the study ID in the URL and take no JSON body. The report response includes its available report content and references; generate after interviews have completed.

Webhooks

Register · `POST /api/public/v1/webhooks/`

curl -X POST 'https://api.userintuition.ai/api/public/v1/webhooks/' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"hook_url":"https://your-company.example/webhooks/user-intuition"}'

hook_url is the HTTPS endpoint on your server that will receive completed-interview POSTs. It is account-wide; do not pass study_id. The response includes signing_secret, shown once. Store it and verify X-UI-Signature against the raw request body as described in Webhooks. Respond with 2xx quickly; failed deliveries are not retried.

Unregister · `DELETE /api/public/v1/webhooks/`

curl -X DELETE 'https://api.userintuition.ai/api/public/v1/webhooks/' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"hook_url":"https://your-company.example/webhooks/user-intuition"}'

Pass the same hook_url used for registration. This DELETE is one of the operations that does take a JSON body; it does not use a webhook ID in the URL.

Overview

Studies

Interviews

Participants

Reports

Targeting

Panels

Feasibility

Study Management

Webhooks

Public API request examples

Studies

List studies · `GET /api/public/v1/studies/`

Create a study · `POST /api/public/v1/studies/`

Create a study and invite participants · `POST /api/public/v1/studies/create-with-participants`

Get a study · `GET /api/public/v1/studies/{study_id}`

Customize the study plan · `POST /api/public/v1/studies/{study_id}/customize-plan`

Change only selected study fields · `PATCH /api/public/v1/studies/{study_id}`

Replace a study · `PUT /api/public/v1/studies/{study_id}`

Delete, pause, resume, or stop a study

Panels, targeting, and feasibility

Find panel qualifications · `GET /api/public/v1/targeting-attributes/`

Find supported countries · `GET /api/public/v1/panel-countries/`

Estimate or launch a panel for an existing study · `POST /api/public/v1/studies/{study_id}/launch-panel`

Create a study and estimate or launch its panel · `POST /api/public/v1/studies/create-and-launch-panel`

Submit a low-incidence or niche audience · `POST /api/public/v1/feasibility-requests/`

List or get feasibility requests

Participants

List participants · `GET /api/public/v1/participants/`

Invite participants · `POST /api/public/v1/participants/`

Get or change a participant

Send a BYOP reward · `POST /api/public/v1/participants/{participant_id}/reward`

Interviews and reports

List interviews · `GET /api/public/v1/interviews/`

Get or delete an interview

Generate or fetch a study report

Webhooks

Register · `POST /api/public/v1/webhooks/`

Unregister · `DELETE /api/public/v1/webhooks/`

​Studies

​List studies · GET /api/public/v1/studies/

​Create a study · POST /api/public/v1/studies/

​Create a study and invite participants · POST /api/public/v1/studies/create-with-participants

​Get a study · GET /api/public/v1/studies/{study_id}

​Customize the study plan · POST /api/public/v1/studies/{study_id}/customize-plan

​Change only selected study fields · PATCH /api/public/v1/studies/{study_id}

​Replace a study · PUT /api/public/v1/studies/{study_id}

​Delete, pause, resume, or stop a study

​Panels, targeting, and feasibility

​Find panel qualifications · GET /api/public/v1/targeting-attributes/

​Find supported countries · GET /api/public/v1/panel-countries/

​Estimate or launch a panel for an existing study · POST /api/public/v1/studies/{study_id}/launch-panel

​Create a study and estimate or launch its panel · POST /api/public/v1/studies/create-and-launch-panel

​Submit a low-incidence or niche audience · POST /api/public/v1/feasibility-requests/

​List or get feasibility requests

​Participants

​List participants · GET /api/public/v1/participants/

​Invite participants · POST /api/public/v1/participants/

​Get or change a participant

​Send a BYOP reward · POST /api/public/v1/participants/{participant_id}/reward

​Interviews and reports

​List interviews · GET /api/public/v1/interviews/

​Get or delete an interview

​Generate or fetch a study report

​Webhooks

​Register · POST /api/public/v1/webhooks/

​Unregister · DELETE /api/public/v1/webhooks/

Studies

List studies · `GET /api/public/v1/studies/`

Create a study · `POST /api/public/v1/studies/`

Create a study and invite participants · `POST /api/public/v1/studies/create-with-participants`

Get a study · `GET /api/public/v1/studies/{study_id}`

Customize the study plan · `POST /api/public/v1/studies/{study_id}/customize-plan`

Change only selected study fields · `PATCH /api/public/v1/studies/{study_id}`

Replace a study · `PUT /api/public/v1/studies/{study_id}`

Delete, pause, resume, or stop a study

Panels, targeting, and feasibility

Find panel qualifications · `GET /api/public/v1/targeting-attributes/`

Find supported countries · `GET /api/public/v1/panel-countries/`

Estimate or launch a panel for an existing study · `POST /api/public/v1/studies/{study_id}/launch-panel`

Create a study and estimate or launch its panel · `POST /api/public/v1/studies/create-and-launch-panel`

Submit a low-incidence or niche audience · `POST /api/public/v1/feasibility-requests/`

List or get feasibility requests

Participants

List participants · `GET /api/public/v1/participants/`

Invite participants · `POST /api/public/v1/participants/`

Get or change a participant

Send a BYOP reward · `POST /api/public/v1/participants/{participant_id}/reward`

Interviews and reports

List interviews · `GET /api/public/v1/interviews/`

Get or delete an interview

Generate or fetch a study report

Webhooks

Register · `POST /api/public/v1/webhooks/`

Unregister · `DELETE /api/public/v1/webhooks/`