Get candidate by ID

Path Parameters

id*string

Candidate id.

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

Header Parameters

X-Organization-Id?string

Organization id used as the overlay organization context.

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

Response Body

`application/json`

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

name?string

photoPathFace?string

links?array<>

Links enriched by Branch and returned by default, as part of our standard metadata offering. These include website and social media URLs.

questionnaire?string

URL for the candidate questionnaire, when available.

election?string

Election key for the race shown as the primary race.

elections?array<string>

Election keys for national or multi-race candidates.

official?string

Official key from the officials service. In this API, an official is an office holder; candidates across elections can be linked to the same office-holder record.

party?string

race?|

Primary race for this candidate. Read hooks populate this by default and may choose the race matching a race query for multi-race candidates.

races?array<|>

Races for national or multi-race candidates. Populated by default on reads.

runoffPrecedent?schemas-ObjectId

MongoDB ObjectId serialized as a string.

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

primaryPrecedent?schemas-ObjectId

MongoDB ObjectId serialized as a string.

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

runningMate?|null

qualified?CandidateQualifiedStatus

Default"tbd"

Value in"yes" | "no" | "tbd"

withdrawn?boolean

Defaultfalse

incumbent?boolean

recentActivity?array<>

Recent organization activity for the candidate, populated with user display fields when available.

contact?array<>

summary?string

HTML summary for editorial display.

readMoreLinks?array<>

specifiedLinks?array<>

Organization-specific candidate links populated by the organization. When an organization supplies a link for the same media type as links, treat the specifiedLinks value as that organization's override.

ballotOrder?number

Default3000

office?string

Office key copied from the race for querying/sorting.

district?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<>

raceKey?string

longName?string

Long name of the race, used for display purposes. For example "Pennsylvania Senator, District 10".

uncontested?boolean

Defaultfalse

uncontestedDetailed?string

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

customFields?

Organization-defined custom values.

statusByQuestionnaire?array<>

questionnaireResponse?|

Present for organization overlay reads when a questionnaire response exists for the candidate.

overlayOrganizationId?schemas-ObjectId

MongoDB ObjectId serialized as a string.

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

createdAt?string

Formatdate-time

updatedAt?string

Formatdate-time

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

{
  "_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"
}

Path Parameters

Header Parameters

Response Body

200application/json

`application/json`