Update rating label
const url = 'https://app.surveyrock.com/api/v1/rating/example/label';const options = { method: 'PUT', headers: { 'If-Match': 'example', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"setName":"default","positionName":"example","index":0,"newText":"example","updatedAt":1}'};
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/rating/example/label \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'If-Match: example' \ --data '{ "setName": "default", "positionName": "example", "index": 0, "newText": "example", "updatedAt": 1 }'Set the text of one rating scale label: typeSettings.labelSets.<setName>.positions.<positionName>. Only rating elements are accepted. The set and position names are checked by the question-settings schema, the same rules the design editor’s saves meet (a rating’s positions are label1, label2, …), and a 422 says which name is wrong. The survey’s draft is marked as modified. updatedAt is an optimistic lock: send the element’s last updatedAt and a write made in between is refused with 409. 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”Rating 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”Label update data
object
Label set name: letters, digits, underscore and hyphen, and not only digits
Label position: label1, label2, … (a rating has no left/center/right)
Must be 0 or omitted: each position holds one label
New label text (trimmed); an empty string clears it. Required.
The element’s updatedAt as last seen (microseconds since the epoch)
Responses
Section titled “Responses”Label updated successfully
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 - 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" }}No such element
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" }}Conflict - optimistic lock failure
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: a wrong type, an unknown set or position name, text over the limit, an index above 0, or an element that is not a rating question. details lists each field
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" }}