Surveys API

Survey campaign management and response collection Base path: /api/v1/surveys Endpoint count: 14

title: “Public survey response endpoints (recipient-facing)” description: “Unauthenticated recipient-facing survey response endpoints, single-use token flow, hosted page, JSON submit, and 30-day link validity.”

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.

Open the survey response page

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

Recipient-facing landing page for a survey invitation. Verifies the signed token from the link, then renders a self-contained HTML page with a 0-10 score row and an optional comment box — or a thank-you page when the recipient has already answered. Unauthenticated; an invalid or expired token returns a 404 HTML page. Use it as the destination URL for NPS and CSAT survey links.

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/public/surveys/tkn_0c1d3e5f7a" \
  -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/tkn_0c1d3e5f7a', {
  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/tkn_0c1d3e5f7a", 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/tkn_0c1d3e5f7a", 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/tkn_0c1d3e5f7a')
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/tkn_0c1d3e5f7a');
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": {},
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

List all survey templates

GET /api/v1/surveys

List the tenant’s survey templates (NPS / CSAT / CES, SMS / WhatsApp / email / Viber / RCS / push), newest first, each with a sent_count and responded_count rollup. Paginate with ?limit= and &offset=; use it to pick the template to send or inspect. Read access: any authenticated role.

string (enum: true|false)

Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/surveys" \
  -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', {
  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", 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", 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')
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');
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": {},
  "meta": {}
}

Get a single survey template

GET /api/v1/surveys/{id}

Fetch one survey template by id, including its full multi-question definition (questions, options, skip-branch rules, conjoint / maxdiff designs) and per-locale translations map. Use it to render or edit a template before sending. 404 when the template does not exist for this tenant.

string

required

—

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", 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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", 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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3')
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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3');
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": {},
  "meta": {}
}

Benchmark this survey’s CSAT / NPS / CES score against industry-vertical peer percentiles — percentile rank, quartile rating, and delta vs the industry median. Pick the peer group with ?vertical=

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

string

required

—

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/benchmark" \
  -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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/benchmark', {
  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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/benchmark", 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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/benchmark", 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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/benchmark')
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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/benchmark');
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": {},
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

List contacts eligible for a reminder wave — sent this survey, not yet responded, stale for at least ?stale_hours= (default 24)

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

The CXaaS response-rate lever. A non-responder is a contact whose MOST RECENT send for this survey went out at least ?stale_hours= ago (default 24, matching the same-survey dedupe window) and who has recorded no response since — evaluated per-contact so an already-answered contact is never re-targeted. Returns the page plus a total count and the applied stale_hours. Paginate with ?limit= and &offset=.

string

required

—

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/non-responders" \
  -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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/non-responders', {
  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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/non-responders", 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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/non-responders", 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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/non-responders')
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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/non-responders');
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": {},
  "meta": {}
}

Aggregate survey rollup — avg score, NPS score, response rate

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

Aggregate scoring for one survey: total_sent, total_responded, response_rate, avg_score, nps_score (only for NPS templates, promoter% − detractor% over scored responses, rounded to one decimal), and a breakdown_by_score histogram. Use it as the headline metric for one program; for cohort breakout filter it with the VoC endpoint.

string

required

—

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/results" \
  -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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/results', {
  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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/results", 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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/results", 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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/results')
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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/results');
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": {},
  "meta": {}
}

Voice-of-Customer analytics over verbatim comments — sentiment, themes, drivers, NPS trend over time. Optionally scoped by channel / agent_id / team_id / segment_id for per-breakout scorecards

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

Voice-of-Customer text analytics over the survey’s free-text verbatim comments: lexicon sentiment distribution, theme / topic extraction, per-theme driver deltas vs overall, an NPS / score trend over time, and a capped set of sentiment-/theme-tagged verbatims (hard-capped at 5000 rows). Scope by ?granularity= plus channel / agent_id / team_id / segment_id for a per-breakout scorecard. Read-only.

string

required

—

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/voc" \
  -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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/voc', {
  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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/voc", 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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/voc", 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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/voc')
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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/voc');
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": {},
  "meta": {}
}

Queue- / agent-level CSAT / NPS scorecards across answered survey responses

GET /api/v1/surveys/scorecards

Post-conversation survey scorecards: buckets the tenant’s answered CSAT / NPS survey_responses by queue (call_logs.metadata->>‘queue_id’, joined via call_id) or by handled agent (survey_responses.agent_user_id) and returns one scorecard per bucket with responses, satisfaction_pct (top-2-box score >= 4), avg_score, csat_avg_score, and NPS (promoters − detractors over NPS rows). Narrow to one bucket with ?queue_id= / ?agent_user_id=; restrict survey type with ?survey_type=csat|nps; bound the window with ?from= / ?to=. Paginate with ?limit= / &offset=. Registered as a static route so it wins over /:id. Read access: any authenticated role.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/surveys/scorecards" \
  -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', {
  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", 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", 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')
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');
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": {},
  "meta": {}
}

Submit a survey response

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

Records a recipient’s answer to a survey link: a 0-10 score and/or a free-text comment, keyed off the signed token in the URL. Accepts either a JSON body or an HTML form post and is idempotent per link, so a repeat submission never double-counts. Unauthenticated; an invalid or expired token returns 403. JSON clients receive a { data, meta } envelope while HTML form posts receive a thank-you page.

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/public/surveys/tkn_0c1d3e5f7a/submit" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

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/tkn_0c1d3e5f7a/submit', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
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/tkn_0c1d3e5f7a/submit", headers=headers, json={})
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/tkn_0c1d3e5f7a/submit", bytes.NewBuffer([]byte(`{}`)))
	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/tkn_0c1d3e5f7a/submit')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.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/tkn_0c1d3e5f7a/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
{}
JSON);
echo curl_exec($ch);

{}

Create a survey template

POST /api/v1/surveys

Create a survey template: pick the metric type (nps / csat / ces), the 0–10 question copy, and the channels it can be delivered on. Optionally attach a multi-question definition (choice / matrix / open-text / ranking / conjoint / maxdiff, with skip-branch logic), a follow-up prompt, and per-locale translations. The template is inert until you send it; returns 201 with the created template. Requires owner / admin / developer.

string

Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/surveys" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

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', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
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/surveys", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/surveys", bytes.NewBuffer([]byte(`{}`)))
	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/surveys')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.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/surveys');
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
{}
JSON);
echo curl_exec($ch);

{
  "data": {},
  "meta": {}
}

Send a reminder wave to a survey’s non-responders (CXaaS response-rate lever) — re-dispatches through the same channel check, dedupe, and fatigue cap as the original send

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

The CXaaS response-rate lever. Resolve the same non-responder set GET /non-responders reports (optionally narrowed to contact_ids, up to 1000), then re-dispatch each through the same single-contact primitive the automation engine uses — so the wave inherits the channel check, 24h dedupe, and fatigue cap of the original send; anyone re-surveyed by a concurrent process simply comes back skipped. Returns sent / skipped / skipped_by_reason. Requires owner / admin / developer.

string

required

—

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/remind" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/remind', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
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/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/remind", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/remind", bytes.NewBuffer([]byte(`{}`)))
	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/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/remind')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.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/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/remind');
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
{}
JSON);
echo curl_exec($ch);

{
  "data": {},
  "meta": {}
}

Send a survey to an audience (contact, list, or segment)

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

Dispatch this survey to one of: a single contact (contact_id), an explicit list (contact_ids, up to 1000), or a dynamic segment (segment_id), on one of the template’s configured channels. Each recipient gets a signed landing URL and passes the 24h same-survey dedupe plus the configurable cross-survey fatigue cap (fatigue_window_hours, default 72; 0 disables). Hard-capped at 5000 contacts per call. Returns sent / skipped counts. Requires owner / admin / developer.

string

required

—

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/send" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/send', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
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/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/send", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/send", bytes.NewBuffer([]byte(`{}`)))
	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/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/send')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.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/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/send');
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
{}
JSON);
echo curl_exec($ch);

{
  "data": {},
  "meta": {}
}

Update a survey template

PATCH /api/v1/surveys/{id}

Patch a survey template — any of name, type, question, channels, follow_up_prompt, questions, default_locale, or translations; omitted fields stay unchanged. Pass at least one field or the request 400s; pass questions: null to collapse a multi-question survey back to the legacy single-question shape. A template-level edit only affects FUTURE sends. Requires owner / admin / developer.

string

required

—

string (enum: true|false)

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
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.patch("https://api.orbit.devotel.io/api/v1/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("PATCH", "https://api.orbit.devotel.io/api/v1/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", bytes.NewBuffer([]byte(`{}`)))
	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/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3')
req = Net::HTTP::Patch.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.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/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": {},
  "meta": {}
}

Delete a survey template

DELETE /api/v1/surveys/{id}

Delete a survey template. CASCADE removes every survey_responses row for it, so the results / VoC rollups stop being available immediately; use this only when the program is truly retired. Returns 204 with no body; 404 when the template does not exist. Requires owner / admin / developer.

string

required

—

string (enum: true|false)

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
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.delete("https://api.orbit.devotel.io/api/v1/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("DELETE", "https://api.orbit.devotel.io/api/v1/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", bytes.NewBuffer([]byte(`{}`)))
	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/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3')
req = Net::HTTP::Delete.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.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/surveys/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

Response: 204 No Content

API Reference

All Endpoints

Surveys API

Surveys API

title: “Public survey response endpoints (recipient-facing)” description: “Unauthenticated recipient-facing survey response endpoints, single-use token flow, hosted page, JSON submit, and 30-day link validity.”

Public survey response (recipient-facing)

Open the survey response page

Submit a survey response

Reminder waves for non-responders

List non-responders

Send a reminder wave

Post-conversation scorecards by queue or agent

Open the survey response page

List all survey templates

Get a single survey template

Benchmark this survey’s CSAT / NPS / CES score against industry-vertical peer percentiles — percentile rank, quartile rating, and delta vs the industry median. Pick the peer group with ?vertical=

List contacts eligible for a reminder wave — sent this survey, not yet responded, stale for at least ?stale_hours= (default 24)

Aggregate survey rollup — avg score, NPS score, response rate

Voice-of-Customer analytics over verbatim comments — sentiment, themes, drivers, NPS trend over time. Optionally scoped by channel / agent_id / team_id / segment_id for per-breakout scorecards

Queue- / agent-level CSAT / NPS scorecards across answered survey responses

Submit a survey response

Create a survey template

Send a reminder wave to a survey’s non-responders (CXaaS response-rate lever) — re-dispatches through the same channel check, dedupe, and fatigue cap as the original send

Send a survey to an audience (contact, list, or segment)

Update a survey template

Delete a survey template

​Surveys API

​title: “Public survey response endpoints (recipient-facing)” description: “Unauthenticated recipient-facing survey response endpoints, single-use token flow, hosted page, JSON submit, and 30-day link validity.”

​Public survey response (recipient-facing)

​Open the survey response page

​Submit a survey response

​Reminder waves for non-responders

​List non-responders

​Send a reminder wave

​Post-conversation scorecards by queue or agent

​Open the survey response page

​List all survey templates

​Get a single survey template

​Benchmark this survey’s CSAT / NPS / CES score against industry-vertical peer percentiles — percentile rank, quartile rating, and delta vs the industry median. Pick the peer group with ?vertical=

​List contacts eligible for a reminder wave — sent this survey, not yet responded, stale for at least ?stale_hours= (default 24)

​Aggregate survey rollup — avg score, NPS score, response rate

​Voice-of-Customer analytics over verbatim comments — sentiment, themes, drivers, NPS trend over time. Optionally scoped by channel / agent_id / team_id / segment_id for per-breakout scorecards

​Queue- / agent-level CSAT / NPS scorecards across answered survey responses

​Submit a survey response

​Create a survey template

​Send a reminder wave to a survey’s non-responders (CXaaS response-rate lever) — re-dispatches through the same channel check, dedupe, and fatigue cap as the original send

​Send a survey to an audience (contact, list, or segment)

​Update a survey template

​Delete a survey template

Surveys API

title: “Public survey response endpoints (recipient-facing)” description: “Unauthenticated recipient-facing survey response endpoints, single-use token flow, hosted page, JSON submit, and 30-day link validity.”

Public survey response (recipient-facing)

Open the survey response page

Submit a survey response

Reminder waves for non-responders

List non-responders

Send a reminder wave

Post-conversation scorecards by queue or agent

Open the survey response page

List all survey templates

Get a single survey template

Benchmark this survey’s CSAT / NPS / CES score against industry-vertical peer percentiles — percentile rank, quartile rating, and delta vs the industry median. Pick the peer group with ?vertical=

List contacts eligible for a reminder wave — sent this survey, not yet responded, stale for at least ?stale_hours= (default 24)

Aggregate survey rollup — avg score, NPS score, response rate

Voice-of-Customer analytics over verbatim comments — sentiment, themes, drivers, NPS trend over time. Optionally scoped by channel / agent_id / team_id / segment_id for per-breakout scorecards

Queue- / agent-level CSAT / NPS scorecards across answered survey responses

Submit a survey response

Create a survey template

Send a reminder wave to a survey’s non-responders (CXaaS response-rate lever) — re-dispatches through the same channel check, dedupe, and fatigue cap as the original send

Send a survey to an audience (contact, list, or segment)

Update a survey template

Delete a survey template