Get race by ID

Returns a single race by id. Core race reads require an organization overlay context supplied by 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.

Header Parameters

X-Organization-Id?string

Organization id used as the overlay organization context.

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?

runningMates?

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?

runningMateSummary?

Qualified secondary running mates, ordered alphabetically.

candidates?array<|>

Slim candidate records built from candidateSummary by default. Full candidate records are returned when $populate[]=candidates is supplied. For races with running mates enabled, populated results include only primary candidates.

runningMateCandidates?array<>

Full running-mate candidate records returned when running mates are enabled and $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
  },
  "runningMates": {
    "enabled": false,
    "secondaryOffice": "string"
  },
  "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"
    ]
  },
  "runningMateSummary": {
    "numCandidates": 0,
    "numCandidatesNotQualified": 0,
    "names": [
      "string"
    ],
    "keys": [
      "string"
    ],
    "ids": [
      "65d4f20f8f5a4d7e9a123456"
    ],
    "photos": [
      "string"
    ],
    "parties": [
      "string"
    ],
    "mainCandidateIds": [
      "65d4f20f8f5a4d7e9a123456"
    ]
  },
  "candidates": [
    {
      "_id": "65d4f20f8f5a4d7e9a123456",
      "photo": "string",
      "photoPathFace": "string",
      "name": "string",
      "party": "string",
      "official": "string"
    }
  ],
  "runningMateCandidates": [
    {
      "_id": "65d4f20f8f5a4d7e9a123456",
      "name": "string",
      "photoPathFace": "string",
      "links": [
        {
          "_id": "65d4f20f8f5a4d7e9a123456",
          "mediaType": "twitter",
          "title": "string",
          "url": "http://example.com"
        }
      ],
      "questionnaire": "string",
      "election": "string",
      "elections": [
        "string"
      ],
      "official": "string",
      "party": "string",
      "race": "65d4f20f8f5a4d7e9a123456",
      "races": [
        "65d4f20f8f5a4d7e9a123456"
      ],
      "runoffPrecedent": "65d4f20f8f5a4d7e9a123456",
      "primaryPrecedent": "65d4f20f8f5a4d7e9a123456",
      "runningMate": {
        "candidate": "65d4f20f8f5a4d7e9a123456",
        "isPrimary": true
      },
      "qualified": "yes",
      "withdrawn": false,
      "incumbent": true,
      "recentActivity": [
        {
          "user": "65d4f20f8f5a4d7e9a123456",
          "timestamp": "2019-08-24T14:15:22Z",
          "type": "edited",
          "_id": "65d4f20f8f5a4d7e9a123456"
        }
      ],
      "contact": [
        {
          "method": "phone",
          "value": "string",
          "visibility": "public"
        }
      ],
      "summary": "string",
      "readMoreLinks": [
        {
          "text": "string",
          "url": "http://example.com",
          "date": "2019-08-24",
          "author": "string",
          "image": "http://example.com"
        }
      ],
      "specifiedLinks": [
        {
          "_id": "65d4f20f8f5a4d7e9a123456",
          "mediaType": "twitter",
          "title": "string",
          "url": "http://example.com"
        }
      ],
      "ballotOrder": 3000,
      "office": "string",
      "district": "65d4f20f8f5a4d7e9a123456",
      "districtType": "county",
      "cities": [
        "65d4f20f8f5a4d7e9a123456"
      ],
      "counties": [
        "65d4f20f8f5a4d7e9a123456"
      ],
      "raceKey": "string",
      "longName": "string",
      "uncontested": false,
      "uncontestedDetailed": "under-contested",
      "customFields": {},
      "statusByQuestionnaire": [
        {
          "questionnaire": "65d4f20f8f5a4d7e9a123456",
          "organization": "65d4f20f8f5a4d7e9a123456",
          "status": "not-started",
          "submittedAt": "2019-08-24T14:15:22Z",
          "publishedAt": "2019-08-24T14:15:22Z"
        }
      ],
      "questionnaireResponse": {},
      "overlayOrganizationId": "65d4f20f8f5a4d7e9a123456",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "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`