A valid request URL is required to generate request examples{
"survey": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"environment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "nps",
"question": "<string>",
"active": true,
"cooldown_days": 123,
"segment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"triggers": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "days_after_created",
"event_type": "<string>",
"days": 123,
"period": "month"
}
],
"created_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Update a survey
Requires engagement:manage. Partial: an omitted field keeps its value.
kind is immutable and sending a different one answers 422 — the scores already recorded were given on the old scale.
segment_id and triggers are the two where omitted and sent differ: omitting leaves them alone, null widens the survey to everybody, [] clears every trigger. Triggers are replaced as a set rather than edited one at a time, because they are the survey’s definition of when it fires and a partial edit across two calls would leave a window where it fires on a rule nobody chose.
Clearing the audience while a stored segment_entered trigger remains is refused: send triggers in the same call. A survey cannot move between environments, so a new segment_id is validated against the one it already lives in.
active: false is the off switch and it is reversible. It reaches further than the other modules’ do: an inactive survey is not delivered and its outstanding deliveries stop being pending, because a question you withdrew is not one your user still owes an answer to.
A valid request URL is required to generate request examples{
"survey": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"environment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "nps",
"question": "<string>",
"active": true,
"cooldown_days": 123,
"segment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"triggers": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "days_after_created",
"event_type": "<string>",
"days": 123,
"period": "month"
}
],
"created_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Authorizations
A staff session token, uk_st_…. Minted by sign-up, sign-in or the two-factor exchange. Only a 401 means it is spent; not_a_member (403) is about the organization named in X-Organization-Id and leaves the token good for the others.
Headers
The organization the caller is acting on — the org_… code that appears in the panel URL. It identifies; the membership JOIN is what authorizes, so a forged code reads nothing: the answer is not_a_member (403), which does not mean the session is over. Absent, the session's default organization answers, or — if that membership was revoked while the session was open — any other one the caller still holds.
Path Parameters
Body
3000 <= x <= 365null clears the audience — the survey applies to everybody.
Replaces the whole set. [] leaves the survey firing on nothing.
5Show child attributes
Show child attributes
Response
The survey as it now stands. triggers is present only when they were replaced.
One question, asked at a moment you chose, of an audience you already defined. kind decides what an answer means — nps has the fixed 0–10 scale the results screen computes a number from, custom is anything else — and it cannot change, because the scores already given were given on the old scale.
Show child attributes
Show child attributes