curl -X POST https://api.getversive.com/api/v1/studies \
-H "Authorization: Bearer $VERSIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Onboarding feedback — July",
"description": "Post-onboarding interview for new signups",
"welcome_message": {
"title": "Quick chat about your first week?",
"body": "This takes about 5 minutes.",
"ctaText": "Start"
}
}'
{
"id": "9b2f7c1e-4a4b-4f6e-9a1d-1c2d3e4f5a6b",
"title": "Onboarding feedback — July",
"description": "Post-onboarding interview for new signups",
"metadata": null,
"type": "VERSIVE_STUDY",
"mode": "TEXT_AND_VOICE",
"access_policy": "FULL_ACCESS",
"config": {
"interviewMode": "quality",
"lang": { "default": { "name": "English" } },
"tutorial": {
"enabled": false,
"requireMicCheck": false,
"showMicTest": false,
"showTimerColors": false,
"showTroubleshooting": false
}
},
"welcome_message": {
"title": "Quick chat about your first week?",
"body": "This takes about 5 minutes.",
"ctaText": "Start"
},
"tutorial_message": {
"title": "Before you begin",
"content": "<p>A few quick tips so the interview goes smoothly.</p><ul>...</ul>",
"ctaText": "Continue"
},
"thank_you_message": null,
"screen_out_message": { "title": "Thanks for your interest!" },
"created_at": "2026-07-13T10:30:00Z"
}
Studies
Create study
Create a new study
POST
/
studies
curl -X POST https://api.getversive.com/api/v1/studies \
-H "Authorization: Bearer $VERSIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Onboarding feedback — July",
"description": "Post-onboarding interview for new signups",
"welcome_message": {
"title": "Quick chat about your first week?",
"body": "This takes about 5 minutes.",
"ctaText": "Start"
}
}'
{
"id": "9b2f7c1e-4a4b-4f6e-9a1d-1c2d3e4f5a6b",
"title": "Onboarding feedback — July",
"description": "Post-onboarding interview for new signups",
"metadata": null,
"type": "VERSIVE_STUDY",
"mode": "TEXT_AND_VOICE",
"access_policy": "FULL_ACCESS",
"config": {
"interviewMode": "quality",
"lang": { "default": { "name": "English" } },
"tutorial": {
"enabled": false,
"requireMicCheck": false,
"showMicTest": false,
"showTimerColors": false,
"showTroubleshooting": false
}
},
"welcome_message": {
"title": "Quick chat about your first week?",
"body": "This takes about 5 minutes.",
"ctaText": "Start"
},
"tutorial_message": {
"title": "Before you begin",
"content": "<p>A few quick tips so the interview goes smoothly.</p><ul>...</ul>",
"ctaText": "Continue"
},
"thank_you_message": null,
"screen_out_message": { "title": "Thanks for your interest!" },
"created_at": "2026-07-13T10:30:00Z"
}
Creates a study in your organization. Versive applies sensible default configuration (interview mode, messages, screen-out defaults) and merges any
config you provide over those defaults.
Conversation mode:
TEXT_ONLY, TEXT_AND_VOICE, VOICE_WITH_PREVIEW, or VIDEO.Controls which organization members can access the study. Use
FULL_ACCESS, CAN_EDIT,
CAN_EDIT_SURVEY_ONLY, CAN_VIEW, or INVITE_ONLY. This does not control participant access.Study configuration overrides, merged over Versive’s defaults (AI interviewer settings, branding, languages, device rules, and so on).Branding and languages you omit here are filled in from your organization’s study defaults; values you send explicitly are kept as-is. A
lang you send keeps its default language, and an empty support list still takes the organization’s supported languages. A support list you send stays, except for a language that becomes the study’s default. When the organization’s default language applies, the welcome, thank-you, and screen-out messages you omit (or send as Versive’s English defaults) are written in that language. When the organization has a default response limit, the new study gets that Total completes quota (returned as quota); change it with PUT /studies/{id}/quotas. Participants see a supported language only once the study is translated: after adding questions, call Translate a study.Participant colors are primaryColor, textColor and backgroundColor, each a 6-digit hex value like #18181B (any other value returns a 422). Leave textColor and backgroundColor out, or send an empty string, to take your organization’s defaults; with no defaults set, participants see dark text on white. See Branding.AI interviewer settings you omit (interviewerPersonality, guidelines, allowQuestionRephrasing, questionRephrasingInstructions, interviewMode) use the same defaults as a study created in the dashboard, so the interviewer may rephrase questions. Send "allowQuestionRephrasing": false to have questions asked word for word.Memory is set with enableMemory (boolean, off by default), memoryFocus and memoryUsageRules (strings, up to 300 characters each).The tutorial page switches are set with tutorial: { enabled, requireMicCheck, showMicTest, showTimerColors, showTroubleshooting }, all booleans. Switches you omit are off, so send "enabled": true to show the page. null counts as false. Unknown switches and any other value return 422.Tutorial page copy:
{ title, content, ctaText }, where content is HTML. Fields you omit use the default page (header Before you begin, three setup tips, button Continue). See Copy for the length limits, the HTML that’s kept, and the 422 errors. The page is only shown once config.tutorial.enabled is true.Response
Returns the created study (status201) with fields: id, title, description, metadata, type, mode, config, welcome_message, tutorial_message, thank_you_message, screen_out_message, status, quota, pause_url, access_policy, and created_at.
curl -X POST https://api.getversive.com/api/v1/studies \
-H "Authorization: Bearer $VERSIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Onboarding feedback — July",
"description": "Post-onboarding interview for new signups",
"welcome_message": {
"title": "Quick chat about your first week?",
"body": "This takes about 5 minutes.",
"ctaText": "Start"
}
}'
{
"id": "9b2f7c1e-4a4b-4f6e-9a1d-1c2d3e4f5a6b",
"title": "Onboarding feedback — July",
"description": "Post-onboarding interview for new signups",
"metadata": null,
"type": "VERSIVE_STUDY",
"mode": "TEXT_AND_VOICE",
"access_policy": "FULL_ACCESS",
"config": {
"interviewMode": "quality",
"lang": { "default": { "name": "English" } },
"tutorial": {
"enabled": false,
"requireMicCheck": false,
"showMicTest": false,
"showTimerColors": false,
"showTroubleshooting": false
}
},
"welcome_message": {
"title": "Quick chat about your first week?",
"body": "This takes about 5 minutes.",
"ctaText": "Start"
},
"tutorial_message": {
"title": "Before you begin",
"content": "<p>A few quick tips so the interview goes smoothly.</p><ul>...</ul>",
"ctaText": "Continue"
},
"thank_you_message": null,
"screen_out_message": { "title": "Thanks for your interest!" },
"created_at": "2026-07-13T10:30:00Z"
}