Update element settings
const url = 'https://app.surveyrock.com/api/v1/elements/example/settings';const options = { method: 'PUT', headers: { 'If-Match': 'example', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"settings":{"typeSettings":{},"responseValidation":{}},"questionText":"example","helpText":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PUT \ --url https://app.surveyrock.com/api/v1/elements/example/settings \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'If-Match: example' \ --data '{ "settings": { "typeSettings": {}, "responseValidation": {} }, "questionText": "example", "helpText": "example" }'Update element settings using ElementService. settings is a patch (RFC 7396): only the keys sent change, an object merges into the stored one, a value or a list replaces it, and null removes a key. The merged settings are then checked as the design panel checks them, against the question-settings schema for the element’s type, exactly as stored (a string is not read as a boolean): 422 lists each wrong setting by location, e.g. “settings.typeSettings.labelsCount”, with the schema’s own message. Problems the element’s settings already had are not held against a patch that does not touch them. 403 feature_locked means the patch turns on a setting the account’s plan does not include. questionText and helpText are written with it, in the same transaction, so a refused settings patch leaves the text unchanged. questionText is rich text: it is sanitised to the safe subset the design editor allows, and a hand-typed question number token such as {{Q2_Answer}} is rewritten to its canonical form (the stored text is returned). helpText is plain text, stored as given, and an empty string clears it. null or an absent field leaves it unchanged. A successful update marks the survey’s draft as modified. 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”Element ID
Header Parameters
Section titled “Header Parameters”The element’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”Element update data: at least one of settings, questionText and helpText
object
Element configuration settings
object
Question type specific settings
object
Response validation rules
object
New question text. Rich text, sanitised to the design editor’s safe subset; cannot be empty.
New help text. Plain text; an empty string clears it.
Examplegenerated
{ "settings": { "typeSettings": {}, "responseValidation": {} }, "questionText": "example", "helpText": "example"}Responses
Section titled “Responses”Element settings updated successfully
object
object
The settings block and its new version; present only when settings were sent
object
The question text as stored (sanitised, question numbers rewritten); present only when questionText was sent
The help text as stored (null when cleared); present only when helpText was sent
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" }}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 - access denied to element, or (error code feature_locked; details name the plan that includes it) the patch turns on 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" }}Element 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.typeSettings.labelsCount”
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" }}