Pepvote API
Positions
Read and manage positions in a voting event.
Endpoints
| Method | Path | Scope | Description |
|---|---|---|---|
GET | /voting-events/:code/positions | read | List positions. |
POST | /voting-events/:code/positions | write | Create a position. |
GET | /voting-events/:code/positions/:id | read | Get a position. |
PATCH | /voting-events/:code/positions/:id | write | Update a position. |
DELETE | /voting-events/:code/positions/:id | write | Delete a position. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
groupId | string | No | List positions in one group. |
Request fields
title is required on create. Send at least one field on update. tallyRule is an object with a required type. Use seatCount and stvQuota only for ranked_stv. Use bordaSchema only for ranked_borda.
| Field | Type | Required on create | Description |
|---|---|---|---|
title | string | Yes | 1 to 200 characters. |
desc | string | No | Up to 2,000 characters. |
groupId | string | No | Group ID. |
minSelections | integer | No | Minimum 0. |
maxSelections | integer | No | Minimum 1. |
votingMethod | string | No | An implemented Pepvote voting method. |
tallyRule | object | No | type: plurality, approval, score, cumulative, quadratic, referendum, ranked IRV, STV, or Borda total. |
scoreMin, scoreMax | integer | No | Score voting bounds. |
cumulativePointBudget | integer | No | Minimum 1. |
quadraticBaseCreditBudget | integer | No | Minimum 1. |
quadraticAllowCreditTopUps | boolean | No | Allow paid top-ups. |
quadraticMaxPurchasedCreditsPerVoter | integer | No | Minimum 0. |
Example
curl -X POST "https://api.pepvote.com/voting-events/BOARD26/positions" \
-H "Authorization: Bearer $PEPVOTE_API_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: chair-001" -d '{"title":"Board chair","maxSelections":1}'{ "data": { "id": "j57position01", "votingEventId": "j57event01", "groupId": null, "title": "Board chair", "desc": null, "votingMethod": "plurality", "tallyRule": { "type": "plurality_total" }, "minSelections": 0, "maxSelections": 1, "scoreMin": null, "scoreMax": null, "cumulativePointBudget": null, "quadraticBaseCreditBudget": null, "quadraticAllowCreditTopUps": null, "quadraticMaxPurchasedCreditsPerVoter": null, "createdAt": 1776900100000 } }A successful create returns 201. Delete returns 202 with { "data": { "id": "...", "deletion": "queued" } }. The row is removed by the same scheduled batch the dashboard uses, so a read right after the delete can still return it for a moment.
Was this helpful?
Last updated September 5, 2026