Pepvote Support Center

Create Position

POST
/voting-events/{idOrCode}/positions

Authorization

bearerAuth
AuthorizationBearer <token>

A key in the form pepvote_api_ followed by 32 hexadecimal characters.

In: header

Header Parameters

Idempotency-Keystring

Optional retry key. First successful response is stored for 24 hours.

  • Length: up to 255 characters
User-Agentstringrequired

Name and version of the calling integration. Required on every request.

Path Parameters

idOrCodestringrequired

Voting event ID or code.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

titlestringrequired

Position title.

  • Length: 1 to 200 characters
descstring

Description shown on the ballot.

  • Length: up to 2000 characters
groupIdstring

Group the position belongs to. Requires group mode.

minSelectionsinteger

Fewest candidates a voter must choose.

  • Minimum value: 0
maxSelectionsinteger

Most candidates a voter may choose.

  • Minimum value: 1
votingMethodenum<string>

How votes are cast and counted for the position: plurality, approval, score, cumulative, quadratic, ranked_choice, or referendum.

  • Values:plurality|approval|score|cumulative|quadratic|ranked_choice|referendum
tallyRuleobject

How the tally is computed. type must match the voting method; seatCount, stvQuota, and bordaSchema apply to ranked methods.

scoreMininteger

Lowest score a voter can give under score voting.

scoreMaxinteger

Highest score a voter can give under score voting.

cumulativePointBudgetinteger

Points each voter distributes under cumulative voting.

  • Minimum value: 1
quadraticBaseCreditBudgetinteger

Credits every voter starts with under quadratic voting.

  • Minimum value: 1
quadraticAllowCreditTopUpsboolean

Let voters buy extra credits under quadratic voting.

quadraticMaxPurchasedCreditsPerVoterinteger

Cap on purchased credits per voter.

  • Minimum value: 0

Response Body

application/json

application/json

curl -X POST "https://example.com/voting-events/string/positions" \  -H "User-Agent: my-app/1.0" \  -H "Content-Type: application/json" \  -d '{}'
{
  "data": {
    "id": "string",
    "votingEventId": "string",
    "groupId": "string",
    "title": "string",
    "desc": "string",
    "votingMethod": "string",
    "tallyRule": {
      "type": "plurality_total",
      "seatCount": 1,
      "stvQuota": "droop",
      "bordaSchema": "zero_based"
    },
    "minSelections": 0,
    "maxSelections": 0,
    "scoreMin": 0,
    "scoreMax": 0,
    "cumulativePointBudget": 0,
    "quadraticBaseCreditBudget": 0,
    "quadraticAllowCreditTopUps": true,
    "quadraticMaxPurchasedCreditsPerVoter": 0,
    "createdAt": 0
  }
}
{
  "error": {
    "code": "bad_request",
    "message": "string",
    "details": {
      "field": "string",
      "parameter": "string",
      "limit": 0,
      "retryAfterSeconds": 0,
      "feature": "string",
      "plan": "string"
    }
  }
}
Was this helpful?

Last updated September 6, 2026