Add questions to a survey

POST

/surveys/{id}/questions

curl --request POST \
  --url https://app.surveyrock.com/api/v1/surveys/example/questions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "questions": [ {} ], "pageId": "example" }'

• API v1 endpoints

Add questions after the survey’s last question, or after the last question of the page named by pageId. Each is the question the survey editor would make for its type, with that type’s defaults; the list takes the same fields as createSurvey’s questions. A question with pageTitle starts a new page at the end of the survey, so pageTitle is refused when pageId names a page other than the last. All or nothing: the list is checked whole first; any problem is a 422 naming each question at fault, and more questions than the plan allows on one survey (counting those it has) is a 403 quota_exceeded. Either way nothing is written. A published survey keeps collecting with its published questions until it is published again. Not idempotent: send an Idempotency-Key so a retry does not add the questions twice.

Authorizations

• bearerAuth
  elements:write

Parameters

Path Parameters

id

required

string

Survey ID

Header Parameters

Idempotency-Key

string

>= 1 characters <= 128 characters

1 to 128 characters, chosen by the caller. Recommended: adding questions is not idempotent, and a retry with the same key and body replays the first response instead of adding them twice; the same key with a different body is a 409

Request Body^required

Media typeapplication/json

object

questions

required

The questions to add, in order. Each takes the fields of createSurvey’s questions items: type (required), text (required), helpText, required, choices, multipleAnswers, rows, columns, pageTitle, subject (nps only; an NPS question asks the standard sentence about its subject, not its text). The response gives each question’s text as respondents will see it.

Array<object>

>= 1 items <= 100 items

object

pageId

The question page to add to (each element in listSurveyElements carries its page_id). Leave it out to add to the last page.

string

nullable

Example^generated

{
  "questions": [
    {}
  ],
  "pageId": "example"
}

Responses

200

Questions added

Media typeapplication/json

object

success

boolean

data

object

surveyId

string

questions

Each question added, in the request’s order, with its new element id and the page it is on.

Array<object>

object

elementId

string

pageId

string

type

string

text

string

meta

Standard response metadata

object

timestamp

Response timestamp in ISO 8601 format

string format: date-time

version

API version

string

requestId

Unique request identifier

string

etag

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.

string

Example

{
  "success": true,
  "meta": {
    "version": "3.0"
  }
}

403

Forbidden: the token or its owner may not edit this survey; or (error code quota_exceeded; details give limit, requested and required_plan) the survey would hold more questions than the plan allows. Nothing is written.

Media typeapplication/json

Standard error response format

object

success

boolean

error

object

code

Stable, snake_case domain code – see ApiErrorHandler::EXCEPTION_MAP and DomainException

string

message

Human-readable error message

string

suggestion

Imperative recovery hint for this domain code – see ApiErrorHandler::DOMAIN_CODE_SUGGESTIONS

string

retryable

Whether retrying the identical request might succeed without any change on the caller’s end

boolean

details

Additional, code-specific error details

object

meta

Standard response metadata

object

timestamp

Response timestamp in ISO 8601 format

string format: date-time

version

API version

string

requestId

Unique request identifier

string

etag

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.

string

Example

{
  "success": false,
  "error": {
    "code": "survey_not_found"
  },
  "meta": {
    "version": "3.0"
  }
}

422

Validation failed: questions is missing or names the questions at fault, or pageId is not one of the survey’s question pages

Media typeapplication/json

Validation error response with field-specific errors

object

success

boolean

error

object

code

string

message

string

suggestion

string

retryable

boolean

details

Field-specific validation errors

object

key

additional properties

Array<string>

meta

Standard response metadata

object

timestamp

Response timestamp in ISO 8601 format

string format: date-time

version

API version

string

requestId

Unique request identifier

string

etag

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.

string

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"
  }
}