Skip to main content

Bring Your Own Panel

This is a provider integration for a BYOP study, distinct from adding individual participants with create_participants. The external provider sends respondents through an entry URL with its respondent ID. User Intuition records each session and redirects the respondent to the provider’s completion or screen-out URL when the interview ends. It does not launch or charge for User Intuition’s paid panel. Create and customize a study with recruiting_method: "byop", then use get_study to confirm it is provisioned and review the current plan. configure_external_panel requires absolute HTTP(S) completion and screen-out redirect URLs. You can also set the provider’s respondent ID query parameter and placeholder, session and external study ID mappings, and quota-full or technical-failure redirects. The response includes entry_url; have the human verify the plan, parameter mapping, and redirects before giving that link to the provider. Changing the configuration with the same PUT keeps the entry token. Token regeneration changes the URL, so the provider must receive the replacement link before the old one is used again. Use a fresh idempotency_key for each regeneration and reuse it if its result is uncertain. For the same operations over REST, see External panels.

Before a panel launch

  1. Call get_study and confirm recruiting_method is panel.
  2. Return the complete persisted plan, audience, and screeners from get_study; obtain explicit approval of that exact version.
  3. Ask the user to choose the launch country explicitly. One launch_panel call fields exactly one country; it cannot field a region or a list of countries.
  4. Read userintuition://catalog/panel-countries and verify that the country supports the study’s language. If your client cannot read MCP resources, use the authenticated GET /api/public/v1/panel-countries/ endpoint.
  5. Call estimate_panel with that country_code; show the resolved country, language, cost, and heuristic timeline.
  6. Call launch_panel with the returned estimate_id and the same country to review the saved plan and current estimate. This first call does not spend. In clients advertising MCP Apps support, the human approves with the App button. In other clients, show the complete saved plan as Markdown and the estimate as readable amounts, ask for explicit human confirmation, then call launch_panel again with the same inputs, returned chat_approval_nonce and human_confirmed: true.
  7. The review is short-lived and single-use, bound to the credential, organization, study version and estimate. Changed inputs, an expired quote or a changed saved plan require fresh review and human confirmation. After an uncertain response, read get_study before any further action; do not automatically create a new approval to retry. Client tool permissions and approval of an earlier plan do not count.
The chat fallback relies on the model obtaining genuine human confirmation; the server cannot independently prove who supplied it. Clients advertising App support must use the human button. No dashboard approval is involved. For a brief that names multiple countries, ask the user to select one country or create separately approved country-specific studies or launches. Never allow an omitted country to silently become a different market. Direct launch requires incident_rate >= 10. Use submit_feasibility_request for lower-incidence or specialized audiences. A feasibility request is a persistent manual-review record; use cancel_feasibility_request to withdraw it while pending. Feasibility request status is received, responded, or cancelled. Only a pending request can be cancelled. Panel country responses use uppercase country codes and lowercase language codes; use a lowercase code such as en to filter by language. Describe audience criteria in ordinary language through customize_study. The backend matches suitable criteria such as age or household income to canonical targeting attributes and decides when a custom screener is needed. Targeting attributes are not accepted by launch_panel through MCP.