Find candidates
Returns paginated candidates for a supplied query. At least one non-special query parameter is required.
Query Parameters
Maximum number of records to return.
0 <= valueNumber of records to skip.
0 <= valueSort object, for example $sort[createdAt]=-1.
Candidate id or ids. Counts as the required non-special query parameter.
Fuzzy Atlas Search query against candidate name.
Election key or keys. The service also matches multi-race candidates whose elections array contains the requested key. Do not use $in or $nin; pass repeated/array values directly.
Race id or ids. The service also matches multi-race candidates whose races array contains the requested id and folds the matching race back into the race field in the response. Do not use $in or $nin; pass repeated/array values directly.
Official key linked across one or more candidate records.
District id copied from the race, or district[$intersectsWith] to resolve candidates whose race districts intersect the supplied district.
Office key copied from the race.
Qualification status. Anonymous callers are automatically constrained to qualified=yes unless server-side parameters skip qualification checks.
"tbd""yes" | "no" | "tbd"Candidate coverage plan copied from the race.
"issues-coverage" | "auto-coverage" | "basic-coverage" | "no-coverage"Candidate coverage status copied from the race.
"no-coverage" | "coverage" | "archived"Organization overlay id. When supplied, the overlay service merges the organization's candidate overrides into global candidates, includes organization-created candidates, excludes organization-deleted candidates, and may return overlay metadata such as overlayOrganizationId, overlayDocumentId, globalId, numberOverlayFields, and resolutionStatus. The same overlay context may also be supplied with the X-Organization-Id header.
^[a-fA-F0-9]{24}$Filters candidates by questionnaire status. Use with statusByQuestionnaire.organization; the service converts both fields into an element match.
"not-started" | "in-progress" | "completed" | "published"Organization id paired with statusByQuestionnaire.status.
^[a-fA-F0-9]{24}$With overlayOrganizationId, restricts results to the organization's configured supported area. This is only meaningful for organization overlay reads.
Header Parameters
Organization id used as the overlay organization context. Equivalent to overlayOrganizationId; when both are supplied, the query parameter takes precedence.
^[a-fA-F0-9]{24}$Response Body
application/json
Paginated candidate results.
TypeScript Definitions
Use the response body type in TypeScript.
curl -X GET "https://example.com/candidates" \ -H "X-Organization-Id: org_123"{
"total": 0,
"limit": 0,
"skip": 0,
"data": [
{
"_id": "65d4f20f8f5a4d7e9a123456",
"name": "string",
"photoPathFace": "string",
"photoPathSquare": "string",
"links": [
{
"mediaType": "twitter",
"title": "string",
"url": "http://example.com"
}
],
"bios": [
{
"type": "personal",
"text": "string",
"sources": [
{
"url": "http://example.com",
"type": "string",
"sourceType": "website",
"directQuote": "string",
"title": "string"
}
],
"complete": true,
"missingData": "no-public-info",
"hasHallucinations": true
}
],
"questionnaire": "string",
"issues": [
{
"key": "string",
"title": "string",
"complete": false,
"missingData": "no-public-info",
"text": "string",
"sources": [
{
"url": "http://example.com",
"type": "string",
"sourceType": "website",
"directQuote": "string",
"title": "string"
}
],
"isTopPriority": false,
"soundbiteAudioPath": "string",
"textPolicyMarkup": "string",
"policyTerms": [
"string"
],
"stances": [
{
"text": "string",
"sources": [
{
"url": "http://example.com",
"type": "string",
"sourceType": "website",
"directQuote": "string",
"title": "string"
}
],
"complete": false,
"usefulness": 0,
"redundant": true,
"issuesSecondary": [
"string"
],
"textApproved": true,
"editsMade": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}
],
"archivedIssues": [
{
"key": "string",
"title": "string",
"complete": false,
"missingData": "no-public-info",
"text": "string",
"sources": [
{
"url": "http://example.com",
"type": "string",
"sourceType": "website",
"directQuote": "string",
"title": "string"
}
],
"isTopPriority": false,
"soundbiteAudioPath": "string",
"textPolicyMarkup": "string",
"policyTerms": [
"string"
],
"stances": [
{
"text": "string",
"sources": [
{
"url": "http://example.com",
"type": "string",
"sourceType": "website",
"directQuote": "string",
"title": "string"
}
],
"complete": false,
"usefulness": 0,
"redundant": true,
"issuesSecondary": [
"string"
],
"textApproved": true,
"editsMade": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}
],
"progress": 0,
"status": "incomplete",
"incompleteFields": [
"string"
],
"missingInfoChecked": "2019-08-24T14:15:22Z",
"profiledAt": "2019-08-24T14:15:22Z",
"references": {
"checked": false,
"totalSources": 0,
"categories": [
{
"type": "string",
"sources": [
{
"mediaType": "twitter",
"title": "string",
"url": "http://example.com"
}
],
"missing": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
},
"election": "string",
"elections": [
"string"
],
"official": "string",
"party": "string",
"race": "65d4f20f8f5a4d7e9a123456",
"races": [
"65d4f20f8f5a4d7e9a123456"
],
"runoffPrecedent": "65d4f20f8f5a4d7e9a123456",
"primaryPrecedent": "65d4f20f8f5a4d7e9a123456",
"qualified": "yes",
"withdrawn": false,
"incumbent": true,
"contact": [
{
"method": "phone",
"value": "string",
"visibility": "public"
}
],
"summary": "string",
"readMoreLinks": [
{
"text": "string",
"url": "http://example.com"
}
],
"specifiedLinks": [
{
"mediaType": "twitter",
"title": "string",
"url": "http://example.com"
}
],
"finance": {
"filerId": "string",
"schemaVersion": "1.0",
"summaryData": {},
"processedAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"referenceDocs": [
{
"url": "http://example.com",
"type": "string",
"sourceType": "website",
"directQuote": "string",
"title": "string"
}
],
"problemDocs": [
{
"url": "http://example.com",
"type": "string",
"sourceType": "website",
"directQuote": "string",
"title": "string"
}
]
},
"result": {
"autoSources": [
{
"sourceType": "clarity",
"lookupData": {},
"totalVotes": 0,
"percentage": 0,
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"manual": {
"totalVotes": 0,
"updatedAt": "2019-08-24T14:15:22Z"
}
},
"ballotOrder": 3000,
"office": "string",
"district": "65d4f20f8f5a4d7e9a123456",
"districtType": "county",
"cities": [
"65d4f20f8f5a4d7e9a123456"
],
"counties": [
"65d4f20f8f5a4d7e9a123456"
],
"raceKey": "string",
"longName": "string",
"priorityLevel": "high",
"expectedReaders": 0,
"coverageStatus": "no-coverage",
"customFields": {},
"statusByQuestionnaire": [
{
"questionnaire": "65d4f20f8f5a4d7e9a123456",
"organization": "65d4f20f8f5a4d7e9a123456",
"status": "not-started",
"submittedAt": "2019-08-24T14:15:22Z",
"publishedAt": "2019-08-24T14:15:22Z"
}
],
"questionnaireSortByOrganization": {
"property1": {
"status": "not-started",
"statusRank": 0,
"submittedAt": "2019-08-24T14:15:22Z",
"publishedAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
},
"property2": {
"status": "not-started",
"statusRank": 0,
"submittedAt": "2019-08-24T14:15:22Z",
"publishedAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
},
"coveragePlan": "issues-coverage",
"attributedOrganizations": [
{
"key": "string",
"coveragePlan": "no-coverage"
}
],
"issuesToCover": [
"string"
],
"photoOptions": [
"string"
],
"showcaseRanking": 0,
"interviewed": false,
"sentQuestionnaire": false,
"jobs": [
{
"_id": "65d4f20f8f5a4d7e9a123456",
"type": "webscrape",
"status": "INPROGRESS",
"request": "string",
"responsePayload": "string",
"stepsComplete": [
"string"
],
"totalSteps": [
"string"
],
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"questionnaireResponse": {},
"overlayOrganizationId": "65d4f20f8f5a4d7e9a123456",
"globalId": "65d4f20f8f5a4d7e9a123456",
"overlayDocumentId": "65d4f20f8f5a4d7e9a123456",
"numberOverlayFields": 0,
"resolutionStatus": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}