Surveys

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.

API Reference

All Endpoints

Public survey response (recipient-facing)

Open the survey response page

Submit a survey response

​Public survey response (recipient-facing)

​Open the survey response page

​Submit a survey response

Public survey response (recipient-facing)

Open the survey response page

Submit a survey response