Update NPS settings

PUT

/nps/{id}/settings

curl --request PUT \
  --url https://app.surveyrock.com/api/v1/nps/example/settings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'If-Match: example' \
  --data '{ "settings": { "typeSettings": { "showLabels": true, "labelsCount": 1, "labelSets": {}, "activeLabelSet": "example", "recommendationSubject": "this company", "customSubject": "example" }, "responseValidation": { "isRequired": true } } }'

• API v1 endpoints

Update NPS element settings. A patch, checked exactly as updateElementSettings checks it (422 by location, 403 feature_locked for a plan-gated setting), and the element must be an NPS question (422 on elementId otherwise). NPS has no scale setting; its scale is always 0 to 10. 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

• bearerAuth
  elements:write

Parameters

Path Parameters

id

required

string

>= 16 characters <= 16 characters

NPS element ID

Header Parameters

If-Match

required

string

The element’s current ETag (from a read), or * to skip the check

Idempotency-Key

string

>= 1 characters <= 128 characters

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 Body^required

NPS settings update data

Media typeapplication/json

object

settings

required

object

typeSettings

object

showLabels

boolean

labelsCount

integer

Allowed values: 1 2 3

labelSets

Label texts by set name: {“default”: {“positions”: {“left”: “Not likely”, “center”: “Neutral”, “right”: “Very likely”}}}

object

activeLabelSet

string

recommendationSubject

string

nullable

Allowed values: this company this brand this product this service

customSubject

string

nullable

responseValidation

object

isRequired

boolean

Responses

200

Settings updated successfully

Media typeapplication/json

object

success

boolean

data

object

elementId

string

updatedAt

string format: date-time

settings

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": true,
  "meta": {
    "version": "3.0"
  }
}

Headers

ETag

string

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.

412

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).

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

428

The request has no If-Match header. Read the resource and send its ETag (error code precondition_required).

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