Smart Surveys

Smart Surveys use AI to create conversational survey experiences that adapt in real-time based on respondent answers. Instead of static question lists, Smart Surveys generate contextual follow-up questions to explore topics more deeply.

How It Works

1. Create a Smart Session

Start by creating a session with your survey's objectives:

POST /api/v1/surveys/{surveyId}/smart-sessions
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "respondentId": "resp_abc123",      // Optional: link to known respondent
  "metadata": {                       // Optional: pass to AI for context
    "department": "Engineering",
    "tenure": "2 years"
  }
}

// Response
{
  "data": {
    "sessionId": "ss_xyz789",
    "surveyId": "srv_abc123",
    "status": "active",
    "currentQuestion": {
      "id": "q_001",
      "text": "How would you describe your overall experience working here?",
      "type": "open_text",
      "isGenerated": true
    },
    "questionCount": 1,
    "maxQuestions": 10,
    "createdAt": "2026-02-04T10:00:00Z"
  }
}

2. Submit Response & Get Next Question

After the respondent answers, submit the response to receive the next AI-generated question:

POST /api/v1/surveys/{surveyId}/smart-sessions/{sessionId}/respond
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "questionId": "q_001",
  "answer": "Overall it's been positive, though I sometimes feel disconnected from other teams."
}

// Response
{
  "data": {
    "sessionId": "ss_xyz789",
    "status": "active",
    "responseRecorded": {
      "questionId": "q_001",
      "sentiment": "mixed",           // positive | negative | neutral | mixed
      "themes": ["collaboration", "team communication"]
    },
    "nextQuestion": {
      "id": "q_002",
      "text": "You mentioned feeling disconnected from other teams. Can you tell me more about what makes collaboration difficult?",
      "type": "open_text",
      "isGenerated": true,
      "followUpTo": "q_001"          // Indicates this is a follow-up
    },
    "questionCount": 2,
    "maxQuestions": 10
  }
}

3. Complete the Session

Sessions complete automatically when max questions are reached, or you can complete manually:

POST /api/v1/surveys/{surveyId}/smart-sessions/{sessionId}/complete
Authorization: Bearer YOUR_API_KEY

// Response
{
  "data": {
    "sessionId": "ss_xyz789",
    "status": "completed",
    "summary": {
      "totalQuestions": 6,
      "totalResponses": 6,
      "duration": 420,                // seconds
      "overallSentiment": "mixed",
      "keyThemes": [
        "cross-team collaboration",
        "communication tools",
        "meeting overload"
      ],
      "insights": [
        "Respondent values team relationships but struggles with cross-functional coordination",
        "Communication tools are seen as inadequate for async collaboration",
        "Meeting frequency is a concern affecting productivity"
      ]
    },
    "completedAt": "2026-02-04T10:07:00Z"
  }
}

Session Configuration

Customize Smart Survey behavior in your survey settings or per session:

Using with Embed SDK

The Embed SDK has built-in Smart Survey support with real-time callbacks:

import { Revuloop } from '@revuloop/embed';

const survey = new Revuloop({
  token: 'YOUR_EMBED_TOKEN',
  surveyId: 'srv_abc123',
  mode: 'smart',                    // Enable Smart Survey mode

  // Smart Survey callbacks
  onSmartSurveyInit: (session) => {
    console.log('Session started:', session.sessionId);
    console.log('First question:', session.currentQuestion.text);
  },

  onSmartQuestionChange: (data) => {
    console.log('New question:', data.question.text);
    console.log('Question #:', data.questionNumber);
    console.log('Is follow-up:', !!data.question.followUpTo);
  },

  onSmartResponseRecorded: (data) => {
    console.log('Sentiment:', data.sentiment);
    console.log('Themes:', data.themes);
  },

  onComplete: (summary) => {
    console.log('Session complete!');
    console.log('Key themes:', summary.keyThemes);
    console.log('Insights:', summary.insights);
  }
});

survey.open();

Credit Usage

Required Scopes

Best Practices