Get race by ID

Returns a single race by id. Core race reads require an organization overlay context supplied by `overlayOrganizationId` or the `X-Organization-Id` header.

Path Parameters

id*string

Race id.

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

Query Parameters

$populate?array<>

Includes selected joined data. Pass $populate[]=candidates to replace the default slim candidates with full candidate records.

$includeParentDistrict?boolean

Includes parent district details on populated race districts.

overlayOrganizationId?string

Organization overlay id. When supplied, the overlay service merges the organization's race overrides into global races, includes organization-created races, excludes organization-deleted races, restricts results to the organization's supported area, and returns the external organization-authenticated race shape. The same overlay context may also be supplied with the X-Organization-Id header.

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

Header Parameters

X-Organization-Id?string

Organization id used as the overlay organization context. Equivalent to overlayOrganizationId; when both are supplied, the query parameter takes precedence.

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

Response Body

`application/json`

Race 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}$

election?string

Election key.

office?string

Office key. Office details are not populated on race responses.

raceKey?string

Stable race key generated from election, office, district, party, and position data.

district?

Always populated and enriched with pretty district names.

parentDistrict?schemas-ObjectId

MongoDB ObjectId serialized as a string.

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

districtType?DistrictType

District type from the shared districtTypes constants.

Value in

"country" | "state" | "congressional" | "state-utilities" | "state-utilities-subdistrict" | "state-legislative" | "state-senate" | "state-house" | "state-school" | "state-school-subdistrict" | "state-school-bond-district" | "county" | "county-district" | "county-super-district" | "county-school-district" | "county-school-super-district" | "state-transportation" | "county-district-court" | "city" | "city-council" | "city-school-board" | "city-super-school-board" | "judicial-circuit" | "judicial-district" | "superior-court" | "prosecutorial" | "supreme-court" | "court-of-appeals" | "us-judicial-district" | "fire-advisory" | "fire-protection" | "magisterial" | "park" | "hospital" | "water" | "soil" | "community" | "reservation" | "community-council" | "soil-conservation" | "precinct" | "county-utilities" | "justice-precinct" | "appellate-sub-division" | "elementary" | "technical-education" | "technical-education-subdistrict" | "community-college" | "community-college-subdistrict" | "township" | "municipal-court-district" | "city-court" | "state-water" | "state-board-of-education" | "healthcare" | "healthcare-subdistrict" | "county-library" | "library" | "borough" | "city-parks" | "village" | "town" | "village-district" | "town-council" | "natural-resource-district" | "natural-resource-subdistrict" | "board-of-regents" | "public-service-commission"

cities?array<>

counties?array<>

additionalDistricts?array<|>

excludedDistricts?array<>

originalDistrict?||

Original representative district when the race is rolled up to a parent district.

party?string

Party key for partisan primary races.

positionData?

runoffPrecedent?|null

primaryPrecedent?array<>

runoffRace?schemas-ObjectId

MongoDB ObjectId serialized as a string.

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

generalRace?schemas-ObjectId

MongoDB ObjectId serialized as a string.

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

ballotOrder?number

Default3000

maxChoices?number

Default1

rankedChoice?

retention?boolean

Defaultfalse

uncontested?boolean

Defaultfalse

uncontestedDetailed?RaceContestStatus

Default"under-contested"

Value in"under-contested" | "uncontested" | "contested"

longName?string

officeName?string

Race-specific office display name.

descriptionShort?string

detailShort?string

HTML-formatted short details.

detailLong?string

HTML-formatted long details.

readMoreLink?string

candidateSummary?

candidates?array<|>

Slim candidate records built from candidateSummary by default. Full candidate records are returned when $populate[]=candidates is supplied.

questionnaire?|

Present if a questionnaire has been added to the race for that organization.

createdAt?string

Formatdate-time

updatedAt?string

Formatdate-time

`application/json`

Missing organization overlay context.

TypeScript Definitions

Use the response body type in TypeScript.

name?string

message?string

code?integer

className?string

data?

errors?

`application/json`

Race was not found.

TypeScript Definitions

Use the response body type in TypeScript.

name?string

message?string

code?integer

className?string

data?

errors?

curl -X GET "https://example.com/races/65d4f20f8f5a4d7e9a123456" \  -H "X-Organization-Id: org_123"

{
  "_id": "65d4f20f8f5a4d7e9a123456",
  "election": "string",
  "office": "string",
  "raceKey": "string",
  "district": {
    "_id": "65d4f20f8f5a4d7e9a123456",
    "type": "county",
    "matchName": "ga-fulton",
    "displayName": "string",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z",
    "name": "string",
    "fipsCode": "string",
    "number": 0,
    "letter": "string",
    "parentId": "65d4f20f8f5a4d7e9a123456",
    "parent": "string",
    "parentsFlat": [
      "65d4f20f8f5a4d7e9a123456"
    ],
    "population": 0,
    "populationType": "definitive",
    "votingType": "voting-district",
    "intersectingCities": [
      "65d4f20f8f5a4d7e9a123456"
    ],
    "intersectingCounties": [
      "65d4f20f8f5a4d7e9a123456"
    ],
    "state": "65d4f20f8f5a4d7e9a123456",
    "translationAvailable": true,
    "longName": "State House District 77",
    "shortName": "District 77"
  },
  "parentDistrict": "65d4f20f8f5a4d7e9a123456",
  "districtType": "county",
  "cities": [
    "65d4f20f8f5a4d7e9a123456"
  ],
  "counties": [
    "65d4f20f8f5a4d7e9a123456"
  ],
  "additionalDistricts": [
    "65d4f20f8f5a4d7e9a123456"
  ],
  "excludedDistricts": [
    "65d4f20f8f5a4d7e9a123456"
  ],
  "originalDistrict": "65d4f20f8f5a4d7e9a123456",
  "party": "string",
  "positionData": {
    "special": false,
    "seatIdentifier": "string",
    "seatIdentifierType": "post"
  },
  "runoffPrecedent": "65d4f20f8f5a4d7e9a123456",
  "primaryPrecedent": [
    "65d4f20f8f5a4d7e9a123456"
  ],
  "runoffRace": "65d4f20f8f5a4d7e9a123456",
  "generalRace": "65d4f20f8f5a4d7e9a123456",
  "ballotOrder": 3000,
  "maxChoices": 1,
  "rankedChoice": {
    "enabled": false,
    "maxChoices": 1
  },
  "retention": false,
  "uncontested": false,
  "uncontestedDetailed": "under-contested",
  "longName": "string",
  "officeName": "string",
  "descriptionShort": "string",
  "detailShort": "string",
  "detailLong": "string",
  "readMoreLink": "string",
  "candidateSummary": {
    "numCandidates": 0,
    "numCandidatesNotQualified": 0,
    "names": [
      "string"
    ],
    "keys": [
      "string"
    ],
    "ids": [
      "65d4f20f8f5a4d7e9a123456"
    ],
    "photos": [
      "string"
    ],
    "parties": [
      "string"
    ]
  },
  "candidates": [
    {
      "_id": "65d4f20f8f5a4d7e9a123456",
      "photo": "string",
      "photoPathFace": "string",
      "name": "string",
      "party": "string",
      "official": "string"
    }
  ],
  "questionnaire": {},
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Path Parameters

Query Parameters

Header Parameters

Response Body

200application/json

401application/json

404application/json

`application/json`

`application/json`

`application/json`