< back to index

HTTP request

GET https://api.wevoteusa.org/apis/v1/voterBallotItemsRetrieve (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

Optional Parameters

Parameter name	Value	Description
google_civic_election_id	integer	The unique identifier for a particular election. If not provided, use the most recent ballot for the voter's address.
ballot_returned_we_vote_id	string	The unique identifier for the ballot at one address.
ballot_location_shortcut	string	The unique identifier for one ballot, identified by a string url.
use_test_election	boolean	If you need to request a test election, pass this with the value 'True'. Note that text_for_map_search (either passed into this API endpoint as a value, or previously saved with voterAddressSave) is required with every election, including the test election.

Response

{
  "status": string,
  "success": boolean,
  "voter_device_id": string (88 characters long),
  "google_civic_election_id": integer (if an error response),
  "original_text_city": string,
  "original_text_state": string,
  "original_text_zip": string,
  "text_for_map_search": string (if an error response),
  "substituted_address_nearby": string,
  "substituted_address_city": string,
  "substituted_address_state": string,
  "substituted_address_zip": string,
  "ballot_found": boolean (if an error response),
  "ballot_caveat": string (if an error response),
  "is_from_substituted_address": boolean,
  "is_from_test_ballot": boolean (if an error response),
  "ballot_item_list": list
   [
     "id": integer,
     "we_vote_id": string,
     "ballot_item_display_name": string,
     "google_civic_election_id": integer,
     "google_ballot_placement": integer,
     "local_ballot_order": integer,
     "kind_of_ballot_item": string (CANDIDATE, MEASURE),
     "measure_subtitle": string (if kind_of_ballot_item is MEASURE)
     "measure_text": string (if kind_of_ballot_item is MEASURE)
     "measure_url": string (if kind_of_ballot_item is MEASURE)
     "yes_vote_description": string (if kind_of_ballot_item is MEASURE)
     "no_vote_description": string (if kind_of_ballot_item is MEASURE)
     "candidate_list": list (if kind_of_ballot_item is CANDIDATE)
      [
        "id": integer,
        "we_vote_id": string,
        "ballot_item_display_name": string,
        "ballotpedia_candidate_id": integer,
        "ballotpedia_candidate_summary": string,
        "ballotpedia_candidate_url": string,
        "ballotpedia_person_id": integer,
        "candidate_email": string,
        "candidate_phone": string,
        "candidate_photo_url_large": string,
        "candidate_photo_url_medium": string,
        "candidate_photo_url_tiny": string,
        "candidate_url": string,
        "candidate_contact_form_url": string,
        "contest_office_id": integer,
        "contest_office_name": string,
        "contest_office_we_vote_id": string,
        "facebook_url": string,
        "google_civic_election_id": integer,
        "instagram_handle": string,
        "instagram_followers_count": string,
        "kind_of_ballot_item": string,
        "maplight_id": string,
        "ocd_division_id": string,
        "order_on_ballot": integer,
        "party": string,
        "politician_id": string,
        "politician_we_vote_id": string,
        "state_code": string,
        "twitter_url": string,
        "twitter_handle": string,
        "twitter_description": string,
        "twitter_followers_count": integer,
        "youtube_url": string,
        "is_battleground_race": boolean,
        "withdrawn_from_election": boolean,
        "withdrawal_date": date,
      ],
   ],
}

Response Status Codes

Code	Description
VALID_VOTER_DEVICE_ID_MISSING	A valid voter_device_id parameter was not included. Cannot proceed.
VALID_VOTER_ID_MISSING	A valid voter_id was not found from voter_device_id. Cannot proceed.
MISSING_GOOGLE_CIVIC_ELECTION_ID	A valid google_civic_election_id not found. Cannot proceed.
VOTER_BALLOT_ITEMS_RETRIEVED	Ballot items were found.

Try It Now: API Variables

Request a skeleton of ballot data for this voter location, so that the web_app has all the ids it needs to make more requests for data about each ballot item.

Parameter name	Value
voter_device_id:
google_civic_election_id:
ballot_returned_we_vote_id:
ballot_location_shortcut:
use_test_election:	True False

(opens in new window)