GET /surveys/

Load survey questions for display to a panelist. Returns only the fields needed for voting - sensitive metadata is excluded.

Request

GET /public/surveys/

Headers

Header	Required	Description
Authorization	Yes	Compound token from Tenant API

Response

{
  "title": "Customer Satisfaction Survey",
  "questions": [
    {
      "questionId": "1",
      "questionText": "How satisfied are you with our service?",
      "questionType": "likert",
      "scaleLabels": {
        "min": "Very Dissatisfied",
        "max": "Very Satisfied"
      },
      "answerOptions": [
        { "optionId": "1", "label": "1" },
        { "optionId": "2", "label": "2" },
        { "optionId": "3", "label": "3" },
        { "optionId": "4", "label": "4" },
        { "optionId": "5", "label": "5" }
      ]
    },
    {
      "questionId": "2",
      "questionText": "Which features do you use?",
      "questionType": "multiple",
      "answerOptions": [
        { "optionId": "1", "optionText": "Dashboard" },
        { "optionId": "2", "optionText": "Reports" },
        { "optionId": "3", "optionText": "API" }
      ]
    }
  ]
}

Response Fields

Field	Type	Description
title	string	Survey title
questions	array	List of question objects, sorted by display order

Question Object

Field	Type	Description
questionId	string	Unique question identifier (use in vote submission)
questionText	string	The question text to display
questionType	string	Question type: `likert`, `kano`, `single`, `multiple`
scaleLabels	object	(Optional) Scale endpoint labels for likert questions
answerOptions	array	Available answer options

Answer Option Object

Field	Type	Description
optionId	string	Unique option identifier (use in vote submission)
label	string	(Optional) Display label for scale positioning
optionText	string	(Optional) Full option text to display

Likert scale display: For likert questions, label determines where the option appears on the scale. This may differ from optionId for reverse-scored questions. For example, an option with optionId: "1" and label: "7" should be displayed at position 7 on the scale (the positive end), even though votes are recorded as “1”.

For Kano questions, answer options use a grouped structure:

Field	Type	Description
label	string	Group label (e.g., “If present”, “If absent”)
options	array	Nested options with `optionId` and `optionText`

Examples

JavaScript

const loadSurvey = async (publicKey) => {
  const response = await fetch('https://api.votito.com/public/surveys/', {
    headers: { 'Authorization': publicKey }
  });

  if (!response.ok) {
    throw new Error(`Failed to load survey: ${response.status}`);
  }

  const survey = await response.json();

  return survey;
};

// Usage
const survey = await loadSurvey(publicKey);
survey.questions.forEach(q => {
  console.log(`${q.questionText}`);
  q.answerOptions.forEach(opt => {
    console.log(`  - ${opt.optionText || opt.label}`);
  });
});

React Example

const SurveyForm = ({ publicKey }) => {
  const [survey, setSurvey] = useState(null);

  useEffect(() => {
    fetch('https://api.votito.com/public/surveys/', {
      headers: { 'Authorization': publicKey }
    })
      .then(r => r.json())
      .then(setSurvey);
  }, [publicKey]);

  if (!survey) return <div>Loading...</div>;

  return (
    <form>
      <h1>{survey.title}</h1>
      {survey.questions.map(q => (
        <Question key={q.questionId} question={q} />
      ))}
    </form>
  );
};