Survey responses

List response sessions, read transcripts, export answers, and simulate the inbound flow.

Each subscriber who engages a survey produces a session, an ordered exchange of questions and answers. These endpoints require the surveys scope. For creating and controlling surveys, see Surveys.

List response sessions

Fetch the response sessions for a survey, with optional filters.

GET/api/v1/surveys/{uuid}/responses/sessions

Query params

status

string

Filter by session status (active | completed | expired | abandoned).

msisdn

string

Filter by respondent phone.

page

integer

Page number.

page_size

integer

Results per page.

curl -X GET "https://timisha-solutions-api.salamu.co.ke/api/v1/surveys/srv-uuid/responses/sessions?status=completed" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Get a session transcript

Return the full question-and-answer exchange for a single session.

GET/api/v1/surveys/{uuid}/responses/sessions/{session_uuid}/transcript

curl -X GET "https://timisha-solutions-api.salamu.co.ke/api/v1/surveys/srv-uuid/responses/sessions/sess-uuid/transcript" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Export all transcripts

Download a CSV file with all responses across every session, suitable for bulk analysis.

GET/api/v1/surveys/{uuid}/responses/transcripts/export

curl -X GET "https://timisha-solutions-api.salamu.co.ke/api/v1/surveys/srv-uuid/responses/transcripts/export" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

CSV, not JSON

This endpoint streams a CSV attachment rather than the usual JSON envelope. Save the body to a file instead of parsing it as JSON.

Simulate a session

Drive the full inbound SMS flow from your API client, without a real phone. Start a simulation to receive the first question, then submit answers to advance through the survey.

POST/api/v1/surveys/{uuid}/simulatestarts session

POST/api/v1/surveys/{uuid}/simulate/respondsends a response

Start a simulation

Returns a simulation session ID and the first question.

curl -X POST "https://timisha-solutions-api.salamu.co.ke/api/v1/surveys/srv-uuid/simulate" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Submit a response

Returns the next question, or the completion message when the survey ends.

Parameters

session_idreq

string

The simulation session ID returned when the simulation started.

responsereq

string

The answer to the current question.

curl -X POST "https://timisha-solutions-api.salamu.co.ke/api/v1/surveys/srv-uuid/simulate/respond" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "session_id": "sim-session-uuid",
  "response": "3"
}'

200: Next question

{
  "success": true,
  "data": {
    "session_id": "sim-session-uuid",
    "next_question": "What can we improve? Reply with your suggestion.",
    "completed": false
  }
}

Test before you activate

Simulate the whole flow against a draft survey to verify question order and wording, then activate it when it reads correctly.