curl -X POST https://api.getversive.com/api/v1/questions/batch \
-H "Authorization: Bearer $VERSIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"questions": [
{
"id": "8d3b6a2f-1c4e-4f7a-b5d9-2e6c8a0f4b1d",
"study_id": "9b2f7c1e-4a4b-4f6e-9a1d-1c2d3e4f5a6b",
"content": "Which plan are you currently on?"
},
{
"study_id": "9b2f7c1e-4a4b-4f6e-9a1d-1c2d3e4f5a6b",
"type": "question",
"content": "Why did you choose the {{Q:8d3b6a2f-1c4e-4f7a-b5d9-2e6c8a0f4b1d}} plan?",
"props": { "required": true, "maxFollowupQuestions": 3 }
}
]
}'
{
"created_question_ids": ["4f9c1e7a-6b2d-4a8e-9c3f-1d5b7e9a2c4f"],
"updated_question_ids": ["8d3b6a2f-1c4e-4f7a-b5d9-2e6c8a0f4b1d"]
}
Questions
Batch create/update questions
Create and update questions in one call
POST
/
questions
/
batch
curl -X POST https://api.getversive.com/api/v1/questions/batch \
-H "Authorization: Bearer $VERSIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"questions": [
{
"id": "8d3b6a2f-1c4e-4f7a-b5d9-2e6c8a0f4b1d",
"study_id": "9b2f7c1e-4a4b-4f6e-9a1d-1c2d3e4f5a6b",
"content": "Which plan are you currently on?"
},
{
"study_id": "9b2f7c1e-4a4b-4f6e-9a1d-1c2d3e4f5a6b",
"type": "question",
"content": "Why did you choose the {{Q:8d3b6a2f-1c4e-4f7a-b5d9-2e6c8a0f4b1d}} plan?",
"props": { "required": true, "maxFollowupQuestions": 3 }
}
]
}'
{
"created_question_ids": ["4f9c1e7a-6b2d-4a8e-9c3f-1d5b7e9a2c4f"],
"updated_question_ids": ["8d3b6a2f-1c4e-4f7a-b5d9-2e6c8a0f4b1d"]
}
Creates and/or updates questions in a single study in one request. Items with an
To map each ID back to the question you sent, walk your
id are updated; items without an id are created (appended after the existing questions in the order given). Returns 201.
Optional, up to 255 characters. Makes the request safe to retry; see Retries.
The questions to create or update, at most 500 per request (more returns
422). Every item must include the same study_id. Recognized fields per item:id— include to update an existing question; omit to create.study_id— required on every item.content— question text; may include{{Q:...}}references.type— question type (see List questions for values).props— type-specific settings object. On updates it is merged with the existing props, with the same handling of multiple-choiceexclusiveOptionsas Update question and the same validation ofearlierAnswerChecks(checks against earlier answers).interviewer_notes— private AI guidance.display_condition_match—allorany, as in Update question; any other value returns400.assets— media assets array.asset— attach a verified upload ({ "upload_id", "layout", "sizing", "max_width_percent", "autoplay", "loop" }) or copy another question’s media in the same study ({ "copy_from_question_id", "layout" }), see Update question;nullremoves the default-language asset (translated-language variants are kept). Cannot be combined withassets,embedded_website_url, orfigma_prototype_urlon the same item.embedded_website_url— anhttps://page framed beside the question; not onwebsiteTest,prototypeTask, orcalendar. Figma links are refused (pass them asfigma_prototype_url), as are v0 share links.figma_prototype_url— a public Figma prototype link, stored embed-only underhttps://www.figma.com/proto/…: required onprototypeTask(the task’s prototype), and on any other type exceptwebsiteTestandcalendarit attaches the prototype as the question’s asset. On aprototypeTask, replacing the link clears an existingprops.goalNode, and a non-emptygoalNodein the same item is refused.display_order— position (new questions are auto-ordered if omitted).
Question references (mentions)
content can reference an earlier answer with either:
{{Q:<question_id>}}— the complete answer.- A type-specific property token — one option response from a structured answer, such as:
{{Q:<matrix_question_id>.ratingForItem[0]}}{{Q:<ranking_question_id>.rankOfOption[0]}}{{Q:<ranking_question_id>.optionAtRank[0]}}{{Q:<allocation_question_id>.allocationForItem[0]}}
.option[index] selector; it is not supported.
Call List available references for the destination question’s position and copy the returned template verbatim. References are validated on write, and invalid property names, indices, missing questions, or forward references fail with 422 and an errors array.
Response
IDs of newly created questions, in request order:
created_question_ids[i] is the ID of the i-th item without an id. Items with an id are skipped, and display_order or question_group_id on an item does not change its position in this list.questions array and take the next ID from created_question_ids for each item without an id, and the next ID from updated_question_ids for each item with one.
Errors
The batch is validated before anything is written. When one item is invalid, the request fails with400, 403, or 404 and a detail that names the item by its zero-based position, for example "questions[2]: Unknown question type 'notAType'. ...". Fix that item and resend the whole batch.
Two checks run after the rows are written: {{Q:...}} references on every item, and checks against earlier answers on new questions. A 422 from either one leaves the batch written and does not return the new IDs. Retrying the same request with the same Idempotency-Key returns the same 422 without creating the questions again; fix the batch and send it with a new key.
Retries
Send anIdempotency-Key header (a UUID you generate per batch works well) and you can resend the same request after a timeout, a network error, or a 5xx without creating questions twice. A retry with the same key and the same body returns the same created_question_ids as the first attempt, and the questions are written once, even when the retries overlap.
The key only covers that exact body: the same key with a different body is treated as a new batch. Without the header, every request creates new questions.
The example below creates one new question and updates an existing one (8d3b6a2f-1c4e-4f7a-b5d9-2e6c8a0f4b1d), piping that existing question’s answer into the new question’s text. References must point at questions that already exist in the study — use List available references to discover valid templates.
curl -X POST https://api.getversive.com/api/v1/questions/batch \
-H "Authorization: Bearer $VERSIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"questions": [
{
"id": "8d3b6a2f-1c4e-4f7a-b5d9-2e6c8a0f4b1d",
"study_id": "9b2f7c1e-4a4b-4f6e-9a1d-1c2d3e4f5a6b",
"content": "Which plan are you currently on?"
},
{
"study_id": "9b2f7c1e-4a4b-4f6e-9a1d-1c2d3e4f5a6b",
"type": "question",
"content": "Why did you choose the {{Q:8d3b6a2f-1c4e-4f7a-b5d9-2e6c8a0f4b1d}} plan?",
"props": { "required": true, "maxFollowupQuestions": 3 }
}
]
}'
{
"created_question_ids": ["4f9c1e7a-6b2d-4a8e-9c3f-1d5b7e9a2c4f"],
"updated_question_ids": ["8d3b6a2f-1c4e-4f7a-b5d9-2e6c8a0f4b1d"]
}