Public voting

Use these endpoints to build your own voting interface. Call them from your server with an API key that has the vote scope. Do not call them from browser code.

The organizer key never sees a voter key. Pepvote creates and emails a voter key when your server requests one. The email still links to Pepvote, but the voter uses the key in your interface. Your interface sends that key to your server, and your server relays it to Pepvote.

There are no ballot attempts, sessions, or tokens in this API.

Endpoints

Identity model

Elections use a voter ID and a voter key. Request a key with voterId when the event requires voter IDs. Otherwise request it with email.

Polls require visitorId on eligibility, cast, and quadratic credit requests. It must be vi_ followed by 16 to 128 hexadecimal characters. Use one of these choices, in order:

1. If you want email-based deduplication, turn on saveVoterInfo and send email.
2. Otherwise, use visitorId = "vi_" + sha256(lowercased email).
3. Or use an HMAC of your own user ID.

A raw email is accepted as a voter ID in some poll flows, but do not use it as visitorId. A visitor ID becomes the visible voter ID and the credit ledger key.

Read voter.pollIdentity from the event context. It tells you which poll identity the event uses. The context also includes payments, which tells you if checkout is needed.

Voter registration

Use this only when the event lets voters self-register.

curl -X POST "https://api.pepvote.com/public/voting-events/BOARD26/register/voter" \
  -H "Authorization: Bearer $PEPVOTE_VOTE_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: voter-registration-001" \
  -d '{"name":"Grace Hopper","email":"grace@example.com","voterId":"MEM-42"}'

{
  "data": {
    "id": "j57voter01",
    "name": "Grace Hopper",
    "email": "grace@example.com",
    "voterId": "MEM-42",
    "status": "pending",
    "weight": 1
  }
}

Candidate registration

Paid registration needs email and returns 402. Follow payments to complete checkout, then send the same endpoint { "paymentAttemptId": "..." } and nothing else.

curl -X POST "https://api.pepvote.com/public/voting-events/BOARD26/register/candidate" \
  -H "Authorization: Bearer $PEPVOTE_VOTE_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: candidate-registration-001" \
  -d '{"name":"Ada Lovelace","email":"ada@example.com","positionIds":["j57position01"],"avatarUrl":"https://images.example/ada.png"}'

{
  "data": {
    "id": "j57candidate01",
    "name": "Ada Lovelace",
    "positionIds": [
      "j57position01"
    ],
    "avatarUrl": "https://images.example/ada.png",
    "status": "pending"
  }
}

Ballot preview

Get the event context before you render the ballot. Then get the ballot. You can send an optional seed query parameter to keep a shuffled order stable for one voter.

curl "https://api.pepvote.com/public/voting-events/BOARD26/ballot?seed=member-42" \
  -H "Authorization: Bearer $PEPVOTE_VOTE_KEY" \
  -H "User-Agent: my-app/1.0"

{
  "data": {
    "votingEventId": "j57event01",
    "positions": [
      {
        "id": "j57position01",
        "title": "President",
        "votingMethod": "plurality",
        "group": null
      }
    ],
    "candidates": [
      {
        "id": "j57candidate01",
        "name": "Ada Lovelace",
        "positionIds": [
          "j57position01"
        ],
        "group": null,
        "referendumRole": null,
        "avatarUrl": null
      }
    ],
    "sponsors": [
    ]
  }
}

Ballot entries

Every cast sends votes, an array of 1 to 200 entries. One entry selects one candidate for one position. The ballot response tells you each position's votingMethod, minSelections, maxSelections, and for score positions scoreMin and scoreMax, for cumulative positions cumulativePointBudget, and for quadratic positions quadraticBaseCreditBudget.

A wrong shape returns 422 validation_error naming the entry, for example votes[2].rank.

Election cast

First request a voter key. Send voterId for an event that requires it. Otherwise send email. Pepvote emails the key to the voter. The voter types it into your interface. You then relay it to voter/check and ballot/cast.

voter/check is optional. It always returns 200 with eligible: false and a reason for an eligibility failure. Use it before rendering a ballot if that helps your interface. Cast checks everything again.

curl -X POST "https://api.pepvote.com/public/voting-events/BOARD26/ballot/cast" \
  -H "Authorization: Bearer $PEPVOTE_VOTE_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ballot-cast-001" \
  -d '{"voterId":"MEM-42","voterKey":"voter_key_from_email","countryCode":"CA","votes":[{"positionId":"j57position01","candidateId":"j57candidate01"}]}'

{
  "data": {
    "confirmationCode": "PV-7K2M",
    "votesCount": 1
  }
}

countryCode is optional. Pepvote stores it as your reported country. API votes do not use VPN detection. Votes have channel api.

voter-key/request takes voterId or email (one is required) and returns { "sent": true, "maskedEmail": "g***@example.com" }. voter/check takes voterKey plus the same voterId, email, or visitorId you will send to cast.

Poll cast

On a pay-to-vote poll the first cast returns 402; see payments.

curl -X POST "https://api.pepvote.com/public/voting-events/POLL26/ballot/cast" \
  -H "Authorization: Bearer $PEPVOTE_VOTE_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: poll-cast-001" \
  -d '{"visitorId":"vi_ab12ab12ab12ab12ab12ab12ab12ab12","votes":[{"positionId":"j57position01","candidateId":"j57candidate01"}]}'

{
  "data": {
    "confirmationCode": "PV-9D4R",
    "votesCount": 1
  }
}

Confirm a ballot

Cast does not count votes. It returns a confirmationCode. Confirm that code before you show a success state. The body is { "confirmationCode": "..." }, 1 to 64 characters.

curl -X POST "https://api.pepvote.com/public/voting-events/BOARD26/ballot/confirm" \
  -H "Authorization: Bearer $PEPVOTE_VOTE_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{"confirmationCode":"PV-7K2M"}'

{
  "data": {
    "confirmationCode": "PV-7K2M",
    "confirmedCount": 1,
    "totalVotes": 1,
    "submittedAt": 1780000000000,
    "votes": [
      {
        "positionName": "President",
        "candidateName": "Ada Lovelace"
      }
    ]
  }
}

Public results

Results are available only when the event allows live or published results.

curl "https://api.pepvote.com/public/voting-events/BOARD26/results" \
  -H "Authorization: Bearer $PEPVOTE_VOTE_KEY" \
  -H "User-Agent: my-app/1.0"

{
  "data": {
    "votingEventId": "j57event01",
    "title": "Board election",
    "positions": [
      {
        "id": "j57position01",
        "title": "President",
        "candidates": [
          {
            "id": "j57candidate01",
            "name": "Ada Lovelace",
            "votesWon": 24
          }
        ],
        "totalVotes": 24
      }
    ],
    "stats": {
      "totalVotes": 24
    }
  }
}

Quadratic credits

Credits belong to a position and are keyed by visitorId. GET .../quadratic-credits and GET .../quadratic-credits/options both take positionId and visitorId as query parameters. Read them before checkout.

curl -X POST "https://api.pepvote.com/public/voting-events/POLL26/quadratic-credits/checkout" \
  -H "Authorization: Bearer $PEPVOTE_VOTE_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: credit-checkout-001" \
  -d '{"positionId":"j57position01","visitorId":"vi_ab12ab12ab12ab12ab12ab12ab12ab12","credits":20,"returnUrl":"https://your-app.example/credits"}'

{
  "data": {
    "paymentRequired": true,
    "paymentAttemptId": "j57payment01",
    "amount": 5,
    "currency": "usd",
    "provider": "paystack",
    "paystack": {
      "checkoutUrl": "https://checkout.paystack.com/example",
      "accessCode": "access_code",
      "reference": "reference"
    },
    "credits": 20,
    "pricingModel": "ratio"
  }
}

Read payments for the checkout completion flow.