Get election by key

Header Parameters

X-Organization-Id*string

The ID of the organization making the request.

Response Body

`application/json`

Election response.

TypeScript Definitions

Use the response body type in TypeScript.

_id?schemas-ObjectId

MongoDB ObjectId serialized as a string.

Match^[a-fA-F0-9]{24}$

key?string

Stable election key used in URLs and references.

name?string

state?schemas-ObjectId

MongoDB ObjectId serialized as a string.

Match^[a-fA-F0-9]{24}$

stateCode?string

Match^[A-Z]{2}$

date?string

Formatdate-time

year?integer

Full numerical year derived from date.

runoffDate?string

Date copied from the associated runoff election when one exists.

Formatdate-time

publishDate?string

Formatdate-time

qualifyingDate?string

Formatdate-time

absenteeEnd?string

Formatdate-time

voterRegistrationEnd?string

Formatdate-time

voterRegistrationAdvanceEnd?string

Formatdate-time

earlyVotingStart?string

Formatdate-time

earlyVotingEnd?string

Formatdate-time

createdAt?string

Formatdate-time

updatedAt?string

Formatdate-time

status?ElectionStatus

Publication/results state for the election. prep means the election is being prepared and is not publicly live. live means the election is visible and active for voters. results-counting means voting has ended and results are still being counted. results-tentative means preliminary results are available but not certified. results-certified means final certified results are available.

Value in"prep" | "live" | "results-counting" | "results-tentative" | "results-certified"

active?boolean

Whether this election is currently active for its locale.

electionType?ElectionType

High-level election category. Primaries choose candidates for later general elections, runoff elections resolve races where no candidate met the required winning threshold, general elections choose officeholders, and special elections fill vacancies or otherwise occur outside the normal election cycle.

Value in"primary" | "primary-runoff" | "general" | "general-runoff" | "special"

primaryMode?ElectionPrimaryMode

Rules for how primary candidates are grouped and advanced. PRIMARY_MODE_BY_PARTY is an open party primary where candidates are split by party. PRIMARY_MODE_BY_PARTY_CLOSED_SEMI is a party primary where party-registered voters use their party ballot and independent voters may choose a party ballot. PRIMARY_MODE_BY_PARTY_CLOSED is a party primary limited to voters registered with that party. PRIMARY_MODE_TOP_TWO is a non-party-grouped primary where the top two candidates advance to the general election.

Value in"PRIMARY_MODE_BY_PARTY" | "PRIMARY_MODE_BY_PARTY_CLOSED_SEMI" | "PRIMARY_MODE_BY_PARTY_CLOSED" | "PRIMARY_MODE_TOP_TWO"

runoffMode?ElectionRunoffMode

Rules for whether a race can advance to a runoff. RUNOFF_MODE_NO_RUNOFF means the top vote-getter wins without a runoff. RUNOFF_MODE_30_PERCENT_REQUIRED means the winner must receive at least 30 percent of the vote or the top candidates advance to a runoff. RUNOFF_MODE_50_PERCENT_REQUIRED means the winner must receive at least 50 percent of the vote or the top candidates advance to a runoff.

Value in"RUNOFF_MODE_NO_RUNOFF" | "RUNOFF_MODE_30_PERCENT_REQUIRED" | "RUNOFF_MODE_50_PERCENT_REQUIRED"

nonpartisanPrimaryMode?ElectionNonpartisanPrimaryMode

Rules for nonpartisan races that appear alongside primary elections. NONPARTISAN_PRIMARY_MODE_DECIDED_IN_PRIMARY means nonpartisan races can be decided during the primary. NONPARTISAN_PRIMARY_MODE_DECIDED_IN_GENERAL means nonpartisan races advance to or are decided in the general election.

Value in"NONPARTISAN_PRIMARY_MODE_DECIDED_IN_PRIMARY" | "NONPARTISAN_PRIMARY_MODE_DECIDED_IN_GENERAL"

partisan?boolean

Computed from stored election configuration fields.

uncontestedPrimariesAppearOnBallot?boolean

runoffPrecedent?string

Election key for the election that precedes this runoff.

primaryPrecedent?string

Primary election key that precedes this general election.

absenteeDisclaimer?string

voterRegistrationDisclaimer?string

voterRegistrationAdvanceDisclaimer?string

earlyVotingDisclaimer?string

electionDayDisclaimer?string

ballotContentDisclaimer?string

partiesPresent?array<string>

Party keys present in primary election races.

parties?array<>

Party records matching partiesPresent, returned in the same order.

ballotOverview?array<string>

Office keys used for prep-phase ballot preview.

translationAvailable?boolean

Whether all translated fields were available for the requested language.

curl -X GET "https://example.com/elections/string" \  -H "X-Organization-Id: org_123"

{
  "_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"
    }
  ]
}

Path Parameters

Header Parameters

Response Body

200application/json

`application/json`