Create new survey
const url = 'https://app.surveyrock.com/api/v1/surveys';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"example","description":"example","language":"en","type":1,"settings":{},"questions":[{"type":"text_input","text":"example","subject":"example","helpText":"example","required":false,"choices":["example"],"multipleAnswers":false,"rows":["example"],"columns":["example"],"pageTitle":"example"}]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://app.surveyrock.com/api/v1/surveys \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "example", "description": "example", "language": "en", "type": 1, "settings": {}, "questions": [ { "type": "text_input", "text": "example", "subject": "example", "helpText": "example", "required": false, "choices": [ "example" ], "multipleAnswers": false, "rows": [ "example" ], "columns": [ "example" ], "pageTitle": "example" } ] }'Create new survey using shared SurveyService. Uses the same service as web SurveyController to ensure zero duplication. settings is checked exactly as in updateSurvey (nested, every value checked, 422 with field errors, 403 feature_locked for a setting the plan lacks), and a survey whose settings are refused is not created. With questions, the survey is created with those questions in one step, all or nothing, and the response lists each question’s new element id. The response carries the new resource’s ETag, as the ETag header and as meta.etag.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”1 to 128 characters, chosen by the caller. Optional on this operation: a retry with the same key and body replays the first response instead of applying the write twice; the same key with a different body is a 409
Request Bodyrequired
Section titled “Request Bodyrequired”Survey creation data
object
Survey name
Survey description
Survey language code
Survey type
Nested settings to start with, e.g. {“display”: {“progressStyle”: “bar”}}. See updateSurvey.
object
Optional. The survey’s questions, in order, written with the survey in one step: each is the question the survey editor would make for its type, with that type’s defaults. A question with pageTitle starts a new page with that title; the questions before the first one go on the first page. The list is checked whole first: any problem is a 422 naming each question at fault, and a list longer than the plan’s questions-per-survey limit is a 403 quota_exceeded. Either way no survey is created.
object
Question type. text_input is a free-text answer, rating_scale a rating scale, ranking puts choices in order, matrix asks rows against columns.
The question as respondents read it. Except for nps: an NPS question always asks the standard sentence, “How likely is it that you would recommend [subject] to a friend or colleague?”, so its text is not shown; set subject instead. The response gives each question’s text as respondents will see it.
For nps only: who or what is recommended, e.g. “us” or “our support team”. Leave it out for “this company”. Refused on other types.
Optional guidance shown under the question.
Whether a respondent must answer it.
The answer options, for multiple_choice and ranking. Ignored for other types.
For multiple_choice: let respondents pick more than one. Ignored for other types.
For matrix and slider: the statements rated. None gives the editor’s three placeholder rows. Ignored for other types.
For matrix: the answer columns. None keeps the editor’s standard scale. Ignored for other types.
Start a new page at this question, with this title.
Responses
Section titled “Responses”Survey created successfully
object
object
Present when the request had questions: each one written, in the request’s order, with the id its element now has.
object
Standard response metadata
object
Response timestamp in ISO 8601 format
API version
Unique request identifier
The resource’s ETag, on a read, create or update of a survey, element, rating or NPS question, distributor or contact. The same value as the ETag response header. Treat it as opaque and send it back as If-Match on the next update.
Example
{ "success": true, "meta": { "version": "3.0" }}Headers
Section titled “Headers”Example
"element:abc123:1790690123456789"The resource’s current version, as a strong validator. Opaque: send it back unchanged as If-Match. Also returned as meta.etag in the body, for a client that only sees the body.
Bad request - invalid data
Standard error response format
object
object
Stable, snake_case domain code – see ApiErrorHandler::EXCEPTION_MAP and DomainException
Human-readable error message
Imperative recovery hint for this domain code – see ApiErrorHandler::DOMAIN_CODE_SUGGESTIONS
Whether retrying the identical request might succeed without any change on the caller’s end
Additional, code-specific error details
object
Standard response metadata
object
Response timestamp in ISO 8601 format
API version
Unique request identifier
The resource’s ETag, on a read, create or update of a survey, element, rating or NPS question, distributor or contact. The same value as the ETag response header. Treat it as opaque and send it back as If-Match on the next update.
Example
{ "success": false, "error": { "code": "survey_not_found" }, "meta": { "version": "3.0" }}Forbidden - the account is over its limit; or (error code feature_locked; details name the plan that includes it) settings names a setting the account’s plan does not include; or (error code quota_exceeded; details give limit, requested and required_plan) questions has more questions than the plan allows on one survey. Nothing is created.
Standard error response format
object
object
Stable, snake_case domain code – see ApiErrorHandler::EXCEPTION_MAP and DomainException
Human-readable error message
Imperative recovery hint for this domain code – see ApiErrorHandler::DOMAIN_CODE_SUGGESTIONS
Whether retrying the identical request might succeed without any change on the caller’s end
Additional, code-specific error details
object
Standard response metadata
object
Response timestamp in ISO 8601 format
API version
Unique request identifier
The resource’s ETag, on a read, create or update of a survey, element, rating or NPS question, distributor or contact. The same value as the ETag response header. Treat it as opaque and send it back as If-Match on the next update.
Example
{ "success": false, "error": { "code": "survey_not_found" }, "meta": { "version": "3.0" }}Validation failed; details are keyed by location, e.g. “settings.display.progressStyle”
Validation error response with field-specific errors
object
object
Field-specific validation errors
object
Standard response metadata
object
Response timestamp in ISO 8601 format
API version
Unique request identifier
The resource’s ETag, on a read, create or update of a survey, element, rating or NPS question, distributor or contact. The same value as the ETag response header. Treat it as opaque and send it back as If-Match on the next update.
Example
{ "success": false, "error": { "code": "validation_failed", "message": "Validation failed", "suggestion": "Fix the fields listed in details and re-submit.", "retryable": false }, "meta": { "version": "3.0" }}