< back to index

HTTP request

GET https://api.wevoteusa.org/apis/v1/candidateRetrieve (Jump to "Try It Now")

Required Parameters

Parameter name Value Description
voter_device_id string An 88 character unique identifier linked to a voter record on the server
api_key string (from post, cookie, or get (in that order)) The unique key provided to any organization using the WeVoteServer APIs
candidate_id integer The unique internal identifier for this candidate (either candidate_id OR candidate_we_vote_id required -- not both. If it exists, candidate_id is used instead of candidate_we_vote_id)
candidate_we_vote_id string The unique identifier for this candidate across all networks (either candidate_id OR candidate_we_vote_id required -- not both.) NOTE: In the future we might support other identifiers used in the industry.

Response

{
  "status": string,
  "success": boolean,
  "voter_device_id": string (88 characters long),
  "kind_of_ballot_item": string (CANDIDATE),
  "id": integer,
  "we_vote_id": string,
  "ballot_item_display_name": string,
  "candidate_photo_url_large": string,
  "candidate_photo_url_medium": string,
  "candidate_photo_url_tiny": string,
  "order_on_ballot": integer,
  "google_civic_election_id": integer,
  "ballotpedia_candidate_id": integer,
  "ballotpedia_candidate_summary": string,
  "ballotpedia_candidate_url": string,
  "ballotpedia_person_id": integer,
  "maplight_id": integer,
  "contest_office_id": integer,
  "contest_office_we_vote_id": string,
  "contest_office_name": string,
  "politician_id": integer,
  "politician_we_vote_id": string,
  "party": string,
  "ocd_division_id": string,
  "state_code": string,
  "candidate_url": string,
  "candidate_contact_form_url": string,
  "facebook_url": string,
  "twitter_url": string,
  "twitter_handle": string,
  "google_plus_url": string,
  "youtube_url": string,
  "candidate_email": string,
  "candidate_phone": string,
}

Response Status Codes

Code Description
VALID_VOTER_DEVICE_ID_MISSING Cannot proceed. A valid voter_device_id parameter was not included.
VALID_VOTER_ID_MISSING Cannot proceed. A valid voter_id was not found.

Try It Now: API Variables

Retrieve detailed information about one candidate.

Parameter name Value  
voter_device_id:
candidate_id:
candidate_we_vote_id:

(opens in new window)