Create Survey
Creates a new survey in the authenticated account. Returns the full survey object, including the two default pages Alchemer creates automatically.
Endpoint
PUT
v5/survey
Requires authentication
Path Parameters
This endpoint does not have path parameters.
None
Query Parameters
title
string
required
The title of the new survey.
type
string
required
The survey type. Accepted values:
survey, form, poll, quiz.status
string
The initial status of the survey. Example values:
Launched, Closed.team
string
The ID of the team to assign the survey to.
Response
Returns the result of the creation request and the full survey object.
result_ok
boolean
Whether the request succeeded.
data
object
The newly created survey object.
child attributes
id
string
The unique ID of the newly created survey.
team
array
The team or teams that own the survey.
child attributes
id
string
The unique ID of the team.
name
string
The display name of the team.
type
string
The survey type. Example values:
Standard Survey, QuestionLibrary.status
string
The status of the survey at time of creation.
created_on
string
Timestamp when the survey was created.
modified_on
string
Timestamp when the survey was last modified.
forward_only
boolean
Whether respondents are prevented from navigating back to previous pages.
languages
array
List of languages the survey is available in. Example:
["English"].title
string
The public-facing title of the survey.
internal_title
string
The internal title of the survey, used for organizational purposes within the Alchemer platform.
title_ml
object
Multilingual survey title, keyed by language name. Example:
{"English": "My Survey"}.theme
string
The ID of the theme applied to the survey.
blockby
string | null
The duplicate prevention method for the survey. Returns
"NONE" when no method is configured, or null if unset.statistics
null
Always
null on a newly created survey, as no responses exist yet.overall_quota
integer | null
The overall response quota for the survey, if set. Returns
null if no quota is configured.auto_close
string | null
The date and time the survey is configured to automatically close, if set. Returns
null if not configured.sso
array
SSO configuration for the survey. Returns an empty array if SSO is not configured.
links
object
Public URLs for accessing the survey.
child attributes
default
string
The default public URL for the survey.
campaign
string
The campaign distribution URL for the survey.
pages
array
Ordered array of page objects. A newly created survey includes two default pages: an untitled first page and a Thank You page.
child attributes
id
integer
The unique ID of the page.
title
object
The page title, keyed by language. Example:
{"English": "Page 1"}.description
array
Description content for the page. Empty array if not set.
properties
object
Configuration properties for the page.
child attributes
hidden
boolean
Whether the page is hidden from respondents.
questions
array
Array of question objects on this page. Empty array if the page has no questions.
child attributes
id
integer
The unique ID of the question.
base_type
string
The base classification of the question. Example values:
Question, Action, Decorative.type
string
The question type. Example values:
FILE, HIDDEN, INSTRUCTIONS.title
object
The question title, keyed by language. Example:
{"English": "What is your name?"}.shortname
string | null
The shortname assigned to the question, used for variable referencing. Empty string or
null if not set.description
array
Description content for the question. Empty array if not set.
has_showhide_deps
boolean | null
Whether the question has show/hide logic dependencies. Returns
null if not applicable.comment
boolean | null
Whether the question has a comment field enabled.
properties
object
Configuration properties for the question. The specific fields present vary by question type.
options
array
Answer options for the question. Empty array if the question type does not use options.
child attributes
id
integer
The unique ID (SKU) of the option.
title
object
The option label, keyed by language.
value
string
The reporting value for the option.
properties
object | null
Additional properties for the option. Returns
null if none are set.show_rules_ids
array | null
IDs of the show/hide logic rules applied to this question. Returns
null if no rules are set.Examples
Request (cURL)
curl -X PUT "https://api.alchemer.com/v5/survey?api_token=YOUR_API_TOKEN&api_token_secret=YOUR_API_TOKEN_SECRET&title=Q1+Customer+Feedback"
Response
{
"result_ok": true,
"data": {
"id": "YOUR_SURVEY_ID",
"team": [
{
"id": "YOUR_TEAM_ID",
"name": "Team 1"
}
],
"type": "Standard Survey",
"status": "Launched",
"created_on": "2026-03-30 16:33:29",
"modified_on": "2026-03-30 16:33:29",
"forward_only": false,
"languages": [
"English"
],
"title": "Q1 Customer Feedback",
"internal_title": "Q1 Customer Feedback",
"title_ml": {
"English": "Q1 Customer Feedback"
},
"theme": "YOUR_THEME_ID",
"blockby": "NONE",
"statistics": null,
"overall_quota": null,
"auto_close": null,
"sso": [],
"links": {
"default": "https://survey.alchemer.com/s3/YOUR_SURVEY_ID/q1-customer-feedback",
"campaign": "https://survey.alchemer.com/s3/YOUR_SURVEY_ID/q1-customer-feedback"
},
"pages": [
{
"id": 1,
"title": {
"English": "(untitled)"
},
"properties": {
"hidden": false
},
"description": [],
"questions": []
},
{
"id": 2,
"title": {
"English": "Thank You!"
},
"properties": {
"hidden": false
},
"description": [],
"questions": [
{
"id": 1,
"base_type": "Decorative",
"type": "INSTRUCTIONS",
"title": {
"English": "Thank you for taking our survey. Your response is very important to us."
},
"shortname": null,
"varname": [],
"description": [],
"has_showhide_deps": null,
"comment": null,
"properties": {
"hidden": false,
"map_key": "instructions"
},
"options": [],
"show_rules_ids": null
}
]
}
]
}
}