Find races
Returns paginated races. Core race reads require an organization overlay context supplied by the `X-Organization-Id` header. When `$search` is supplied, `election` is required.
Query Parameters
Maximum number of records to return.
0 <= valueNumber of records to skip.
0 <= valueSort object, for example $sort[createdAt]=-1.
Race id or ids.
Full-text/fuzzy search against race office and candidate search terms. Must be paired with election.
Election key or keys.
Stable race key or keys.
District id, or district[$intersectsWith] to find races whose districts intersect the supplied district id or ids.
Office key.
Party key for partisan primary races.
Includes selected joined data. Pass $populate[]=candidates to replace the default slim candidates with full candidate records.
Header Parameters
Organization id used as the overlay organization context.
^[a-fA-F0-9]{24}$Response Body
application/json
Paginated race results.
TypeScript Definitions
Use the response body type in TypeScript.
application/json
Request validation failed.
TypeScript Definitions
Use the response body type in TypeScript.
application/json
Missing organization overlay context.
TypeScript Definitions
Use the response body type in TypeScript.
curl -X GET "https://example.com/races" \ -H "X-Organization-Id: org_123"{
"total": 0,
"limit": 0,
"skip": 0,
"data": [
{
"_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"
}
]
}Get questionnaire by ID
Returns a single questionnaire by id. Authentication is optional for this read; if provided, the token is validated and may affect fields visible to the caller.
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.