canonical: https://jentic.com/apis/greatquestion.co/greatquestion # Great Question API The Great Question API exposes the core resources of a Great Question UX research workspace - accounts, candidates, custom attributes, sessions, studies, and study participants - across 21 endpoints. It supports bulk candidate operations for synchronising panels with external systems, consent form management, and study-level participant lifecycle changes. Authentication is a single bearer token issued from the workspace settings. ## For AI agents Manage research candidates, run bulk panel imports, and operate UX research studies and sessions in Great Question. ## Scope Does not host video sessions, schedule meetings, or run quantitative analytics - use for managing UX research candidates, studies, and participants only. ## Capabilities - Look up the authenticated workspace account and list available accounts - Create, retrieve, and unsubscribe individual research candidates via `/v1/candidates` - Run bulk imports and deletions across the candidate panel via `/v1/candidates/bulk` endpoints - Record and retrieve consent form submissions for a candidate - Manage studies and the candidate-study assignments that drive recruiting - Track study participants and session activity through the studies surface ## Use cases ### Panel Synchronisation from a CRM Customer research teams use the bulk candidate endpoints to keep their Great Question panel in sync with the source-of-truth CRM, adding new customers and removing churned ones on a schedule. The bulk import endpoint accepts a list of candidates with custom attributes so segmentation rules in studies stay accurate. Example prompt: POST 500 candidates with company and plan attributes to `/v1/candidates/bulk` and confirm the response shows zero errors ### Consent Logging for Research Studies Research operations teams use the consent forms endpoint on candidates to retrieve evidence that a participant agreed to recording, data retention, or compensation terms before a session takes place. The API surfaces the consent form record so it can be stored alongside session artifacts. Example prompt: GET `/v1/candidates/{candidate_id}/consent_forms` and store each consent record in the team's research drive ### Study Participant Tracking Research managers use the Studies and Study Participants endpoints to monitor recruiting progress for an active study, see which candidates accepted or completed sessions, and trigger follow-up outreach for no-shows. Example prompt: List study participants for the active study and email a follow-up to anyone whose status is 'invited' but not 'scheduled' ### Agent-Driven Research Operations Assistant via Jentic An AI research operations assistant uses Jentic to discover the right Great Question operation when a researcher asks 'add this customer to the panel' or 'who's signed up for the pricing study?'. Jentic injects the bearer token from the vault and the agent works with structured Great Question data. Example prompt: Search Jentic for 'add a candidate to great question', load the schema, and execute `/v1/candidates` with the user's lead details ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/v1/account` | Retrieve the authenticated account | | GET | `/v1/candidates` | List research candidates | | POST | `/v1/candidates` | Create a research candidate | | POST | `/v1/candidates/bulk` | Bulk import candidates | | POST | `/v1/candidates/bulk/delete` | Bulk delete candidates | | POST | `/v1/candidates/unsubscribe` | Unsubscribe a candidate from outreach | | GET | `/v1/candidates/{candidate_id}/consent_forms` | Retrieve a candidate's consent forms | ## Key resources - **Accounts** — Read the authenticated workspace account and list accessible accounts - **Candidates** — Create, retrieve, unsubscribe, and bulk-manage research candidates - **Custom Attributes** — Manage the custom fields stored against candidates - **Sessions** — Track research sessions tied to studies and participants - **Studies** — Operate research studies and their lifecycle - **Study Candidates** — Assign and inspect candidate-study relationships - **Study Participants** — Track participant progress through a study ## Why Jentic - **Setup:** Wiring the Great Question API by hand means carrying its bearer token and wiring the candidate, study, participant, and consent-form endpoints yourself. Through Jentic you install once, import the Great Question API from the API Directory, store the bearer token once, and your agent calls it. - **Permission scoping:** Great Question puts the study id in the URL path (`/studies/{study_id}/candidates`, `/studies/{study_id}/participants`), so a rule can pin your agent to one study: it can read the candidates and participants for that study and nothing else. You choose the operations it may call, so ones like bulk-deleting candidates are not included unless you add them. - **Credential handling:** Your Great Question bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'list participants in a research study' or 'add a candidate to a study', and Jentic returns the matching Great Question operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Typeform** — Collect screener responses that feed into a Great Question panel - **Qualtrics** — Enterprise experience-management platform with research and survey capabilities - **SurveyMonkey** — Survey platform that overlaps on quantitative research collection - **Outlook Calendar** — Schedule research sessions on the moderator's calendar ## FAQ ### What authentication does the Great Question API use? The API uses HTTP bearer authentication. Generate a token from the Great Question workspace settings and pass it in the Authorization header on every request. Through Jentic the bearer token is held in the encrypted vault and injected per call so the agent never holds the raw token. ### Can I bulk import candidates into Great Question? Yes. POST a list of candidate objects to `/v1/candidates/bulk` with email, name, and custom attribute fields. The response indicates per-row success or error so the caller can retry only the failed rows. There is also a `/v1/candidates/bulk/delete` endpoint for bulk removal. ### What are the rate limits for the Great Question API? Great Question does not publish a fixed numerical limit and recommends backing off on HTTP 429 responses. For panel sync workloads, prefer the `/v1/candidates/bulk` endpoints over per-row calls and run on a schedule rather than continuously. Jentic surfaces 429 responses to the agent so it can wait before retrying. ### How do I add a new candidate through Jentic? Search Jentic for 'add a candidate in great question', load the operation that maps to POST `/v1/candidates`, and execute it with the candidate's email, name, and any custom attributes. The response includes the new candidate id which can then be used in study-candidate assignments. ### Can I retrieve a candidate's signed consent forms? Yes. GET `/v1/candidates/{candidate_id}/consent_forms` returns the consent records linked to that candidate, which can be archived alongside session recordings for compliance. The endpoint is scoped to the authenticated account so it only returns consent forms for candidates in your workspace. ### Does this API support managing studies, not just candidates? Yes. The Studies, Study Candidates, and Study Participants tags expose endpoints for inspecting studies and the candidates assigned to them. Combined with the Candidates surface, an agent can operate the full recruiting lifecycle from importing a candidate to tracking session completion. ### Can I limit what my agent is allowed to do with the Great Question API? Yes. Because your Jentic One instance is self-hosted, your own rules decide which Great Question operations and credentials the agent may use. Since Great Question puts the study id in the URL path, such as `/studies/{study_id}/candidates` and `/studies/{study_id}/participants`, you can pin the agent to a single study so it only reads that study's candidates and participants. You also choose the exact operations it may call, so destructive ones like `/v1/candidates/bulk/delete` stay off limits unless you explicitly allow them.