Update survey
const url = 'https://app.surveyrock.com/api/v1/surveys/example';const options = { method: 'PATCH', headers: { 'If-Match': 'example', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"name":"example","description":"example","language":"example","type":1,"active":1,"settings":{}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url https://app.surveyrock.com/api/v1/surveys/example \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'If-Match: example' \ --data '{ "name": "example", "description": "example", "language": "example", "type": 1, "active": 1, "settings": {} }'Update survey using shared SurveyService. Uses the same service as web SurveyController to ensure zero duplication. All body fields are optional; only provided fields are changed. settings is a nested patch: send only the settings to change, e.g. {“display”: {“progressStyle”: “bar”}}; settings not named are kept. Each value is checked by the rules the settings page uses and the patch is applied all together or not at all. 422 lists every wrong value by its location (“settings.display.progressStyle”), and a key that is not a changeable setting is a 422 too (the first such error lists the settable paths). 403 feature_locked means the patch is otherwise valid but names a setting the account’s plan does not include. Requires If-Match: the resource’s current ETag, from any read of it (the ETag header, or meta.etag in the body). 428 without it, 412 when it is stale (the resource was written since) and nothing is written; * skips the check. The response carries the next ETag.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Survey ID
Header Parameters
Section titled “Header Parameters”The survey’s current ETag (from a read), or * to skip the check
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 update data
object
Survey name
Survey description
Survey language code
Survey type
Read-only. The survey’s lifecycle state, which this endpoint refuses to change: a value other than the current one is a 422. To stop collecting responses, pause the survey’s links (pauseDistributor). To delete a survey, use the SurveyRock app.
Nested patch of the settings to change, e.g. {“display”: {“progressStyle”: “bar”}, “navigation”: {“showPrevious”: false}}. Settings not named are kept.
object
Examplegenerated
{ "name": "example", "description": "example", "language": "example", "type": 1, "active": 1, "settings": {}}Responses
Section titled “Responses”Survey updated successfully
object
object
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 - missing survey ID, missing body, or no updates provided
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" }}Unauthorized - invalid or missing token
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 - insufficient permissions, or (error code feature_locked; details name the plan that includes it) settings names a setting the account’s plan does not include
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" }}Survey not found
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" }}The ETag in If-Match is stale: the resource was written since it was read. Nothing was written. Read it again, reapply the change to what is there now, and retry with the new ETag (error code precondition_failed).
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" }}The request has no If-Match header. Read the resource and send its ETag (error code precondition_required).
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" }}