A valid request URL is required to generate request examples{
"survey_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "nps",
"delivered": 123,
"responses": 123,
"scored": 123,
"promoters": 123,
"passives": 123,
"detractors": 123,
"score": 123,
"trend": [
{
"week": "2023-12-25",
"scored": 123,
"promoters": 123,
"detractors": 123,
"score": 123
}
],
"verbatims": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"email": "<string>",
"name": "<string>",
"score": 123,
"comment": "<string>",
"created_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"
}
}Survey results
Requires engagement:manage. The score, the trend and the verbatims.
score is null when nobody has given one, never 0. Zero is a real NPS — as many detractors as promoters — and it is a number somebody would act on, so an empty survey must not report it. The buckets are the standard cut: 9–10 promoters, 7–8 passives, 0–6 detractors, and scored is the denominator, counting answers that carry a score rather than answers (a custom survey answered with a sentence alone is not part of a rate it never entered).
delivered is how many people were asked, which is the denominator of your response rate and is not the same as your audience: the cooldown means somebody in the segment may simply not have been asked yet.
trend is by UTC week over the last 180 days. Weeks rather than days because a survey answered by a dozen people a day makes a daily line that is noise.
verbatims is the 100 most recent answers with who gave them — a score without the sentence beside it is a number nobody can act on.
A valid request URL is required to generate request examples{
"survey_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "nps",
"delivered": 123,
"responses": 123,
"scored": 123,
"promoters": 123,
"passives": 123,
"detractors": 123,
"score": 123,
"trend": [
{
"week": "2023-12-25",
"scored": 123,
"promoters": 123,
"detractors": 123,
"score": 123
}
],
"verbatims": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"email": "<string>",
"name": "<string>",
"score": 123,
"comment": "<string>",
"created_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.
Path Parameters
Response
The results.
nps, custom How many people were asked.
Answers carrying a score — the denominator.
Promoters minus detractors over scored, as a percentage. null when nobody has scored — never 0, which is a real result.
Show child attributes
Show child attributes
Show child attributes
Show child attributes