Public survey response (recipient-facing)

These two endpoints power the page a recipient lands on when they open a survey link. They are unauthenticated — the request carries no API key. Access is granted by the single-use token embedded in the link, so you never expose your API key to end users. The token is minted when you send a survey with POST /api/v1/surveys/{id}/send and is baked into the SMS, email, WhatsApp, RCS, or Viber message each recipient receives. Tokens are valid for 30 days. Most teams let recipients use the hosted page below; the JSON form of the submit endpoint is there for when you render your own response UI.

Do not send an X-API-Key header to these endpoints, and do not build the token yourself — always use the link returned by the send endpoint. Both endpoints are rate-limited to 10 requests per minute per IP.

Open the survey response page

GET /api/v1/public/surveys/{token}

string

required

The signed token from the survey link. An invalid or expired token returns a 404 page rather than revealing whether a survey exists.

Returns a self-contained HTML page with a 0–10 rating scale and, when the survey defines a follow-up prompt, a comment box. If the recipient has already answered, the page shows their recorded score instead of the form. The response is served with Cache-Control: private, no-store, so shared links are never cached.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/public/surveys/{token}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/public/surveys/{token}', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/public/surveys/{token}", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/public/surveys/{token}", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/public/surveys/{token}')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/public/surveys/{token}');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

Submit a survey response

POST /api/v1/public/surveys/{token}/submit

string

required

The signed token from the survey link.

integer

The rating, 0–10. Optional when a comment is provided.

string

A free-text comment, up to 2000 characters. Optional when a score is provided.

Send at least one of score or comment; a request with neither is rejected. The endpoint accepts either a JSON body or a standard application/x-www-form-urlencoded form post, so the hosted page and your own integration share the same route. Submitting again with the same token is safe — the first answer is kept and never double-counted. Set Accept: application/json to receive a JSON envelope; otherwise the endpoint returns an HTML thank-you page for browser form posts.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/public/surveys/{token}/submit" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "score": 9,
  "comment": "Fast and friendly support."
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/public/surveys/{token}/submit', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "score": 9,
  "comment": "Fast and friendly support."
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/public/surveys/{token}/submit", headers=headers, json={
  "score": 9,
  "comment": "Fast and friendly support."
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/public/surveys/{token}/submit", bytes.NewBuffer([]byte(`{
  "score": 9,
  "comment": "Fast and friendly support."
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/public/surveys/{token}/submit')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "score": 9,
  "comment": "Fast and friendly support."
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/public/surveys/{token}/submit');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "score": 9,
  "comment": "Fast and friendly support."
}
JSON);
echo curl_exec($ch);

{
  "data": { "ok": true },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-07-03T00:00:00.000Z"
  }
}

Errors

Status	Code	When
`400`	`EMPTY_SUBMISSION`	Neither `score` nor `comment` was provided.
`400`	`VALIDATION_ERROR`	`score` is outside `0`–`10`, or `comment` exceeds 2000 characters.
`403`	`INVALID_TOKEN`	The token is malformed or has expired.

Reminder waves for non-responders

A survey’s response rate is set by what happens after the first send. Two endpoints close that loop: one lists the contacts who have not answered yet, and one re-sends the survey to them. This is safer than manually re-sending to a stale audience. A contact counts as a non-responder only while their latest send is unanswered — the moment they reply (from any earlier link), they drop out of the list and out of every future wave. Each reminder then runs through the same delivery guardrails as the original send — if a contact was already re-sent the survey (by a concurrent wave, an automation, or a manual resend) inside the 24-hour dedupe window, they come back skipped, never double-sent.

List non-responders

GET /api/v1/surveys/{id}/non-responders

string

required

The survey template id.

integer

How old a contact’s most recent send must be before they surface — defaults to 24. Ranges 1–8760. Bad values fall back to the default rather than erroring, so the list stays loadable.

integer

Page size, 1–200, default 50.

integer

Pagination offset, default 0.

Returns the current non-responders for the survey — each with its contact id, the channel of the contact’s latest send, and that send’s timestamp — plus a total for the full list, so you can show “203 contacts still out” while rendering the first page.

Send a reminder wave

POST /api/v1/surveys/{id}/remind

string

required

The survey template id.

integer

Only contacts whose latest send is at least this old join the wave — default 24, range 1–8760.

array of strings

Restrict the wave to this subset of non-responders (max 1,000). Omit to wave at everyone GET /non-responders would currently list.

integer

Override the cross-survey fatigue cap for this wave (default 72 hours at platform level). Pass 0 to disable cross-survey fatigue capping for this wave.

Responds with requested, sent, and skipped counts — plus a skipped_by_reason breakdown (for example, deduped when the 24-hour same-survey recency check still guards the contact). When nobody is eligible yet, the response is { "requested": 0, "sent": 0, "skipped": 0, "reason": "no_non_responders" }. Every reminder re-uses the channel the contact’s last send used, so a WhatsApp non-responder is chased on WhatsApp, an email non-responder on email. The wave is also auditable — each POST /remind call is written to the audit log with the requested / sent / skipped totals.

Post-conversation scorecards by queue or agent

Post-conversation surveys (the auto-CSAT/NPS close-triggered dispatch and the post-call IVR captures) collect scores per interaction. GET /api/v1/surveys/scorecards rolls the answered responses up into one scorecard per queue (?group_by=queue, the default) or per handling agent (?group_by=agent), so a supervisor can compare teams and agents on the same headline metrics.

GET /api/v1/surveys/scorecards

string

queue (default) buckets by the queue that handled the interaction; agent buckets by the handling agent.

string

csat, nps, or all (default). Restrict the rollup to one metric.

string

Narrow to one queue bucket (with group_by=queue).

string

Narrow to one agent bucket (with group_by=agent).

string

ISO timestamp window lower bound. Only answered responses count.

string

ISO timestamp window upper bound.

integer

Page size, 1–200 (default 50). A bucket with zero answers drops out entirely.

integer

Pagination offset, default 0.

Each row carries responses, satisfied_count, satisfaction_pct (share at score 4–5, the top-two-box), avg_score, csat_avg_score, and nps (promoters minus detractors, over NPS rows only) plus nps_responses. CSAT and NPS averages are kept independent — a blended mean across the two scales is meaningless.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/surveys/scorecards?group_by=queue&survey_type=all&from=2026-08-01T00:00:00Z" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/surveys/scorecards?group_by=queue&survey_type=all&from=2026-08-01T00:00:00Z', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/surveys/scorecards?group_by=queue&survey_type=all&from=2026-08-01T00:00:00Z", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/surveys/scorecards?group_by=queue&survey_type=all&from=2026-08-01T00:00:00Z", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/surveys/scorecards?group_by=queue&survey_type=all&from=2026-08-01T00:00:00Z')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/surveys/scorecards?group_by=queue&survey_type=all&from=2026-08-01T00:00:00Z');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "group_by": "queue",
    "survey_type": "all",
    "scorecards": [
      {
        "key": "q_support_tier1",
        "responses": 148,
        "satisfied_count": 121,
        "satisfaction_pct": 82,
        "avg_score": 4.31,
        "csat_avg_score": 4.31,
        "nps": 42,
        "nps_responses": 96
      }
    ],
    "pagination": { "limit": 50, "offset": 0 }
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-08-28T00:00:00Z"
  }
}

Unanswered sends never distort the numbers: a queue or agent bucket appears only once it has at least one answered response, so sampled-off or not-yet-answered sends never surface as zero-response rows.

Worked response envelopes (per operation)

The envelopes below are the response contracts for the individual survey operations the generated page enumerates. Each is hand-authored against the real reply shape the route returns — use them as the integration target for the matching <Note> route. For the full VoC playbook (sentiment, themes, drivers, and the NPS trend over time), see guides/surveys-voc.mdx.

List all survey templates

GET /api/v1/surveys

{
  "data": [
    {
      "id": "surv_4f8c1a2b3c4d5e6f7a8b9c0d",
      "name": "Post-call CSAT (Tier 1)",
      "type": "csat",
      "channel": "sms",
      "status": "active",
      "sent_count": 1284,
      "responded_count": 1041,
      "created_at": "2026-09-04T14:22:10.000Z",
      "updated_at": "2026-10-02T09:11:32.000Z"
    },
    {
      "id": "surv_9a7b6c5d4e3f2a1b0c9d8e7f",
      "name": "Quarterly NPS",
      "type": "nps",
      "channel": "email",
      "status": "active",
      "sent_count": 4202,
      "responded_count": 1187,
      "created_at": "2026-07-18T11:00:00.000Z",
      "updated_at": "2026-07-18T11:00:00.000Z"
    }
  ],
  "meta": {
    "limit": 50,
    "offset": 0,
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-10-09T12:00:00.000Z"
  }
}

Get a single survey template

GET /api/v1/surveys/{id}

{
  "data": {
    "id": "surv_4f8c1a2b3c4d5e6f7a8b9c0d",
    "name": "Post-call CSAT (Tier 1)",
    "type": "csat",
    "channel": "sms",
    "status": "active",
    "welcome_prompt": "How did we do today? Reply with a score from 0 to 10.",
    "questions": [
      {
        "id": "q_score",
        "kind": "scale",
        "min": 0,
        "max": 10,
        "label": "Overall satisfaction"
      },
      {
        "id": "q_comment",
        "kind": "free_text",
        "label": "What could we do better?",
        "max_length": 2000
      }
    ],
    "sent_count": 1284,
    "responded_count": 1041,
    "created_at": "2026-09-04T14:22:10.000Z",
    "updated_at": "2026-10-02T09:11:32.000Z"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-10-09T12:00:00.000Z"
  }
}

Create a survey template

POST /api/v1/surveys

{
  "data": {
    "id": "surv_4f8c1a2b3c4d5e6f7a8b9c0d",
    "name": "Post-call CSAT (Tier 1)",
    "type": "csat",
    "channel": "sms",
    "status": "active",
    "questions": [
      {
        "id": "q_score",
        "kind": "scale",
        "min": 0,
        "max": 10,
        "label": "Overall satisfaction"
      }
    ],
    "created_at": "2026-09-04T14:22:10.000Z",
    "updated_at": "2026-09-04T14:22:10.000Z"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-04T14:22:10.000Z"
  }
}

Update a survey template

PATCH /api/v1/surveys/{id}

{
  "data": {
    "id": "surv_4f8c1a2b3c4d5e6f7a8b9c0d",
    "name": "Post-call CSAT (Tier 1, v2)",
    "type": "csat",
    "channel": "sms",
    "status": "active",
    "welcome_prompt": "How did we do? Reply 0 (bad) to 10 (great).",
    "updated_at": "2026-10-09T13:05:44.000Z"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-10-09T13:05:44.000Z"
  }
}

Delete a survey template

DELETE /api/v1/surveys/{id}

Returns 204 No Content with an empty body. A successful delete carries no JSON envelope — the response is the status alone. A 404 is returned when the template does not exist.

List non-responders

GET /api/v1/surveys/{id}/non-responders

{
  "data": [
    {
      "contact_id": "ctc_2b1a9f8e7d6c5b4a3c2d1e0f",
      "channel": "sms",
      "last_sent_at": "2026-10-08T08:15:00.000Z"
    },
    {
      "contact_id": "ctc_7c6b5a4d3e2f1c0b9a8d7e6f",
      "channel": "email",
      "last_sent_at": "2026-10-08T08:15:02.000Z"
    }
  ],
  "meta": {
    "total": 203,
    "limit": 50,
    "offset": 0,
    "stale_hours": 24,
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-10-09T12:00:00.000Z"
  }
}

Send a reminder wave

POST /api/v1/surveys/{id}/remind

{
  "data": {
    "requested": 203,
    "sent": 189,
    "skipped": 14,
    "skipped_by_reason": {
      "deduped": 11,
      "fatigue_capped": 3
    }
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-10-09T12:00:00.000Z"
  }
}

When nobody is eligible yet, the same shape returns { "requested": 0, "sent": 0, "skipped": 0, "reason": "no_non_responders" } under data.

Send a survey to an audience

POST /api/v1/surveys/{id}/send

{
  "data": {
    "send_id": "snd_3f2e1d0c9b8a7f6e5d4c3b2a",
    "survey_id": "surv_4f8c1a2b3c4d5e6f7a8b9c0d",
    "audience": "list_lst_8c1a2b3c4d5e6f7a8b9c0d1e",
    "dispatched": 1240,
    "skipped": 44,
    "skipped_by_reason": {
      "deduped": 40,
      "fatigue_capped": 4
    }
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-10-09T12:00:00.000Z"
  }
}

Aggregate rollup

GET /api/v1/surveys/{id}/results

{
  "data": {
    "survey_id": "surv_4f8c1a2b3c4d5e6f7a8b9c0d",
    "sent_count": 1284,
    "responded_count": 1041,
    "response_rate": 81.1,
    "avg_score": 8.4,
    "nps": 52,
    "nps_responses": 1041
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-10-09T12:00:00.000Z"
  }
}

Voice-of-Customer analytics

GET /api/v1/surveys/{id}/voc

{
  "data": {
    "survey_id": "surv_4f8c1a2b3c4d5e6f7a8b9c0d",
    "sentiment": {
      "positive": 0.62,
      "neutral": 0.24,
      "negative": 0.14,
      "net": 0.48
    },
    "themes": [
      { "label": "speed of resolution", "mentions": 318, "sentiment": 0.71 },
      { "label": "agent friendliness", "mentions": 263, "sentiment": 0.78 },
      { "label": "callback wait time", "mentions": 97, "sentiment": -0.22 }
    ],
    "drivers": [
      { "label": "first-response time", "impact": 0.41 },
      { "label": "resolution completeness", "impact": 0.33 }
    ],
    "nps_trend": [
      { "period": "2026-09", "nps": 48, "responses": 412 },
      { "period": "2026-10", "nps": 52, "responses": 629 }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-10-09T12:00:00.000Z"
  }
}

Benchmark percentiles

GET /api/v1/surveys/{id}/benchmark

{
  "data": {
    "survey_id": "surv_4f8c1a2b3c4d5e6f7a8b9c0d",
    "vertical": "telecom",
    "metrics": {
      "csat": {
        "score": 4.31,
        "percentile_rank": 74,
        "quartile": "top",
        "median": 4.05,
        "delta_vs_median": 0.26
      },
      "nps": {
        "score": 52,
        "percentile_rank": 68,
        "quartile": "upper",
        "median": 44,
        "delta_vs_median": 8
      }
    }
  },
  "meta": {
    "vertical": "telecom",
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-10-09T12:00:00.000Z"
  }
}

The ?vertical= query parameter picks the peer group (for example, ?vertical=telecom, ?vertical=retail, ?vertical=saas); the chosen group echoes back in meta.vertical so the response is self-describing.

Validation errors worth branching on

Survey writes validate the body before any row is read. A failed validation returns 422 VALIDATION_ERROR with error.details.issues listing each rejected field, so you can name the exact field to fix instead of resending the same body:

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "status": 422,
    "message": "Invalid survey payload",
    "details": {
      "issues": [
        {
          "field": "score_scale",
          "message": "Invalid enum value. Expected '0_10' | '1_5' | 'nps', received '0_100'"
        }
      ]
    }
  },
  "meta": {
    "request_id": "req_survey_err_422",
    "timestamp": "2026-09-12T10:32:44Z"
  }
}

Branch on error.details.issues[].field, fix that field, and resend intentionally — a blind retry of the same body repeats the 422. For the worked end-to-end failure flows these branches plug into, see the error handling guide.

API Reference

All Endpoints

Public survey response endpoints (recipient-facing)

Public survey response (recipient-facing)

Open the survey response page