Responses API

Endpoints

GET/surveys/:sid/responsesList responses for a survey

POST/surveys/:sid/responsesSubmit a response (public endpoint)

GET/responses/:idGet a single response

DELETE/responses/:idDelete a response (GDPR)

Response Object

{
  "id":               "resp_xxxx",
  "surveyId":         "survey_yyyy",
  "surveyVersionId":  "ver_zzzz",
  "completedAt":      "2024-11-14T10:45:00Z",
  "answers": [
    {
      "questionId": "q_1",
      "type":       "nps",
      "value":      9
    },
    {
      "questionId": "q_2",
      "type":       "short_text",
      "value":      "Great experience overall!"
    }
  ],
  "source": {
    "channel":    "sdk",
    "campaignId": null,
    "utmSource":  "email",
    "utmMedium":  null,
    "utmCampaign": null,
    "referrer":   null,
    "pageUrl":    null
  },
  "followUpContact": null
}

Submit a Response

This endpoint is public (no auth required) and intended for the survey renderer / SDK:

POST /surveys/:sid/responses

{
  "surveyVersionId": "ver_zzzz",
  "answers": [
    { "questionId": "q_1", "value": 9 },
    { "questionId": "q_2", "value": "Great!" }
  ],
  "source": {
    "channel": "link",
    "utmSource": "twitter"
  },
  "followUpContact": {
    "email": "user@example.com",
    "consent": true
  }
}

// 201 Created
{
  "id": "resp_xxxx",
  "redirectUrl": "https://your-app.com/thank-you"
}

List Responses

GET /surveys/:sid/responses?page=1&pageSize=50&status=completed

{
  "responses": [ ... ],
  "total": 312,
  "page": 1,
  "pageSize": 50
}

Query parameter	Description
`page`	1-based page number. Default `1`.
`pageSize`	Responses per page. Default `50`, maximum `200`.
`status`	`completed` returns only submitted responses. Without it, started-but-unfinished responses are included too.
`includeHidden`	`true` also returns responses hidden from results. Hidden responses are excluded by default.

Responses are returned newest first.

Analytics Aggregates

GET/surveys/:sid/analyticsAggregate statistics per question

GET /surveys/:sid/analytics

{
  "totalResponses": 312,
  "completionRate": 0.87,
  "averageCompletionTime": 142,
  "questions": [
    {
      "questionId": "q_1",
      "type": "nps",
      "npsScore": 42,
      "promoters": 120,
      "passives":  80,
      "detractors": 112
    }
  ]
}