API Reference
Surveys API
REST API endpoints for listing surveys, reading responses, and managing survey sessions.
Last updated on
List surveys
GET /api/surveysQuery parameters:
| Parameter | Type | Description |
|---|---|---|
status | string | Filter by status: draft, published, archived |
page | number | Page number (default: 1) |
per_page | number | Results per page (default: 20, max: 100) |
Response:
{
"data": [
{
"id": "srv_abc123",
"name": "Reception Satisfaction Survey",
"status": "published",
"default_language": "en",
"current_version": 3,
"created_at": "2026-01-15T09:00:00Z",
"updated_at": "2026-05-20T14:30:00Z"
}
],
"meta": { "total": 12, "page": 1, "per_page": 20, "pages": 1 }
}Get survey
GET /api/surveys/:idReturns the full survey definition including all questions for the current published version.
List survey responses (sessions)
GET /api/survey-analytics/sessionsQuery parameters:
| Parameter | Type | Description |
|---|---|---|
survey_id | string | Required. Filter by survey |
from | ISO 8601 | Start of date range |
to | ISO 8601 | End of date range |
location_id | string | Filter by location |
status | string | completed, in_progress, expired |
page | number | Page number |
per_page | number | Max: 100 |
Response:
{
"data": [
{
"id": "ses_xyz789",
"survey_id": "srv_abc123",
"survey_version": 3,
"location_id": "loc_def456",
"status": "completed",
"language": "en",
"started_at": "2026-06-07T10:00:00Z",
"completed_at": "2026-06-07T10:01:23Z",
"duration_seconds": 83,
"answers": [
{ "question_id": "q1", "type": "rating", "value": 5 },
{ "question_id": "q2", "type": "text", "value": "Excellent service." }
]
}
],
"meta": { "total": 1402, "page": 1, "per_page": 20, "pages": 71 }
}Get survey analytics overview
GET /api/survey-analytics/overviewQuery parameters: survey_id (required), from, to, location_id, version
Response:
{
"survey_id": "srv_abc123",
"period": { "from": "2026-06-01T00:00:00Z", "to": "2026-06-07T23:59:59Z" },
"response_count": 247,
"completion_rate": 0.82,
"avg_duration_seconds": 67,
"nps": 42,
"csat": 0.88,
"per_question": [
{
"question_id": "q1",
"type": "rating",
"avg": 4.3,
"distribution": { "1": 3, "2": 8, "3": 21, "4": 89, "5": 126 }
}
]
}Deploy survey to location
POST /api/surveys/:id/deployRequest body:
{
"location_id": "loc_def456",
"template_id": "tpl_ghi789"
}Response: HTTP 201 with the created deployment object.
List survey templates
GET /api/surveys/presetsReturns available survey templates (NPS, CSAT, hygiene, employee satisfaction, etc.) that can be used as a starting point for new surveys.