Voting events

Use a voting event's id or its short code wherever a path has :idOrCode. All endpoints except health require a bearer API key and a User-Agent header.

Endpoints

Method	Path	Scope	Description
`GET`	`/voting-events`	read	List accessible voting events.
`POST`	`/voting-events`	write	Create a voting event.
`GET`	`/voting-events/:idOrCode`	read	Get one voting event.
`PATCH`	`/voting-events/:idOrCode`	write	Update allowed event settings.
`DELETE`	`/voting-events/:idOrCode`	write	Delete a voting event.
`PUT`	`/voting-events/:idOrCode/logo`	write	Set the event logo from an upload.
`DELETE`	`/voting-events/:idOrCode/logo`	write	Remove the event logo.
`GET`	`/voting-events/:idOrCode/stats`	read	Get event counts and turnout.

List query parameters

Name	Type	Required	Description
`limit`	integer	No	Page size from 1 to 200. Default: 50.
`cursor`	string	No	Cursor from `nextCursor`.
`type`	`election` or `poll`	No	Filter by event type.
`status`	`draft`, `upcoming`, `ongoing`, or `ended`	No	Filter by status. Same names as the dashboard.

Create request fields

title is required. See uploads before setting a logo.

Field	Type	Required	Description
`title`	string	Yes	1 to 200 characters.
`type`	`election` or `poll`	No	Defaults to Pepvote's event type.
`desc`	string	No	Up to 5,000 characters.
`startsAt`, `endsAt`	integer	No	Unix milliseconds.
`liveResult`, `publishedResult`	boolean	No	Control results visibility.
`resultDisplayLimit`	integer	No	Minimum 1.
`groupMode`	boolean	No	Enable event groups.
`voterCanRegister`, `candidateCanRegister`	boolean	No	Allow public registration.
`canContestMultiplePositions`	boolean	No	Allow a candidate to enter more than one position.
`requireVoterId`	boolean	No	Require a voter ID.
`shuffleCandidates`, `multiStepVoting`	boolean	No	Set the voting experience.
`enableWeightedVoting`	boolean	No	Enable weighted voting.
`votingFormat`	`default`, `big_avatar`, `options_with_avatar`, or `options`	No	Set the ballot layout.

Update request fields

Send at least one field. Send null to clear desc, startsAt, endsAt, or resultDisplayLimit.

Field	Type	Description
`title`	string	1 to 200 characters.
`desc`	string or null	Up to 5,000 characters.
`startsAt`, `endsAt`	integer or null	Unix milliseconds.
`liveResult`, `publishedResult`	boolean	Control results visibility.
`voterCanRegister`, `candidateCanRegister`	boolean	Allow public registration.
`resultDisplayLimit`	integer or null	Minimum 1.

Create example

curl -X POST "https://api.pepvote.com/voting-events" \
  -H "Authorization: Bearer $PEPVOTE_API_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: board-2026" \
  -d '{"title":"Board election 2026","type":"election","liveResult":true}'

{
  "data": {
    "id": "j57event01",
    "code": "BOARD26",
    "type": "election",
    "title": "Board election 2026",
    "desc": null,
    "startsAt": null,
    "endsAt": null,
    "status": "draft",
    "locked": false,
    "liveResult": true,
    "publishedResult": false,
    "resultDisplayLimit": null,
    "groupMode": false,
    "votingFormat": "default",
    "shuffleCandidates": false,
    "multiStepVoting": false,
    "canContestMultiplePositions": false,
    "enableWeightedVoting": false,
    "enablePayToVote": false,
    "enablePayToRegisterCandidate": false,
    "registration": {
      "voterCanRegister": false,
      "voterPublicRegistrationClosesAt": null,
      "candidateCanRegister": false,
      "candidatePublicRegistrationClosesAt": null,
      "requireVoterId": false,
      "voterIdValidationLogic": null,
      "voterIdValidatingValue": null
    },
    "aliases": {
      "votingEvent": null,
      "votingCenter": null,
      "position": null,
      "group": null,
      "positionGroup": null,
      "candidateGroup": null,
      "voterGroup": null,
      "candidate": null,
      "voter": null,
      "voterId": null,
      "sponsor": null,
      "weight": null
    },
    "plan": {
      "name": "Starter",
      "maxVoters": 500
    },
    "logoUrl": null,
    "createdAt": 1776900000000
  }
}

Logo example

Upload the image first. Then pass its storageId to the logo endpoint.

curl -X PUT "https://api.pepvote.com/voting-events/BOARD26/logo" \
  -H "Authorization: Bearer $PEPVOTE_API_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{"storageId":"kg2storage01"}'

{
  "data": {
    "id": "j57event01",
    "code": "BOARD26",
    "logoUrl": "https://storage.example/logo.png"
  }
}

Delete returns 204 for a voting event. The stats response has votingEventId, positionCount, candidateCount, approvedCandidateCount, sponsorCount, groupCount, voterCount, approvedVoterCount, pendingVoterCount, votedVoterCount, votesCast, votesConfirmed, and turnoutPercent.