Pepvote API
Candidates
Read and manage candidates in a voting event.
Endpoints
| Method | Path | Scope | Description |
|---|---|---|---|
GET | /voting-events/:code/candidates | read | List candidates. |
POST | /voting-events/:code/candidates | write | Create a candidate. |
GET | /voting-events/:code/candidates/:id | read | Get a candidate. |
PATCH | /voting-events/:code/candidates/:id | write | Update a candidate. |
DELETE | /voting-events/:code/candidates/:id | write | Delete a candidate. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
positionId | string | No | Filter by position. |
groupId | string | No | Filter by group. |
status | not_approved, pending, or approved | No | Filter by registration status. |
Request fields
name is required on create. Send at least one field on update. On update, groupId and referendumRole accept null to clear them.
| Field | Type | Required on create | Description |
|---|---|---|---|
name | string | Yes | 1 to 200 characters. |
email | string | No | Up to 320 characters. |
positionIds | string array | No | Position IDs. |
groupId | string or null | No | Group ID. |
status | enum | No | not_approved, pending, or approved. |
referendumRole | enum or null | No | for, against, or abstain. |
Example
curl -X POST "https://api.pepvote.com/voting-events/BOARD26/candidates" \
-H "Authorization: Bearer $PEPVOTE_API_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: candidate-amina-001" \
-d '{"name":"Amina Bello","email":"amina@example.com","positionIds":["j57position01"],"status":"approved"}'{ "data": { "id": "j57candidate01", "votingEventId": "j57event01", "groupId": null, "positionIds": ["j57position01"], "name": "Amina Bello", "email": "amina@example.com", "status": "approved", "selfRegistered": false, "referendumRole": null, "avatarUrl": null, "createdAt": 1776900200000 } }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