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"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 X-Organization-Id, 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.
^[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": 1,
"limit": 10,
"skip": 0,
"data": [
{
"_id": "6a270dfcf8be694115151dd9",
"election": "2026-california-general-election",
"elections": [],
"official": "xavier-becerra",
"party": "D",
"race": "6a270dd9f8be694115150b90",
"races": [],
"qualified": "yes",
"withdrawn": false,
"name": "Xavier Becerra",
"ballotOrder": 1,
"office": "ca-state-governor",
"district": "675c9a189920391a48a032e8",
"districtType": "state",
"cities": [],
"counties": [],
"raceKey": "2026-california-general-election-ca-state-governor-ca-state",
"longName": "California Governor",
"uncontested": false,
"uncontestedDetailed": "contested",
"contact": [],
"readMoreLinks": [],
"specifiedLinks": [],
"links": [
{
"mediaType": "website",
"url": "https://www.xavierbecerra2026.com/",
"_id": "6a2bed31a78cf6dd16e21027"
},
{
"mediaType": "instagram",
"title": "Instagram",
"url": "https://www.instagram.com/becerraforgovernor",
"_id": "6a2bed31a78cf6dd16e21028"
},
{
"mediaType": "tiktok",
"title": "TikTok",
"url": "https://www.tiktok.com/@becerraforgovernor",
"_id": "6a2bed31a78cf6dd16e21029"
},
{
"mediaType": "twitter",
"title": "Twitter",
"url": "https://x.com/XavierBecerra",
"_id": "6a2bed31a78cf6dd16e2102a"
},
{
"mediaType": "facebook",
"title": "Facebook",
"url": "https://www.facebook.com/becerraforgovernor",
"_id": "6a2bed31a78cf6dd16e2102b"
},
{
"mediaType": "youtube",
"title": "YouTube",
"url": "https://www.youtube.com/@becerraforgovernor",
"_id": "6a2bed31a78cf6dd16e2102c"
},
{
"mediaType": "bluesky",
"title": "Bluesky",
"url": "https://bsky.app/profile/xavierbecerra.bsky.social",
"_id": "6a2bed31a78cf6dd16e2102d"
}
],
"statusByQuestionnaire": [],
"createdAt": "2026-06-08T18:46:20.944Z",
"updatedAt": "2026-06-12T11:27:47.269Z",
"photoPathFace": "https://branch-production-bucket.s3.amazonaws.com/images/candidates/1781001499793_blob"
}
]
}