API Reference (Future)

REST API Reference

The Varied Reach e-Voting API is a JSON REST API. Full API key access is planned for a future release — currently the API is available to logged-in platform users only.

Base URL

https://evoting.variedreach.com/api

Authentication

Authorization: Bearer <access_token>

Short-lived JWT. Refresh via POST /auth/refresh (httpOnly cookie).

Note: The public API key programme (for programmatic access without browser login) is planned for a future release. The endpoints below are accessible today via the browser-based JWT flow. Contact sales@variedreach.com to express interest in early API access.

Authentication

Method	Path	Description	Auth
POST	/auth/request-otp	Request a one-time login code for a registered email	Public
POST	/auth/verify-otp	Verify OTP and receive an access token + refresh cookie	Public
POST	/auth/refresh	Refresh the access token using the httpOnly refresh cookie	Public
POST	/auth/logout	Invalidate the current refresh token	JWT
GET	/auth/me	Return the authenticated user profile	JWT

Assignments

Method	Path	Description	Auth
GET	/assignments	List all assignments for the organisation	JWT
POST	/assignments	Create a new assignment	JWT
GET	/assignments/:id	Get a single assignment by ID	JWT
PATCH	/assignments/:id	Update an assignment	JWT
DELETE	/assignments/:id	Archive an assignment	JWT

Projects & Towers

Method	Path	Description	Auth
GET	/assignments/:id/projects	List projects for an assignment	JWT
POST	/assignments/:id/projects	Create a project	JWT
GET	/projects/:id/towers	List towers for a project	JWT
POST	/projects/:id/towers	Add a tower	JWT

Homebuyers

Method	Path	Description	Auth
GET	/projects/:id/homebuyers	List homebuyers for a project	JWT
POST	/projects/:id/homebuyers/import	Bulk import via CSV/Excel (multipart/form-data)	JWT
POST	/projects/:id/homebuyers	Add a single homebuyer	JWT
PATCH	/homebuyers/:id	Update homebuyer details	JWT
DELETE	/homebuyers/:id	Remove a homebuyer	JWT

Nominations

Method	Path	Description	Auth
GET	/projects/:id/nomination-events	List nomination events	JWT
POST	/projects/:id/nomination-events	Create a nomination event	JWT
GET	/nomination-events/:id/nominations	List nominations for an event	JWT
POST	/nomination-events/:id/nominations	Submit a nomination	JWT
POST	/nominations/:id/review	Approve, reject, or request correction	JWT
GET	/nomination-events/:id/candidates	List approved candidates	JWT

Elections & Voting

Method	Path	Description	Auth
GET	/projects/:id/elections	List elections	JWT
POST	/projects/:id/elections	Create an election	JWT
PATCH	/elections/:id/open	Open election and generate voting tokens	JWT
PATCH	/elections/:id/close	Close election	JWT
POST	/elections/:id/declare-result	Decrypt, tally, and publish results	JWT
GET	/vote/:token/status	Check voting token status (public)	Public
POST	/vote/:token/request-otp	Send OTP to homebuyer for verification (public)	Public
POST	/vote/:token/verify-otp	Verify homebuyer OTP (public)	Public
GET	/vote/:token/ballot	Get ballot candidates (public, after OTP verify)	Public
POST	/vote/:token/cast	Cast an encrypted vote (public)	Public

Quotes & Pricing

Method	Path	Description	Auth
GET	/pricing-plans	List available pricing plans (Super Admin)	JWT
POST	/quotes/preview	Calculate a quote breakdown without saving	JWT
GET	/assignments/:id/quotes	List quotes for an assignment	JWT
POST	/assignments/:id/quotes	Create and save a quote	JWT
GET	/quotes/:id/documents/:type	Download a PDF document (proposal/quotation/invoice)	JWT

Response format

Success (2xx)

// Typical list response
{
  "data": [...],
  "total": 42,
  "page": 1,
  "pageSize": 20
}

// Typical single object
{
  "id": "...",
  "createdAt": "...",
  ...
}

Error (4xx / 5xx)

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed: email must be a valid email",
  "timestamp": "2026-07-01T12:00:00Z"
}

Interested in API access?

The programmatic API key programme is in development. Express interest to get early access.

Express Interest