Panelist API Overview

The Panelist API enables client-side interactions for voting, survey responses, and idea banks. Use it to build custom voting and idea-collection interfaces.

Base URL

https://api.votito.com/public

Authentication

The Panelist API uses compound tokens obtained from the Tenant API. Include the token in the Authorization header:

Authorization: {publicKey}

Survey tokens come from the Tenant API’s panelist access endpoint. Idea bank tokens come from the Tenant API’s ideabank panelist access endpoint.

The endpoints are organized into two groups: Surveys for collecting votes and survey responses, and Idea Banks for proposal submission, voting, comments, and roadmap updates.

Surveys

Survey endpoints load survey questions and record panelist responses and dismissals.

Survey Endpoints

Survey Workflow

1. Get Voting Token

First, your backend calls the Tenant API to get a token:

// Server-side
const { panelist } = await fetch(`https://api.votito.com/tenant/surveys/${surveyId}/panelists/${customerId}`, { headers: { 'X-API-Key': apiKey } }).then((r) =>
	r.json()
);

// Pass panelist.publicKey to your frontend

2. Load Survey

Use the token to load survey questions:

// Client-side
const survey = await fetch('https://api.votito.com/public/survey', {
	headers: { 'Authorization': publicKey }
}).then((r) => r.json());

3. Submit Response

Submit the panelist’s votes:

const result = await fetch('https://api.votito.com/public/survey', {
	method: 'POST',
	headers: {
		'Authorization': publicKey,
		'Content-Type': 'application/json'
	},
	body: JSON.stringify({
		responses: {
			'question-1': { optionId: '3' },
			'question-2': { optionId: '1' }
		},
		isFinal: true
	})
}).then((r) => r.json());

Idea Banks

Idea bank endpoints load an idea bank for a panelist and record proposals, votes, comments, and let panelists track published changes and roadmap items.

Idea Bank Endpoints

Updates

Idea Bank Workflow

1. Get Idea Bank Token

Your backend calls the Tenant API to get a token:

// Server-side
const { panelist } = await fetch(`https://api.votito.com/tenant/ideabanks/${ideaBankId}/panelists/${customerId}`, { headers: { 'X-API-Key': apiKey } }).then(
	(r) => r.json()
);

// Pass panelist.publicKey to your frontend

2. Load Idea Bank

Use the token to load the idea bank and the panelist’s capabilities:

// Client-side
const ideaBank = await fetch('https://api.votito.com/public/ideabank', {
	headers: { 'Authorization': publicKey }
}).then((r) => r.json());

3. Submit a Proposal

Submit a new proposal on the panelist’s behalf:

const result = await fetch('https://api.votito.com/public/ideabank/proposals', {
	method: 'POST',
	headers: {
		'Authorization': publicKey,
		'Content-Type': 'application/json'
	},
	body: JSON.stringify({
		title: 'Dark mode',
		description: 'Please add a dark theme.'
	})
}).then((r) => r.json());

Error Handling

Reference

• Get Survey - Load survey questions for display to a panelist
• Submit Response - Submit panelist votes for survey questions
• Dismiss Survey - Record that a panelist dismissed a survey without responding
• Get Idea Bank - Load idea bank metadata and the panelist's capabilities
• List Proposals - List open proposals in an idea bank, merged with the panelist's own votes
• Submit Proposal - Submit a new proposal to an idea bank on behalf of a panelist
• Vote on Proposal - Cast, update, or remove a panelist's vote on a proposal
• List Comments - List the visible comments on a proposal for a panelist
• Add Comment - Post a comment on a proposal as a panelist
• My Votes - List every proposal the panelist has voted on
• List Changelog - List published changelog entries (implemented proposals) for a panelist
• List Roadmap - List published roadmap items (accepted proposals) for a panelist, cursor-paginated