Surveys

Collect responses from subscribers through inbound keyword-triggered SMS conversations.

A survey has a keyword that triggers it, a sequence of questions, and a target (broadcast to contact groups, or keyword-activated). Endpoints in this section require the surveys scope.

This page covers the survey lifecycle and the controls that move a survey between states. For reading answers and testing flows, see Survey responses.

Lifecycle

A survey moves through these states:

Status	Description
draft	Created. Questions can be added and edited. Not yet activated.
active	Accepting responses. The keyword is live on the shortcode.
paused	Temporarily halted. No new sessions are started.
completed	Ended, past the end date or the max responses count was reached.
cancelled	Manually stopped.

List questions

Fetch the ordered questions for a survey. Use this to confirm the flow before you activate.

GET/api/v1/surveys/{uuid}/questions

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

Activate a survey

Activation moves the survey from draft to active. For broadcast-type surveys, provide the contact group UUIDs that should receive the welcome message and first question. Keyword-triggered surveys need no groups.

POST/api/v1/surveys/{uuid}/activate

Parameters

group_ids

string[]

For broadcast surveys, contact group UUIDs to send the welcome message to.

sender_id

string

Override the sender ID for the broadcast send.

Keyword survey, no groups needed:

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

Broadcast survey, sends the welcome message plus the first question to groups:

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

Pause, resume, cancel

Pause halts a survey without ending it, resume returns it to active, and cancel stops it for good.

POST/api/v1/surveys/{uuid}/pause

POST/api/v1/surveys/{uuid}/resume

POST/api/v1/surveys/{uuid}/cancel

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

200: Paused

{
  "success": true,
  "data": {
    "uuid": "srv-uuid",
    "status": "paused"
  }
}

Cancel is final

Cancelling sets the survey to cancelled and it cannot be resumed. Use pause when you only need to hold responses temporarily.

Read Survey responses to list sessions, pull transcripts, export answers, and simulate the inbound flow.