Surveys API

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

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}

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 "https://api.orbit.devotel.io/api/v1/public/surveys/{token}"

Submit a survey response

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

token

string

required

The signed token from the survey link.

score

integer

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

comment

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 "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "score": 9, "comment": "Fast and friendly support." }'

Node.js

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

Python

import requests

r = requests.post(
    "https://api.orbit.devotel.io/api/v1/public/surveys/{token}/submit",
    headers={"Accept": "application/json"},
    json={"score": 9, "comment": "Fast and friendly support."},
)
print(r.json())

{
  "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.

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-sdk'

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);

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-sdk'

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);

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-sdk'

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);

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-sdk'

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);

Create a survey template

POST /api/v1/surveys/

name

string

required

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

type

string (enum: nps|csat|ces)

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

question

string

required

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

channels

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

required

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

follow_up_prompt

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-sdk'

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);

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-sdk'

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);

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-sdk'

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);

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-sdk'

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);

API Reference

All Endpoints

Surveys API

Surveys API

Public survey response (recipient-facing)

Open the survey response page

Submit a survey response

List all survey templates

Get a single survey template

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 survey to an audience (contact, list, or segment)

Update a survey template

Delete a survey template

​Surveys API

​Public survey response (recipient-facing)

​Open the survey response page

​Submit a survey response

​List all survey templates

​Get a single survey template

​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 survey to an audience (contact, list, or segment)

​Update a survey template

​Delete a survey template

Surveys API

Public survey response (recipient-facing)

Open the survey response page

Submit a survey response

List all survey templates

Get a single survey template

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 survey to an audience (contact, list, or segment)

Update a survey template

Delete a survey template