API Specificationselections
Find elections
Returns paginated elections.
Query Parameters
$limit?integer
Maximum number of records to return.
Range
0 <= value$skip?integer
Number of records to skip.
Range
0 <= value$sort?
Sort object, for example $sort[createdAt]=-1.
$search?string
Full-text/fuzzy search for elections by name.
key?|array<string>
Election key or keys.
state?string
State district id.
Match
^[a-fA-F0-9]{24}$stateCode?string
Two-letter uppercase state code.
Match
^[A-Z]{2}$status?|array<>
Election status or statuses.
electionType?|array<>
Election type or types.
year?integer
Full election year derived from the election date.
Header Parameters
X-Organization-Id*string
The ID of the organization making the request.
Response Body
application/json
Paginated election results.
TypeScript Definitions
Use the response body type in TypeScript.
curl -X GET "https://example.com/elections" \ -H "X-Organization-Id: org_123"{
"total": 1,
"limit": 10,
"skip": 0,
"data": [
{
"_id": "6a109422784dc82893dfc45b",
"name": "2026 Georgia Primary Runoff",
"key": "2026-georgia-primary-runoff",
"status": "live",
"active": true,
"state": "5eac8e9f21ddc806d4f9aacf",
"stateCode": "GA",
"date": "2026-06-16T04:00:00.000Z",
"year": 2026,
"electionType": "primary-runoff",
"primaryMode": "PRIMARY_MODE_BY_PARTY",
"runoffMode": "RUNOFF_MODE_50_PERCENT_REQUIRED",
"nonpartisanPrimaryMode": "NONPARTISAN_PRIMARY_MODE_DECIDED_IN_PRIMARY",
"partisan": true,
"uncontestedPrimariesAppearOnBallot": true,
"runoffPrecedent": "2026-georgia-primary-election",
"partiesPresent": [
"D",
"N",
"R"
],
"ballotOverview": [],
"createdAt": "2026-05-22T17:36:34.844Z",
"updatedAt": "2026-05-27T14:53:58.209Z",
"earlyVotingEnd": "2026-06-12T04:00:00.000Z",
"earlyVotingStart": "2026-06-08T04:00:00.000Z",
"qualifyingDate": "2026-03-06T05:00:00.000Z",
"voterRegistrationEnd": "2026-05-18T04:00:00.000Z",
"publishDate": "2026-05-27T14:17:29.830Z",
"absenteeEnd": "2026-06-05T04:00:00.000Z",
"parties": [
{
"_id": "69ab528ea7e6cdab132a6f71",
"key": "D",
"name": "Democrat",
"createdAt": "2026-03-06T22:17:50.164Z",
"updatedAt": "2026-03-06T22:17:50.164Z"
},
{
"_id": "69ab528ea7e6cdab132a6f76",
"key": "N",
"name": "Nonpartisan",
"createdAt": "2026-03-06T22:17:50.164Z",
"updatedAt": "2026-03-06T22:17:50.164Z"
},
{
"_id": "69ab528ea7e6cdab132a6f72",
"key": "R",
"name": "Republican",
"createdAt": "2026-03-06T22:17:50.164Z",
"updatedAt": "2026-03-06T22:17:50.164Z"
}
]
}
]
}