< back to index

HTTP request

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

Required Parameters

Parameter name Value Description
office_id integer The unique internal identifier for this office (either office_id OR office_we_vote_id required -- not both. If it exists, office_id is used instead of office_we_vote_id)
office_we_vote_id string The unique identifier for this office across all networks (either office_id OR office_we_vote_id required -- not both.) NOTE: In the future we might support other identifiers used in the industry.


  "status": string,
  "success": boolean,
  "office_id": integer,
  "office_we_vote_id": string,
  "google_civic_election_id": integer,
  "candidate_list": list
     "id": integer,
     "status": string,
     "success": boolean,
     "ballot_item_display_name": string,
     "ballotpedia_candidate_id": integer,
     "ballotpedia_candidate_summary": string,
     "ballotpedia_candidate_url": string,
     "candidate_photo_url_large": string,
     "candidate_photo_url_medium": string,
     "candidate_photo_url_tiny": string,
     "kind_of_ballot_item": string,
     "last_updated": string (time in this format %Y-%m-%d %H:%M:%S),
     "order_on_ballot": integer,
     "party": string,
     "we_vote_id": string,

Response Status Codes

Code Description
VALID_OFFICE_ID_AND_OFFICE_WE_VOTE_ID_MISSING A valid internal office_id parameter was not included, nor was a office_we_vote_id. Cannot proceed.
CANDIDATES_RETRIEVED Candidates were returned for this Office.
NO_CANDIDATES_RETRIEVED There are no candidates stored for this Office.

Try It Now: API Variables

Retrieve all the candidates competing for a particular office.

Parameter name Value  

(opens in new window)