Create Survey Question
Creates a new question on a specified page of a survey. Supports all Alchemer question types and a wide range of configuration properties.
Endpoint
PUT
v5/survey/{survey_id}/surveypage/{page_id}/surveyquestion
Requires authentication
Path Parameters
Identifies the survey and page on which the question will be created.
survey_id
string
required
The ID of the survey to add the question to.
page_id
string
required
The ID of the survey page to add the question to.
Query Parameters
type
string
The question type to create. Accepted values:
radio, checkbox, menu, text, essay, email, multitext, single-image, multi-image, contsum, rank-dragdrop, table-radio, table-checkbox, table-textbox, table-menu-matrix, table-stars, file, instructions, media, audio, video, hidden, urlredirect, group, heatmap, texthighlighter, httpinsert, javascript.
title
string
The question text.
description
string
Description or sub-text for the question.
after
string
The ID of the question this new question should follow. Used to control placement on the page.
shortname
string
A shortname or alias for the question.
varname
string
The SPSS variable name for the question. For question types with multiple fields (e.g. Textbox List), specify as an array keyed by option ID — for example,
varname[10001]=Comedy&varname[10002]=Drama.
id
string
The question ID of the parent question. Required when adding sub-questions (rows) to grid question types:
table-radio, table-checkbox, table-textbox, table-menu-matrix, table-stars, and group. Use multitext to create rows of a Dropdown Menu Grid.
properties
object
Configuration properties for the question. All
properties keys are passed as individual query parameters using bracket notation — for example, properties[required]=true.child attributes
disabled
boolean
Disables the question so it cannot be answered.
exclude_number
boolean
Excludes the question number from the display.
hide_after_response
boolean
Hides the question after it has been answered.
option_sort
string
Controls sorting of answer options. Accepted values:
ALPHA (alphabetical), NONE (original creation order), SHUFFLE (randomized), true (alphabetical), false (original order).orientation
string
Display orientation for answer options. Accepted values:
HORZ, VERT.labels_right
boolean
Positions option labels to the right of the input.
question_description_above
boolean
Displays the question description above the question title rather than below.
custom_css
string
A CSS template hook for custom styling on this question.
placeholder
object
Placeholder text shown inside open-text question fields, keyed by language. The language must be specified as part of the key — for example,
properties[placeholder][English]=Enter+your+answer. The language key is required.required
boolean
Makes the question required before the respondent can advance.
soft-required
boolean
Prompts the respondent if they skip the question but does not block advancement.
force_numeric
boolean
Restricts input to numeric values only.
force_percent
boolean
Restricts input to percentage values.
force_currency
boolean
Restricts input to currency-formatted values.
subtype
string
Specifies a validation subtype. Accepted values:
email, date.min_number
string
The minimum accepted numeric value.
max_number
string
The maximum accepted numeric value.
min_answers_per_row
string
Minimum number of answers required per row (grid questions).
minimum_response
string
Minimum number of selections or characters required.
inputmask
object
Input validation mask settings. Pass sub-keys using bracket notation — for example,
properties[inputmask][mask]=\d{5}.child attributes
mask
string
A RegEx pattern used to validate input format.
message
string
The validation error message to display when the input mask pattern is not matched.
defaulttext
string
Default text or reporting value to pre-populate in the question field.
hidden
boolean
Hides the question from respondents. The question is still included in the response data.
piped_from
string
The ID of the question to pipe answer text from into this question's title or description.
save_logic_data
boolean
When set to
true, saves display and skip logic data with this question.admin_question
boolean
Marks the question as an admin-only question, visible only in admin reports.
randomizer_ignore
boolean
Excludes this question from page-level randomization.
fixed_placement
boolean
Pins the question to its current position when page-level randomization is applied.
max_total
string
Continuous Sum. The maximum total value respondents may enter across all fields.
max_total_noshow
boolean
Continuous Sum. When
true, hides the running total display from respondents.must_be_max
boolean
Continuous Sum. Requires the respondent's total to equal the specified maximum before they can advance.
maxfiles
integer
File Upload. Maximum number of files the respondent may upload. Accepted values:
1–10.extentions
string
File Upload. Comma-separated list of allowed file extensions. Example:
png,gif,jpg,pdf,docx.url
string
URL Redirect / HTTP Insert. The destination URL for redirect questions, or the webhook endpoint for HTTP Insert questions.
outbound
object
URL Redirect. Keyed object of outbound variables to pass to the redirect URL. Replace
n with the index of each variable — for example, properties[outbound][0][fieldname]=myVar.child attributes
fieldname
string
The variable name to pass to the redirect URL.
mapping
string
The question ID whose answer should be passed as the value of this variable.
default
string
Default value to pass when the mapped question has no answer.
heatmap_image
string
Heatmap. URL of the image to use as the heatmap background.
messages
object
Text Highlighter. Contains the text content for respondents to highlight. Pass the content using the full key path — for example,
properties[messages][th_content][English]=URL-encoded+text. The language key is required.data_type
string
HTTP Insert. Accepted values:
response (sends full response data) or fields (sends specific fields, which must be configured in the UI). Required for HTTP Insert questions.data_json
boolean
HTTP Insert. When
true, sends response data as JSON. Only applies when data_type is set to response.aurl
string
Audio / Video. The URL of the audio or video content, formatted as
//www.example.com/file. Required for audio and video question types.http
string
Audio / Video. The protocol to use for the media URL. Accepted values:
http, https. Defaults to http if an invalid value is passed. Required for audio and video question types.limits
array
Dropdown Menu Grid. Array of dropdown answer options. Pass each as a separate parameter — for example,
properties[limits][]=apple&properties[limits][]=orange. Required for Dropdown Menu Grid questions.javascript_code
string
JavaScript Action. Base64-encoded JavaScript code to execute as a question action.
Response
Returns the result of the creation request and the newly created question object.
result_ok
boolean
Whether the request succeeded.
data
object
The newly created survey question object. See Get Survey Question for the full list of response fields.
Examples
Request (cURL)
curl -X PUT "https://api.alchemer.com/v5/survey/123456/surveypage/1/surveyquestion?api_token=YOUR_API_TOKEN&api_token_secret=YOUR_API_TOKEN_SECRET&type=radio&title=How+satisfied+are+you%3F&properties[required]=true&properties[orientation]=VERT"
Response
{
"result_ok": true,
"data": {
"id": 7,
"type": "radio",
"title": {
"English": "How satisfied are you?"
},
"description": {
"English": ""
},
"shortname": "",
"varname": "",
"has_options": true,
"options": [],
"properties": {
"required": true,
"hidden": false,
"orientation": "VERT"
}
}
}