Get candidate by ID

Path Parameters

id*string

Candidate id.

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

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.

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

Header Parameters

X-Organization-Id?string

Organization id used as the overlay organization context. Equivalent to overlayOrganizationId; when both are supplied, the query parameter takes precedence.

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

photoPathSquare?string

links?array<>

bios?array<>

questionnaire?string

URL for the candidate questionnaire, when available.

issues?array<>

archivedIssues?array<>

progress?number

Range0 <= value <= 1

status?string

Default"incomplete"

Value in"incomplete" | "complete"

incompleteFields?array<string>

missingInfoChecked?string

Formatdate-time

profiledAt?string

Formatdate-time

references?

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

qualified?CandidateQualifiedStatus

Default"tbd"

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

withdrawn?boolean

Defaultfalse

incumbent?boolean

contact?array<>

summary?string

HTML summary for editorial display.

readMoreLinks?array<>

specifiedLinks?array<>

finance?

result?

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

priorityLevel?string

Default"medium"

Value in"high" | "medium" | "low"

expectedReaders?number

coverageStatus?string

Default"no-coverage"

Value in"no-coverage" | "coverage" | "archived"

customFields?

Organization-defined custom values, typically present for overlay reads.

statusByQuestionnaire?array<>

questionnaireSortByOrganization?

Denormalized questionnaire status snapshots keyed by organization id.

coveragePlan?string

Value in"issues-coverage" | "auto-coverage" | "basic-coverage" | "no-coverage"

attributedOrganizations?array<>

issuesToCover?array<string>

photoOptions?array<string>

showcaseRanking?number

Default0

interviewed?boolean

Defaultfalse

sentQuestionnaire?boolean

Defaultfalse

jobs?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}$

globalId?schemas-ObjectId

MongoDB ObjectId serialized as a string.

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

overlayDocumentId?schemas-ObjectId

MongoDB ObjectId serialized as a string.

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

numberOverlayFields?integer

Number of overlay-specific fields applied to the merged response.

resolutionStatus?string

Review/resolution state for an overlay document.

createdAt?string

Formatdate-time

updatedAt?string

Formatdate-time

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

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

Path Parameters

Query Parameters

Header Parameters

Response Body

200application/json

`application/json`