Surveys API

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

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.

List all survey templates

GET /api/v1/surveys/

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": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Get a single survey template

GET /api/v1/surveys/{id}

string

required

—

cURL

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

string

required

—

cURL

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

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

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

string

required

—

cURL

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

Voice-of-Customer analytics over verbatim comments — sentiment, themes, drivers, NPS trend over time

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

string

required

—

cURL

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

Create a survey template

POST /api/v1/surveys/

string

required

Human-readable name for this survey template (1–200 characters).

string (enum: nps|csat|ces)

Survey type; sets the scoring formula and prompt wording. Defaults to nps.

string

required

The question presented to recipients (1–500 characters).

string (enum: sms|whatsapp|email|viber|rcs)[]

required

One to five delivery channels the survey can be sent through.

string | null

Optional open-ended prompt asked after the score to capture a verbatim comment.

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 '{
  "name": "Post-purchase NPS",
  "type": "nps",
  "question": "How likely are you to recommend us to a friend or colleague?",
  "channels": [
    "sms",
    "email"
  ],
  "follow_up_prompt": "What is the main reason for your score?"
}'

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({
  "name": "Post-purchase NPS",
  "type": "nps",
  "question": "How likely are you to recommend us to a friend or colleague?",
  "channels": [
    "sms",
    "email"
  ],
  "follow_up_prompt": "What is the main reason for your score?"
}),
})
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={
  "name": "Post-purchase NPS",
  "type": "nps",
  "question": "How likely are you to recommend us to a friend or colleague?",
  "channels": [
    "sms",
    "email"
  ],
  "follow_up_prompt": "What is the main reason for your score?"
})
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(`{
  "name": "Post-purchase NPS",
  "type": "nps",
  "question": "How likely are you to recommend us to a friend or colleague?",
  "channels": [
    "sms",
    "email"
  ],
  "follow_up_prompt": "What is the main reason for your score?"
}`)))
	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 = {
  "name": "Post-purchase NPS",
  "type": "nps",
  "question": "How likely are you to recommend us to a friend or colleague?",
  "channels": [
    "sms",
    "email"
  ],
  "follow_up_prompt": "What is the main reason for your score?"
}.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
{
  "name": "Post-purchase NPS",
  "type": "nps",
  "question": "How likely are you to recommend us to a friend or colleague?",
  "channels": [
    "sms",
    "email"
  ],
  "follow_up_prompt": "What is the main reason for your score?"
}
JSON);
echo curl_exec($ch);

{
  "data": {},
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

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

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/surveys/{id}/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/{id}/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/{id}/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/{id}/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/{id}/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/{id}/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": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

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

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

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/surveys/{id}/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/{id}/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/{id}/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/{id}/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/{id}/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/{id}/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": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Update a survey template

PATCH /api/v1/surveys/{id}

string

required

—

cURL

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

Delete a survey template

DELETE /api/v1/surveys/{id}

string

required

—

cURL

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

{
  "data": {
    "ok": true
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

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

List all survey templates

Get a single survey template

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

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

​List all survey templates

​Get a single survey template

​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

​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

List all survey templates

Get a single survey template

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

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