Positions

Endpoints

Method	Path	Scope	Description
`GET`	`/voting-events/:idOrCode/positions`	read	List positions.
`POST`	`/voting-events/:idOrCode/positions`	write	Create a position.
`POST`	`/voting-events/:idOrCode/positions/batch`	write	Create up to 100 positions.
`GET`	`/voting-events/:idOrCode/positions/:id`	read	Get a position.
`PATCH`	`/voting-events/:idOrCode/positions/:id`	write	Update a position.
`DELETE`	`/voting-events/:idOrCode/positions/:id`	write	Delete a position.

Query parameters

Name	Type	Required	Description
`groupId`	string	No	List positions in one group.
`search`	string	No	Search position titles and descriptions.

title is required on a single create. Send at least one field on update. A batch row accepts the same fields, but its title is optional at the HTTP layer and Pepvote applies event rules. tallyRule has a required type. Use seatCount and stvQuota only for ranked_stv. Use bordaSchema only for ranked_borda.

Field	Type	Description
`title`	string	1 to 200 characters.
`desc`	string	Up to 2,000 characters.
`groupId`	string	Group ID.
`minSelections`	integer	Minimum 0.
`maxSelections`	integer	Minimum 1.
`votingMethod`	string	An implemented Pepvote voting method.
`tallyRule`	object	A total, ranked, or referendum rule.
`scoreMin`, `scoreMax`	integer	Score voting bounds.
`cumulativePointBudget`	integer	Minimum 1.
`quadraticBaseCreditBudget`	integer	Minimum 1.
`quadraticAllowCreditTopUps`	boolean	Allow paid top-ups.
`quadraticMaxPurchasedCreditsPerVoter`	integer	Minimum 0.

Create example

curl -X POST "https://api.pepvote.com/voting-events/BOARD26/positions" \
  -H "Authorization: Bearer $PEPVOTE_API_KEY" -H "User-Agent: my-app/1.0" \
  -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
  }
}

Batch create

Send { "positions": [...] }. The array must have 1 to 100 rows. This endpoint uses the batch rate limit bucket.

curl -X POST "https://api.pepvote.com/voting-events/BOARD26/positions/batch" \
  -H "Authorization: Bearer $PEPVOTE_API_KEY" -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" -d '{"positions":[{"title":"Chair"},{"title":"Secretary"}]}'

{
  "data": {
    "created": [
      {
        "id": "j57position01",
        "title": "Chair"
      }
    ],
    "skipped": [
      {
        "index": 1,
        "reason": "A position with this title already exists."
      }
    ]
  }
}

Use index to identify the zero-based input row. A successful create returns 201. Delete returns 202 with { "data": { "id": "...", "deletion": "queued" } }.

Positions

Endpoints

Query parameters

Request fields

Create example

Batch create

On this page