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"
}
}Write a survey
Requires engagement:manage.
kind is nps or custom and cannot be changed afterwards: the scores already recorded were given on the old scale, so an edit would leave one series measured two ways with nothing in the data saying where. nps is the one question with a fixed scale (0–10) and a fixed arithmetic, which is why the results screen can compute a number from it.
active defaults to false: a survey exists while its triggers are being written, and creating one never starts asking anybody.
segment_id is who it is for, or null for everybody, and it must name a segment of the same environment — the audience your flags and changelog posts already use, never a filter of its own.
cooldown_days (default 7) is how long this survey’s delivery closes the door on any survey for that person. The window is per contact rather than per survey, which is the whole promise: three surveys each asking once a day would each be inside their own limit.
triggers is when it fires, replaced as a set on every write. See the SurveyTrigger schema for the three kinds.
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"
}
}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.
Query Parameters
Which environment to act in. A view parameter, valid only on the staff surface — a machine credential never chooses its environment, it is resolved from the key.
live, test Body
nps, custom 3000 <= x <= 365The audience, or null for everybody. Must belong to the same environment.
5Show child attributes
Show child attributes
Response
The survey, with its triggers.
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