Surveys (REST)

Programmatic survey CRUD, analytics, and response export.

List surveys

GET /v1/apps/:appId/surveys

Returns every survey campaign in the standard data envelope, newest first.

Create

POST /v1/apps/:appId/surveys
 
{
  "name": "Onboarding NPS",
  "mode": "triggered",
  "status": "draft",
  "trigger": {
    "kind": "event",
    "eventName": "checkout_completed",
    "delaySeconds": 2,
    "occurrence": { "mode": "every" }
  },
  "flow": {
    "startQuestionId": "q1",
    "questions": [
      {
        "id": "q1",
        "type": "nps",
        "title": "How likely are you to recommend Acme?",
        "required": true
      }
    ],
    "branches": [],
    "progressStyle": "bar",
    "backNavigation": true
  }
}

mode is one of triggered, scheduled, on_demand, or link_only. Audience, schedule, frequency-cap, localization, branching, end-screen, and theme fields use the same canonical schemas as the dashboard composer.

Update

PATCH /v1/apps/:appId/surveys/:surveyId
 
{ "status": "active" }

Delete

DELETE /v1/apps/:appId/surveys/:surveyId

Permanently deletes the survey campaign and its dependent flow records. Use the status lifecycle (active, paused, completed, archived) when you need to stop delivery without deleting the survey.

Analytics

GET /v1/apps/:appId/surveys/:surveyId/analytics?from=2026-05-01&to=2026-05-31

{
  "data": {
    "surveyId": "sv_abc",
    "totals": {
      "started": 5201,
      "completed": 4840,
      "abandoned": 361,
      "completionRate": 0.93
    },
    "funnel": [],
    "perQuestion": []
  }
}

Responses

GET /v1/apps/:appId/surveys/:surveyId/responses?from=2026-05-01T00:00:00Z&to=2026-05-13T23:59:59Z&page=1&limit=200

Returns individual answer records with attemptId, campaignId, questionId, answerValue, and answeredAt. Use the recipients or attempts endpoints when you need subject and completion context around those answers.