Surveys

Manage surveys, work with hidden variables and settings

Overview

The Surveys/Quizzes API lets you programmatically create surveys, manage questions, configure settings, handle hidden variables, control the survey lifecycle (duplicate, rename, archive, delete), and manage default label texts.

Quick navigation

Overview Create & edit Survey list Survey data Survey settings Survey questions Hidden URL variables Survey management Archived surveys

Download the markdown version of the "Surveys" section for use in ChatGPT / other LLMs:

AI Markdown

/static/api/quizzes.md

AI Markdown

Create & edit

This section covers creating a new survey and saving its questions.

Create survey

POST /quiz

Creates a new survey in the specified folder and returns the survey object.

Request body (JSON)

Field	Type	Required	Description
folder_id	integer	Yes	ID of the folder to create the survey in

Request example

curl -X POST "https://api.surveyninja.io/api/v3/service/quiz" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"folder_id": 5}'

Successful response (201)

Main fields

{ "id": 124, "workspace_id": 1, "name": "Survey #12", "virtual_id": "abc12xyz", "url_preview": "https://example.com/quiz/124/preview", "url_shared": "https://example.com/q/abc12xyz", "is_published": false }

Possible errors

HTTP	Code	Description
400	`workspace_not_found`, `folder_not_found`	Workspace or folder not found
401	`user_not_authenticated`	Invalid or missing authorization token
403	`quiz_limit_today`	Daily survey creation limit reached for this account
422	`validation_error`	Request body validation error

Survey questions

Save the full set of questions for a survey using the /quiz/{id}/save endpoint.

POST /quiz/{id}/save

Saves the full question structure for the survey. Replaces the existing set of questions.

Request body (JSON)

Field	Type	Required	Description
ids	array	Yes	Ordered array of question identifiers (UUIDs, "welcome", "submit")
entities	object	Yes	Object mapping each question ID to its full data object

ids values

The ids array contains question identifiers in display order. Special values:

Value	Description
welcome	Welcome screen (intro page)
submit	Completion screen (thank-you page)
UUID	UUID — a regular question

Common fields for all question types

Field	Type	Description
type	string	Required. Question type identifier (see types table below)
title	string	Question title / label text
withTitle	boolean	Show the title field
description	string	Question description / subtitle text
withDescription	boolean	Show the description field
isRequired	boolean	Make the question required
isBlocked	boolean	Block the question (hide from respondents)
multimedia	object \\| null	Multimedia object (image, video, audio) or null
filling_time_enabled	boolean	Enable per-question time limit
filling_time_seconds	integer	Time limit for the question in seconds

Question types

type	Name	Description
welcome	Welcome screen	Intro / welcome screen
yesno	Yes / No	Yes / No question
choice	Choice	Single or multiple choice from a list of options
dropdown	Dropdown	Dropdown list selection
ranking	Ranking	Drag-and-drop ranking of options
slider	Slider	Slider with configurable min/max/step
rating	Rating	Star/heart/emoji rating scale
scale	Scale	Numeric scale (e.g. 1–10)
input	Text input	Short or long text input
email	Email	Email address input field
phone	Phone	Phone number input field
datetime	Date & Time	Date and/or time picker
matrix	Matrix	Matrix grid (rows × columns)
message	Message	Static message or info block
file	File upload	File upload
html	HTML block	Custom HTML content block
submit	Submit screen	Completion / thank-you screen

Multimedia object structure

Field	Description
type	img, video, audio
imgUrl	URL of the image
videoUrl	URL of the video
imgLocation	Image position: top, left, right, background
videoSettings	Video player settings object

Additional fields by question type

welcome (welcome screen): welcomeLabel, welcomeWithResponseTime, welcomeWithQuestionCount

submit (completion screen): submitLabel, submitShowText, submitNextUrl, submitTerms, submitTermsTitle, submitTermsText

choice: choiceType (text/image), choiceMultiple, choiceRandomize, choiceTextOther; choiceTextIds + choiceTextEntities (UUID → {label, score, isCorrect}); choiceImageIds + choiceImageEntities

yesno: yesNoTextIds, yesNoTextEntities (UUID → {type: yes|no, label, score, isCorrect})

dropdown: dropdownIds, dropdownEntities (UUID → text), dropdownScores

ranking: rankingIds, rankingEntities, rankingRandomize, swapActive

slider: sliderMin, sliderMax, sliderStep, sliderValue

rating: ratingCount, ratingFigure (star/heart/thumb/smile), ratingValue, ratingWithNumber, ratingScores

scale: scaleCount, scaleStartValue (0/1), scaleLabelLeft/Central/Right, scaleLabelLeftValue, scaleLabelCentralValue, scaleLabelRightValue, scaleScores

input (text): inputPlaceholder, inputIsTextarea, inputWidth, inputHeight, inputLimit, inputLimitMin, inputLimitMax

email: emailPlaceholder, emailWidth

phone: phonePlaceholder, phoneWidth, phoneIsLimit, phoneLimitMin, phoneLimitMax

datetime: dateTimeType (dateAndTime/date/time), dateTimeFormatOfDate, dateTimeFormatOfTime (12/24), dateTimeSeparator (dot/slash/dash)

matrix: matrixChoiceType (radio/checkbox/text), matrixIsAllRequired, matrixRowIds, matrixColIds, matrixRowEntities, matrixColEntities, matrixTranspose

message: messageLabel, messageWithButton

html: htmlCode, htmlIsEmbedded

Validation rules

All values in ids must be unique
Every value in ids must have a corresponding entry in entities
Every key in entities must be present in ids
Each entity object must have a type field

Example: add a rating question

curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/save" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "ids": ["welcome", "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "submit"], "entities": { "welcome": { "type": "welcome", "title": "Welcome", "welcomeLabel": "Start" }, "a1b2c3d4-e5f6-7890-abcd-ef1234567890": { "type": "rating", "title": "Rate the service", "ratingCount": 5, "ratingFigure": "star" }, "submit": { "type": "submit", "submitLabel": "Submit" } } }'

Errors

HTTP	Description
400	Survey not found
401	Authorization required
403	Access to the survey is denied
422	Validation error: ids and entities are inconsistent
500	Internal server error while saving the survey structure

Get survey list

GET /quiz

Returns a paginated list of all active (non-archived) surveys.

Query parameters

Parameter	Type	Required	Description
sort	string	No	Field to sort by (e.g. name, created_at)
order	string	No	Sort direction: asc or desc
limit	integer	No	Maximum number of surveys to return
offset	integer	No	Number of surveys to skip (pagination offset)

Request example

curl -X GET "https://api.surveyninja.io/api/v3/service/quiz?sort=name&order=asc&limit=10&offset=0" \ -H "Authorization: Bearer YOUR_TOKEN"

API response

[ { "id": "survey ID", "name": "name", "url_shared": "survey URL", "is_published": true, "folder": { "id": 384, "workspace_id": 384, "user_id": 12, "name": "My Surveys", "pos": 1, "is_default": true, "created_at": "2022-04-01T08:37:14.000000Z", "updated_at": "2022-04-27T15:46:27.000000Z", "deleted_at": null } } ]

Get survey data

GET /quiz/{id}

Returns the full data object for a specific survey, including all questions and settings.

Request example

curl -X GET https://api.surveyninja.io/api/v3/service/quiz/123 \ -H "Authorization: Bearer YOUR_TOKEN"

API response

{ "id": "survey ID", "answer_count": "number of responses", "name": "name", "url_shared": "survey URL", "widgets": "question structure (ids, entities)", "hidden_options": "hidden variable", "folder": { "id": 384, "workspace_id": 384, "user_id": 12, "name": "My Surveys", "pos": 1, "is_default": true, "created_at": "2022-04-01T08:37:14.000000Z", "updated_at": "2022-04-27T15:46:27.000000Z", "deleted_at": null } }

Survey settings

Updates one or more setting groups for a survey. All parameters are optional — only the fields you send will be updated.

POST /quiz/{id}/settings/info

Basic

Parameter	Type	Description
name	string	Survey name / title
lang	string	Survey interface language code (e.g. en, ru)
info_title	string	Internal survey title (shown in the dashboard)
description	string	SEO meta description for the survey page

Display

Parameter	Type	Description
show_progressbar	boolean	Show progress bar
show_navigate	boolean	Show navigation buttons (Back / Next)
numeration	boolean	Show question numbers
auto_move_by_enter	boolean	Auto-advance to the next question when Enter is pressed
show_by_one	boolean	Show one question at a time
allow_multiple_answer	boolean	Allow multiple submissions from the same respondent
show_copyright	boolean	Show the SurveyNinja copyright footer

Access & restrictions

Parameter	Type	Description
close_quiz_enabled	boolean	Close the survey (stop accepting responses)
limit_time_enabled	boolean	Enable response deadline
limit_time_value	string	Response deadline (datetime string)
limit_time_timezone	string	Timezone for the response deadline (e.g. Europe/London)
limit_answer_count_enabled	boolean	Limit the total number of responses
limit_answer_count_value	integer	Maximum number of responses
use_password	boolean	Password-protect the survey
multiple_ip	boolean	Allow multiple responses from the same IP address
show_captcha	boolean	Show CAPTCHA before submission
ip_list_enabled	boolean	Enable IP address filtering
ip_whitelist	string	Comma-separated list of allowed IP addresses
ip_blacklist	string	Comma-separated list of blocked IP addresses
available_devices[]	array	Allowed devices: desktop, mobile, tablet

Behavior

Parameter	Type	Description
scoring_switcher	boolean	Enable scoring mode
question_required_mode	string	`individual` / `all_required` / `all_optional`
question_random_order	boolean	Randomize the order of questions
disable_auto_redirect	boolean	Disable automatic redirect after submission
block_jump_to_prev_widget	boolean	Prevent respondents from going back to previous questions
filling_time_enabled	boolean	Enable overall survey time limit
filling_time_seconds	integer	Survey time limit in seconds

Analytics & QR code

Parameter	Type	Description
scripts_in_head	string	Custom scripts inserted in
scripts_in_body	string	Custom scripts inserted before
scripts_in_head_enabled	boolean	Enable head scripts
scripts_in_body_enabled	boolean	Enable body scripts
sso_active	boolean	Enable Single Sign-On (SSO)
qr_code_size	integer	QR code size in pixels
qr_code_color	string	QR code foreground color (HEX)
qr_code_background_color	string	QR code background color (HEX)
qr_code_margin	integer	QR code margin in pixels

POST /api/v3/service/quiz/{id}/settings/info

curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/settings/info" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "New survey name", "lang": "en", "show_progressbar": true, "limit_answer_count_enabled": true, "limit_answer_count_value": 500, "question_required_mode": "all_required" }'

Hidden variables

Get hidden variables

GET /quiz/{id}/hidden/options

Returns the list of hidden variables configured for the survey.

Request example

curl -X GET https://api.surveyninja.io/api/v3/service/quiz/123/hidden/options \ -H "Authorization: Bearer YOUR_TOKEN"

Create hidden variable

POST /quiz/{id}/hidden/options/create

Creates a new hidden variable for the survey.

Request parameters

Parameter	Type	Required	Description
name	string	Yes	Variable name
value	string	Yes	Variable default value

Request example

curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/hidden/options/create \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "productType", "value": "clientShop" }'

Update hidden variable

POST /quiz/{id}/hidden/options/update/{opt_id}

Updates the name and default value of a hidden variable.

Request parameters

Parameter	Type	Required	Description
name	string	Yes	New variable name
value	string	Yes	New variable value

Request example

curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/hidden/options/update/123 \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "productType", "value": "updatedValue" }'

Delete hidden variable

POST /quiz/{id}/hidden/options/delete/{opt_id}

Deletes a hidden variable from the survey.

Request example

curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/hidden/options/delete/123 \ -H "Authorization: Bearer YOUR_TOKEN"

Hidden variables in questions

Get hidden variables in questions

GET /quiz/{id}/widgets/hidden/options

Returns the list of hidden variables embedded in survey questions.

Request example

curl -X GET https://api.surveyninja.io/api/v3/service/quiz/123/widgets/hidden/options \ -H "Authorization: Bearer YOUR_TOKEN"

Add hidden variable to question

POST /quiz/{id}/widgets/hidden/options/create

Adds a hidden variable to a specific question.

Parameter	Type	Description	Required
name	string	Variable name	Yes
value	string	Variable default value	Yes
widget_uuid	string	UUID of the question (widget) to attach the variable to	Yes

Request example

curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/widgets/hidden/options/create \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "productType", "value": "clientShop", "widget_uuid": "c63b9a88-2f1b-4735-a7ab-0b5fd84c90c2" }'

Update hidden variable in question

POST /quiz/{id}/widgets/hidden/options/update/{opt_id}

Updates the name and value of a hidden variable attached to a question.

Parameter	Type	Description	Required
name	string	New variable name	Yes
value	string	New variable value	Yes

Request example

curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/widgets/hidden/options/update/123 \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "productType", "value": "clientShop" }'

Delete hidden variable from question

POST /quiz/{id}/widgets/hidden/options/delete/{opt_id}

Removes a hidden variable from a specific question.

Request example

curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/widgets/hidden/options/delete/123 \ -H "Authorization: Bearer YOUR_TOKEN"

Survey management

The following endpoints let you manage the lifecycle of surveys: add notes, duplicate, rename, make a template, archive, move, and delete.

Survey lifecycle

POST /quiz/{id}/save

Saves the full question structure of the survey (replaces existing questions).

Request example

curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/save" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "ids": ["welcome", "question-1", "submit"], "entities": { "welcome": { "type": "welcome", "...": "..." }, "question-1": { "type": "choice", "title": "...", "...": "..." }, "submit": { "type": "submit", "...": "..." } } }'

POST /quiz/{id}/applyTheme/{theme_id}

Applies a design theme to the survey.

Request example

curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/applyTheme/925" \ -H "Authorization: Bearer YOUR_API_TOKEN"

POST /quiz/{id}/publish

Publishes the current draft of the survey so respondents can access it.

Request example

curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/publish" \ -H "Authorization: Bearer YOUR_API_TOKEN"

POST /quiz/{id}/conditions

Saves the branching logic (skip/jump conditions) for the survey.

Request example

curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/conditions" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "conditions": { "...": "logic structure, same as in the builder" } }'

Add note

POST /quiz/{id}/note

Adds or updates a note (internal comment) attached to the survey.

Request parameters

Parameter	Type	Required	Description
notes	string	Yes	Note text (maximum 1000 characters)

Request example

curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/note \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "notes": "Note text (maximum 1000 characters)" }'

API response

{ "status": true, "notes": "Note text" }

Duplicate survey

POST /quiz/{id}/duplicate

Creates a full copy of the survey including all questions and settings.

Request parameters

Parameter	Type	Required	Description
name	string	No	Name for the duplicated survey (optional; defaults to a copy of the original name)

Request example

curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/duplicate \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Copy name (optional)" }'

API response

{ "status": true, "quiz": { "id": 123, "name": "Copy: Survey Name", "url_shared": "https://example.com/abc123", "is_published": false, "created_at": "2024-01-01T12:00:00Z", "updated_at": "2024-01-01T12:00:00Z", "folder": { "id": 1, "name": "My Folder" } } }

Rename survey

POST /quiz/{id}/rename

Renames the survey.

Request parameters

Parameter	Type	Required	Description
name	string	Yes	New survey name

Request example

curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/rename \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "New survey name" }'

API response

{ "status": true, "name": "New survey name" }

Make template

POST /quiz/{id}/template

Marks the survey as a reusable template available in the template gallery.

Request example

curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/template \ -H "Authorization: Bearer YOUR_TOKEN"

API response

{ "status": true }

Archive survey

POST /quiz/{id}/archive

Archives or unarchives a survey. Archived surveys do not accept new responses.

Request parameters

Parameter	Type	Required	Description
archive	boolean	Yes	true — archive the survey, false — unarchive

Request example

curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/archive \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "archive": true }'

API response

{ "status": true, "archive_at": "2024-01-01T12:00:00Z", "is_archived": true }

Move survey

POST /quiz/{id}/move

Moves the survey to a different folder within the same workspace.

Request parameters

Parameter	Type	Required	Description
folder_id	integer	Yes	ID of the target folder

Request example

curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/move \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "folder_id": 5 }'

API response

{ "status": true, "folder_id": 5, "folder": { "id": 5, "name": "New Folder" } }

Delete survey

DELETE /quiz/{id}

Permanently deletes a survey along with all its responses. This action cannot be undone.

Request example

curl -X DELETE https://api.surveyninja.io/api/v3/service/quiz/123 \ -H "Authorization: Bearer YOUR_TOKEN"

API response

{ "status": true }

Archived surveys

GET /quiz/archived

Returns the list of archived surveys.

Request example

curl -X GET https://api.surveyninja.io/api/v3/service/quiz/archived \ -H "Authorization: Bearer YOUR_TOKEN"

API response

[ { "id": 123, "name": "Archived survey", "url_shared": "https://example.com/abc123", "is_published": false, "created_at": "2024-01-01T12:00:00Z", "updated_at": "2024-01-01T12:00:00Z", "archive_at": "2024-01-02T12:00:00Z", "folder": { "id": 1, "name": "My Folder" } } ]

Hidden URL variables

Hidden URL variables are appended to the survey link as query parameters and captured automatically when a respondent opens the survey.

List hidden URL variables GET /api/v3/service/quiz/{id}/hidden/variables

Returns the list of hidden URL variables configured for the survey.

GET /api/v3/service/quiz/{id}/hidden/variables

curl -X GET "https://api.surveyninja.io/api/v3/service/quiz/123/hidden/variables" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json"

Response example:

[ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "utm_source" }, { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "name": "user_id" } ]

Create hidden URL variable POST /api/v3/service/quiz/{id}/hidden/variables/create

Parameter	Required	Description
name	yes	Variable name used as the query parameter key
id	no	Custom UUID for the variable (auto-generated if not provided)

Errors: 422 if the name already exists or is invalid; 400 if the survey is not found.

POST /api/v3/service/quiz/{id}/hidden/variables/create

curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/hidden/variables/create" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "utm_source" }'

Update hidden URL variable POST /api/v3/service/quiz/{id}/hidden/variables/update/{field_id}

Parameter	Required	Description
name	yes	New variable name

POST /api/v3/service/quiz/{id}/hidden/variables/update/{field_id}

curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/hidden/variables/update/550e8400-e29b-41d4-a716-446655440000" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "utm_campaign" }'

Delete hidden URL variable POST /api/v3/service/quiz/{id}/hidden/variables/delete/{field_id}

No request body required.

POST /api/v3/service/quiz/{id}/hidden/variables/delete/{field_id}

curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/hidden/variables/delete/550e8400-e29b-41d4-a716-446655440000" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json"

Default texts

Default labels are button and UI texts shown to respondents (e.g. Next, Back, Submit). Retrieve current values and override them per survey.

Get default texts GET /api/v3/service/quiz/{id}/default-texts

Parameter	Type	Default	Description
lang	string	ru	Language code for which to retrieve labels (e.g. ru, en)

Returns an array of label objects, each with code, standard_text, and user_text (custom override, or null).

GET /api/v3/service/quiz/{id}/default-texts

curl -X GET "https://api.surveyninja.io/api/v3/service/quiz/123/default-texts?lang=ru" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json"

Response example

[ { "code": "btn_next", "standard_text": "Next", "user_text": null }, { "code": "btn_back", "standard_text": "Back", "user_text": "Go Back" }, { "code": "btn_submit", "standard_text": "Submit", "user_text": null } ]

Update default texts POST /api/v3/service/quiz/{id}/default-texts

Updates custom label texts for the survey. Pass text: null to reset to the standard text.

Parameter	Type	Description
texts[]	array	Array of objects with fields code and text
texts[].code	string	Label code from the GET response
texts[].text	string\|null	New text; null resets to the standard value

Error 400 blocked_by_tariff — the feature is not available on the current plan.

POST /api/v3/service/quiz/{id}/default-texts

curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/default-texts" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "texts": [ { "code": "btn_next", "text": "Forward" }, { "code": "btn_back", "text": null } ] }'

Previous section

Next section