GET /survey

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

Request

GET /public/survey

Headers

Response

{
	"title": "Customer Satisfaction Survey",
	"questions": [
		{
			"questionId": "1",
			"questionText": "How satisfied are you with our service?",
			"questionType": "likert",
			"responseType": "single",
			"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": "multi-choice",
			"responseType": "independent",
			"answerOptions": [
				{ "optionId": "1", "optionText": "Dashboard" },
				{ "optionId": "2", "optionText": "Reports" },
				{ "optionId": "3", "optionText": "API" }
			]
		}
	]
}

Response Fields

Question Object

The Submit Response page shows the answer that each questionType and responseType takes.

Answer Option Object

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”.

Eleven-point scales: A 0-10 scale, such as the one a likelihood-to-recommend survey uses, is an ordinary likert question with 11 answer options carrying optionId"0" through "10", matching labels, and scaleLabels for the endpoints. There is no separate question type for it.

For Kano questions, answer options use a grouped structure:

Examples

JavaScript

const loadSurvey = async (publicKey) => {
	const response = await fetch('https://api.votito.com/public/survey', {
		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/survey', {
			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>
	);
};

Error Responses

401 Unauthorized

Invalid or missing authorization token.

403 Forbidden

The token is not valid.

404 Not Found

The survey does not exist or is not open (survey-not-found).