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. Launch with the returned estimate_id using the same country only after explicit approval of the current plan and complete estimate. Supply a new idempotency_key for this approved launch and reuse that key with identical inputs if the call times out. Expired estimates and changes to relevant study, pricing, balance, or launch inputs require a fresh estimate. Client tool permissions and approval of an earlier plan version do not count.
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.