Pepvote Support Center

Register Public Candidate

POST
/public/voting-events/{idOrCode}/register/candidate

Two calls when registration is paid. First call sends the candidate details and gets 402 with a checkout. Second call sends only paymentAttemptId after the payer returns and gets the created candidate.

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.

paymentAttemptIdstring

Second call only. The attempt returned in the 402. When present every other field is ignored.

namestring

Candidate name. Required on the first call.

  • Length: 1 to 200 characters
emailstring

Candidate email. Required when payments.payToRegisterCandidate is true.

  • Length: up to 320 characters
positionIdsarray<string>

Positions to contest. Required on the first call.

  • Items: at least 1 item
groupIdstring

Group the candidate belongs to. Requires group mode.

avatarUrlstring

External photo URL, saved after a free registration succeeds.

  • Length: up to 2048 characters
returnUrlstring

Absolute http(s) URL the payer lands on after a provider-hosted checkout, with paymentAttemptId appended. Required when payments.provider is stripe.

  • Length: up to 2048 characters
  • Format: uri
cancelUrlstring

Absolute http(s) URL the payer lands on after cancelling the checkout, with paymentAttemptId appended.

  • Length: up to 2048 characters
  • Format: uri

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/public/voting-events/string/register/candidate" \  -H "User-Agent: my-app/1.0" \  -H "Content-Type: application/json" \  -d '{}'
{
  "data": {
    "id": "string",
    "name": "string",
    "email": "string",
    "positionIds": [
      "string"
    ],
    "groupId": "string",
    "status": "not_approved",
    "avatarUrl": "string"
  }
}
{
  "data": {
    "id": "string",
    "name": "string",
    "email": "string",
    "positionIds": [
      "string"
    ],
    "groupId": "string",
    "status": "not_approved",
    "avatarUrl": "string"
  }
}
{
  "data": {
    "paymentRequired": true,
    "paymentAttemptId": "string",
    "amount": 0,
    "currency": "string",
    "provider": "stripe",
    "stripe": {
      "checkoutUrl": "http://example.com",
      "checkoutSessionId": "string"
    },
    "next": "string"
  }
}
{
  "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