Skip to content
SurveyRock Support

Submit survey responses

POST
/response/surveys/{surveyId}
curl --request POST \
  --url https://app.surveyrock.com/api/v1/response/surveys/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "respondentId": "example", "responses": [ { "elementId": "example", "type": "example", "value": "example", "meta": {} } ], "pageId": "example", "metadata": {} }'

Submit survey responses using shared ResponseService. Implements proper validation, tenant scoping, and rate limiting.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
surveyId
required
string
>= 16 characters <= 16 characters

Survey ID

Request Bodyrequired

Section titled “Request Bodyrequired”

Response submission data

Media typeapplication/json
object
respondentId
required

Respondent ID

string
>= 16 characters <= 16 characters
responses
required

Individual question responses

Array<object>
object
elementId

Element ID

string
>= 16 characters <= 16 characters
type

Question type

string
value

Response value (shape varies by question type)

meta

Response metadata

object
pageId

Page ID; if provided, updates respondent progress

string
nullable >= 16 characters <= 16 characters
metadata

Submission metadata

object
Examplegenerated
{
  "respondentId": "example",
  "responses": [
    {
      "elementId": "example",
      "type": "example",
      "value": "example",
      "meta": {}
    }
  ],
  "pageId": "example",
  "metadata": {}
}

Responses

Section titled “Responses”

200

Section titled “200”

Responses submitted successfully

Media typeapplication/json
object
success
boolean
data
object
surveyId
string
respondentId
string
submittedCount
integer
responses
Array<object>
object
elementId
string
type
string
status
string
submittedAt
string format: date-time
metadata
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
Example
{
  "success": true,
  "data": {
    "responses": [
      {
        "status": "submitted"
      }
    ]
  },
  "meta": {
    "version": "3.0"
  }
}

400

Section titled “400”

Bad request - missing survey ID, missing body, or missing respondent ID

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
Example
{
  "success": false,
  "error": {
    "code": "survey_not_found"
  },
  "meta": {
    "version": "3.0"
  }
}

401

Section titled “401”

Unauthorized - invalid or missing token

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
Example
{
  "success": false,
  "error": {
    "code": "survey_not_found"
  },
  "meta": {
    "version": "3.0"
  }
}

403

Section titled “403”

Forbidden - insufficient permissions

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
Example
{
  "success": false,
  "error": {
    "code": "survey_not_found"
  },
  "meta": {
    "version": "3.0"
  }
}

404

Section titled “404”

Survey or respondent not found

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
Example
{
  "success": false,
  "error": {
    "code": "survey_not_found"
  },
  "meta": {
    "version": "3.0"
  }
}

422

Section titled “422”

Validation failed

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