Update a distributor

PATCH

/distribution/{id}

curl --request PATCH \
  --url https://app.surveyrock.com/api/v1/distribution/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --header 'If-Match: example' \
  --data '{ "name": "example", "settings": {}, "scheduling": { "enable_at": "2031-01-01T09:00:00", "disable_at": "2031-02-01T09:00:00" } }'

• API v1 endpoints

Update a distributor. Send any of name (the distributor’s name), settings (merged into the stored settings: keys you leave out are kept, and a key nobody declared is a 400) and scheduling (enable_at and disable_at, as YYYY-MM-DDTHH:MM:SS, or null to clear). Sending none of them is a 422. 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
  distribution:write

Parameters

Path Parameters

id

required

string

Header Parameters

Idempotency-Key

required

string

>= 1 characters <= 128 characters

1 to 128 characters, chosen by the caller. 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

If-Match

required

string

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

Request Body^required

Media typeapplication/json

object

name

New name for the distributor

string

<= 255 characters

settings

Settings to merge into the stored ones

object

scheduling

object

enable_at

string

nullable

Example

2031-01-01T09:00:00

disable_at

string

nullable

Example

2031-02-01T09:00:00

Responses

200

Distributor updated

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.

400

A setting nobody declared, a redirect a respondent could not be sent to, or a malformed schedule

404

Distributor not found

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

422

Validation failed: an unknown field, an empty name, settings or scheduling that is not an object, or nothing to update

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