TickOS
Resources

Surveys

.md

Read customer satisfaction (CSAT) survey results and stats.

Surveys capture customer satisfaction after a ticket is resolved. TickOS sends a short survey (star rating + optional questions and comment) and records the response. The API is read-only: surveys are configured and sent from the dashboard, and you query their results here.

List survey responsesGET/v1/surveys

Permission: read. Returns surveys newest first (by created_at), with their rating and the linked customer and ticket. Supports standard pagination (limit, offset). The list is returned under the surveys key, not data. An invalid status or a rating outside 1-5 returns 400.

Query paramTypeDescription
inbox_idstringFilter by inbox.
statusstringpending, sending, sent, responded, expired or cancelled.
ratingnumberFilter by star rating (1-5).
customer_idstringFilter by customer.
ticket_idstringFilter by ticket.
fromstringISO 8601 lower bound (created_at).
tostringISO 8601 upper bound (created_at).
limitnumberPage size (max 100, default 50).
offsetnumberPagination offset.
response.json
JSON
01{
02  "surveys": [
03    {
04      "id": "srv_xxxxxxxx",
05      "ticket_id": "tck-xxxxxxxx",
06      "customer_id": "cst-xxxxxxxx",
07      "inbox_id": "inb_xxxxxxxx",
08      "status": "responded",
09      "rating": 5,
10      "answered_question": true,
11      "communication_clear": true,
12      "comment": "Fast and helpful, thanks!",
13      "scheduled_at": "2026-07-10T12:00:00Z",
14      "sent_at": "2026-07-10T12:01:00Z",
15      "responded_at": "2026-07-10T13:20:00Z",
16      "created_at": "2026-07-10T11:59:00Z",
17      "customer": { "id": "cst-xxxxxxxx", "name": "Jane Doe", "email": "jane@example.com" },
18      "ticket": { "id": "tck-xxxxxxxx", "client_id": "SUP-00042", "subject": "Cannot access my account" }
19    }
20  ],
21  "pagination": { "total": 128, "limit": 50, "offset": 0 }
22}
UTF-8 · LF · JSONtickos.dev

Survey statisticsGET/v1/surveys/stats

Permission: read. Returns aggregated CSAT metrics in the response root (no data wrapper). Optionally filter with inbox_id, from and to (ISO 8601 bounds on created_at). Rates are percentages from 0 to 100 rounded to 2 decimals, and are null when there is nothing to compute them from.

FieldTypeDescription
total_sentnumberSurveys that were delivered: status sent, responded or expired.
total_respondednumberSurveys with status responded.
response_ratenumber | nulltotal_responded / total_sent as a percentage (0-100, 2 decimals). null when total_sent is 0.
average_ratingnumber | nullMean star rating across responded surveys (1-5, 2 decimals). null when there are no ratings.
rating_distributionobjectCount of responses per star: { "1": n, ..., "5": n }.
answered_question_yes_ratenumber | nullPercentage (0-100) of "yes" among responded surveys that answered this question. null when none answered it.
communication_clear_yes_ratenumber | nullPercentage (0-100) of "yes" among responded surveys that answered this question. null when none answered it.
by_statusobjectCounts per status: pending, sending, sent, responded, expired, cancelled.
response.json
JSON
01{
02  "total_sent": 120,
03  "total_responded": 48,
04  "response_rate": 40,
05  "average_rating": 4.38,
06  "rating_distribution": { "1": 1, "2": 2, "3": 4, "4": 10, "5": 31 },
07  "answered_question_yes_rate": 91.67,
08  "communication_clear_yes_rate": 95.83,
09  "by_status": { "pending": 3, "sending": 0, "sent": 60, "responded": 48, "expired": 12, "cancelled": 2 }
10}
UTF-8 · LF · JSONtickos.dev
terminal
Bash
01curl "https://api.tickos.dev/v1/surveys/stats?inbox_id=inb_xxx&from=2026-07-01" \
02  -H 'Authorization: Bearer sk_your_api_key'
UTF-8 · LF · Bashtickos.dev
PreviousUsers & membersNext API keys