openapi: 3.0.2 info: title: Democracy Works Elections API version: '2.0' description: "# Introduction\n\nThe Democracy Works Elections API provides your application with comprehensive elections data and voting guidance, surfacing our unparalleled coverage of upcoming local, state, and federal elections. Power your platforms, apps, reminders, outreach campaigns, and much more.\n\nJoin the community of developers in our [Google Group](https://groups.google.com/a/democracy.works/g/democracy-works-data)\nfor updates about our data and elections.\n\n## Authentication\nAccess to the Democracy Works Elections API requires authentication. To access the DW API, include an X-API-Key header with each API request. The value of that header should be your API key. For example:\n\n```sh\ncurl \"https://api.democracy.works/v2/elections\" \\\n --header \"X-API-KEY: \"\n```\n\nFor pricing information and to obtain a test key, please [contact us](https://data.democracy.works/api-signup).\n\n## Base URL\nThe base URL for all API endpoints is: https://api.democracy.works/v2\n\n## Support\nIf you have any further questions or issues, please contact us at partnerships@democracy.works.\n\n## Data\n\nData is captured in two entities, an __Election__ and an __Authority__. The __Election__ has election-specific dates and deadlines, URLs for voters to get more information and take action, and detailed guidance in both English and Spanish. The __Authority__ includes statewide evergreen information and instructions on how to register and vote for each state, as well as election office contact information. \n\n# Open Civic Data IDs (OCD-IDs)\n\nWe use Open Civic Data IDs [(OCD-IDs)](https://opencivicdata.info/en/latest/ocdids.html) \nthroughout the API to describe entities and filter results. \n\nOCD-IDs start with what is being identified, and in our case it is always \n`ocd-division`.\n\nSince all authorities are, or are contained within, a state and all elections \nare run by some authority, almost every OCD-ID in our system starts with \n`ocd-division/country:us/state:__`, where `__` is a two-letter state postal code.\n\nThe only exception to this is for the District of Columbia, which has the OCD-ID \n`ocd-division/country:us/district:dc`.\n\n## OCD-ID on the Authority\nThe OCD-ID associated with an authority describes the political district covered\nby an authority. Authorities are uniquely identifiable by the associated OCD-ID.\n\nFor example:\n- The OCD-ID `ocd-division/country:us/state:ak/place:anderson` is associated \n with the authority for Anderson, Alaska.\n- The OCD-ID `ocd-division/country:us/state:ny/county:albany/council_district:2` \n is not associated with an authority because Albany's 2nd Ward is a legislative \n ward which does not run its own elections.\n\n## OCD-ID on the Election\nThe OCD-ID associated with an election describes the highest-level district \nin which all voters have something to vote for on the ballot on Election Day. \nElections always have an associated OCD-ID, but are not uniquely\nidentifiable by the associated OCD-ID.\n\nFor example:\n- If there is a mayoral race in Philadelphia as well as a state-wide \nmeasure contest in Pennsylvania on a given day, there will be one election \nentity with OCD-ID `ocd-division/country:us/state:pa`.\n- If there is only a mayoral race in Pittsburgh in Allegheny County on a given \nday, there will be an election entity with OCD-ID \n`ocd-division/country:us/state:pa/county:allegheny`.\n\n# Standard Parameters\nFunctionality shared between API endpoints is noted here. Each endpoint will\nspecify whether it supports the following functionality.\n\n## Pagination\nAny endpoint that returns multiple results supports pagination. An endpoint that \nsupports pagination accepts two related query parameters:\n- `pageSize`\n - Specifies the number of results requested. Defaults to 10 if not specified. The maximum value is 100.\n - Example: `pageSize=15`\n- `page`\n - Specifies the page to return, based on `pageSize`. Defaults to 1 if not specified.\n - Example: `page=2`\n\nYou can send none, one, or both of these parameters. Each endpoint that supports\npagination will have a `pagination` field in the response, which details what\npage of information is returned, what page size was used for the request, and the\ntotal number of results found. \n\n## Localization\nSome endpoints support localization. An endpoint that supports localization accepts a\nheader parameter:\n- `Accept-Language`\n - Specifies the language tag for localization. Accepted values are `en`, `en-US`, `es`, and `es-US`.\n - Example: `Accept-Language: es`\n\nNot all fields on the response of a localized endpoint are localized. Each field that supports localization\nwill have a `Localized` tag on its field description.\n\nIf no localization in the requested language is found,\nlocalized fields will return `null`.\n\n## Content Formatting\nSome endpoints support content formatting. An endpoint that supports formatting accepts a\nquery parameter:\n- `contentFormatType`\n - Specifies the format of certain fields in the response.\n Accepted values are `html` and `json`. Defaults to `html` if not specified.\n - Example: `contentFormatType=json`\n\nNot all fields on the response of a formatted endpoint are formatted. \nFormatting is generally supported on prose-like fields, including Question and Answer content and most instruction fields.\nEach field that supports formatting will have a `Formatted` tag on its field description.\n\nThe `json`-formatted content is the content represented as an [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree).\n\n## Fields\nSome endpoints support field masking to specify a list of fields to include in the API response. This helps to avoid unnecessary computation and improve performance. An endpoint that supports field masking accepts a\nquery parameter:\n- `fields`\n - Specifies the symbolic field paths to include in the response, provided as comma-separated list. See more about [Field Masks](https://protobuf.dev/reference/protobuf/google.protobuf/#field-mask).\n - Example: `fields=\"ocdId,date,contact.email\"`\n\nPaths are validated against all possible fields, and providing an invalid path will result in a 400 response.\n" servers: - url: https://api.democracy.works/v2 tags: - name: Elections paths: /elections: get: operationId: getElections summary: Elections description: "This endpoint has election-specific dates and deadlines, URLs for voters to get more information and take action, and detailed guidance in both English and Spanish. The information included reflects the voter registration and voting methods available in the state for that election, such as online, in-person, and by-mail registration as well as by-mail, in-person, and early voting. The election also contains some information from the related state authority. The default is to return all elections, though you can limit the response to upcoming elections through the use of the start date parameter. Elections are returned sorted chronologically by election date. \n\nAfter an election is confirmed to be occurring, Democracy Works surfaces information about an election as details become available. An elections guidance phase describes the state of the currently available guidance.\n\nA `past` election is an election whose election date is in the past. A `known` election is an upcoming election for which key details and deadlines have yet to be released. An `active` election is an upcoming election for which details have been vetted and confirmed by the Democracy Works team.\n\nElections are returned sorted chronologically by election date. \n\nSupports the following standard parameters: see __[Pagination](#section/Standard-Parameters/Pagination)__, __[Localization](#section/Standard-Parameters/Localization)__, __[Content Formatting](#section/Standard-Parameters/Content-Formatting)__, and __[Fields](#section/Standard-Parameters/Fields)__.\n\n### Ballot Measure Information\n\nInformation about measures on the ballot are available for the following elections:\n- All federal elections\n- All statewide elections\n\nBallot measure information is not included in the default response for an election. For ballot measure information to be included with the response, include the `includeBallotData` parameter with a value of `true`.\n\nBallot data is sourced from [Ballotpedia](https://ballotpedia.org/).\n\n### Candidate and Contest Information\n\nFor the November 5, 2024 elections, our ballot information will include the following:\n- All federal contests and candidates, including president, vice president, senate, and house of representatives\n- All state contests and candidates, including governor, treasurer, secretary of state, state legislative seats, state supreme court, district court, and court of appeals\n- Local candidates and contests including mayor, county judge, county clerk, commissioners, and city councils in the top 100 cities by population, plus state capitals and school board elections in 475 districts\n - Local coverage may be limited by mapping constraints and in states where primaries have not yet been held.\n\nBallot data is sourced from [Ballotpedia](https://ballotpedia.org/).\n" security: - ApiKeyAuth: [] parameters: - name: address in: query schema: type: string description: If sending an address as a single string, the street, city, state, and zip code of an address to get elections for. Using separate parameters for each address element (as shown below) is preferred. example: 813%20Howard%20Street%20Oswego%20NY%2013126 required: false - name: addressStreet in: query schema: type: string description: The street to get elections for in conjunction with other required address parameters. Include Apt numbers or other additional information. example: 813%20Howard%20Street required: false - name: addressCity in: query schema: type: string description: The city to get elections for in conjunction with other required address parameters. example: Oswego required: false - name: addressStateCode in: query schema: type: string description: The 2 letter postal code to get elections for in conjunction with other required address parameters. DC is also accepted. example: NY required: false - name: addressZip in: query schema: type: string description: The zip code to get elections for in conjunction with other required address parameters. example: '13126' required: false - name: addressZip4 in: query schema: type: string description: OPTIONAL. The zip plus 4 to get elections for in conjunction with other required address parameters. example: '9029' required: false - name: stateCode in: query schema: type: string description: The 2-letter postal code to get elections within a respective state. DC is accepted as well. example: CA required: false - name: ocdId in: query schema: type: string description: The OCD-ID(s) of a political division; elections that apply to a voter in this political division will be returned. This parameter may be provided multiple times to return all elections with any of the OCD IDs provided. example: ocd-division%2Fcountry%3Aus%2Fstate%3Any%2Fcounty%3Akings required: false - name: startDate in: query schema: type: date description: The earliest date to get elections for, inclusive, in UTC ISO 8601 format. example: '2023-01-01' required: false - name: endDate in: query schema: type: date description: The latest date to get elections for, inclusive, in UTC ISO 8601 format. example: '2023-01-02' required: false - name: includeQuestionAndAnswer in: query schema: type: boolean description: Whether Question and Answer content should be included for each returned election. Defaults to false if not specified. Response fields are formattable with the __[content formatting](#section/Standard-Parameters/Content-Formatting)__ standard parameter. example: true required: false - name: includeBallotData in: query schema: type: boolean description: Whether ballot data (ballot measures, candidates, and contests) should be included for each returned election. Defaults to false if not specified. example: true required: false responses: '200': description: Elections fetched by query. content: application/json: schema: type: object properties: data: type: object properties: elections: type: array items: $ref: '#/components/schemas/election' statewideOnly: type: boolean description: Unable to determine elections more granular than the state level. Only state level elections returned. pagination: $ref: '#/components/schemas/pagination' examples: sampleElectionsResponse: $ref: '#/components/examples/elections' '400': $ref: '#/components/responses/badRequestError' '429': $ref: '#/components/responses/tooManyRequestsError' '500': $ref: '#/components/responses/internalServerError' tags: - Elections components: responses: tooManyRequestsError: description: TooManyRequestsError content: application/json: schema: $ref: '#/components/schemas/gatewayErrors' example: message: Too Many Requests internalServerError: description: InternalServerError content: application/json: schema: $ref: '#/components/schemas/errors' example: status: 500 message: - Something went wrong. badRequestError: description: Bad Request content: application/json: schema: $ref: '#/components/schemas/errors' example: status: 400 message: - Something has gone wrong parsing your query string. Please refer to our documentation at https://developers.democracy.works/api/v2 to confirm all required fields are present and all fields are formatted correctly. schemas: candidate: description: A representation of a candidate. type: object required: - id - fullName - firstName - lastName - partyAffiliation - isWriteIn properties: id: type: string description: The ID of the candidate. fullName: type: string description: The full name of the candidate. firstName: type: string description: The first name of the candidate. lastName: type: string description: The last name of the candidate. partyAffiliation: type: array description: Describes the party affiliation of the candidate. items: type: string ballotpediaUrl: type: string status: type: string isWriteIn: type: boolean description: Indicates whether a candidate is a write-in candidate. runningMateFullName: type: string runningMateTitle: type: string contact: type: object properties: campaign: type: object properties: email: type: string description: The candidates campaign email address. website: type: string description: The candidates campaign website. facebook: type: string description: The candidates campaign Facebook. twitter: type: string description: The candidates campaign Twitter. instagram: type: string description: The candidates campaign Instagram. youtube: type: string description: The candidates campaign YouTube. mailingAddress: type: string description: The candidates campaign mailing address. phone: type: string description: The candidates campaign phone number. personal: type: object properties: website: type: string description: The candidates personal website. facebook: type: string description: The candidates personal Facebook. twitter: type: string description: The candidates personal Twitter. instagram: type: string description: The candidates personal Instagram. youtube: type: string description: The candidates personal YouTube. linkedIn: type: string description: The candidates personal LinkedIn. pagination: type: object properties: totalRecordCount: type: number description: Total records found for the given query. currentPage: type: number description: The page of records returned. pageSize: type: number description: The number of records returned. election: description: A representation of an election. type: object required: - description - date - ocdId properties: ocdId: type: string description: Provides the [OCD-ID](https://opencivicdata.info/en/latest/ocdids.html) associated with the office. createdAt: type: string description: ISO 8601 timestamp of when the election was first created in Democracy Works' internal database. updatedAt: type: string description: ISO 8601 timestamp of when the election was last updated in Democracy Works' internal database. date: type: string description: Date of the election in YYYY-MM-DD format. description: type: string description: 'The election name which includes the jurisdiction affected by the election and a descriptor of the election type. `Localized` ' type: type: string description: Provides the election type. enum: - congressional - county - municipal - presidentialPrimary - school - state - stateHouse - stateSenate - subMunicipal pollingLocationUrl: type: string description: Lookup URL for voting location information. If an election is all-mail, this URL will link to information for election-specific dropbox locations. canonicalUrl: type: string description: 'Provides a URL to the Democracy Works data source for attribution purposes. Attribution allows voters to assess the reliability and provenance of election data and guidance. `Localized` ' website: type: string description: 'Provides a URL for voters to access additional information on the upcoming election, when available. `Localized` ' guidancePhase: type: string description: 'After an election is confirmed to be occurring, Democracy Works surfaces information about an election as details become available. An elections guidance phase describes the state of the currently available guidance. A past election is an election whose election date is in the past. A known election is an upcoming election for which key details have yet to be released. An active election is an upcoming election for which details have been vetted and confirmed by the Democracy Works team. ' enum: - past - known - active population: type: string description: Provides the affected population number for the given election using Census data or government data. This field will be null if the population is less than 5,000. voting: type: object properties: inPersonVotingAvailable: type: boolean description: Indicates whether an election has options to vote in person. mailBallotsSentAutomatically: type: boolean description: Indicates whether ballots are sent to eligible registered voters automatically in an election without voters having to request ballots themselves. early: type: object properties: url: type: string description: Provides website for voters to find out more about when and where to vote early in a specific election or provides general information about the early voting process if available. startDate: type: string description: Provides the date when early voting or absentee in person voting begins for the election in YYYY-MM-DD format if early voting or absentee in person voting is available in the election. If in person absentee voting starts as ballots are available, as opposed to a specific start date, this field will be blank and only voting.early.endDate will be returned. endDate: type: string description: Provides the date when early voting or absentee in person voting ends for the election in YYYY-MM-DD format if early voting or absentee in person voting is available in the election. varies: type: boolean description: Indicates whether early voting dates are consistent across locations and whether early voting is available every day between when early voting starts and when early voting ends. byMail: type: object properties: idInstructions: type: string description: Provides election-specific instructions for voters who choose to vote by mail. explainerUrl: type: string description: 'Provides a URL where voters can learn more about voting by mail. `Localized` ' allMail: type: object properties: ballotInfoUrl: type: string description: Provides a URL where voters can learn more about their ballot in an all mail election. ballotSendStartDate: type: string description: Provides the date in which a state will start to send mail ballots to all registered voters in an all mail election. Not collected for most all mail elections. ballotSendEndDate: type: string description: Provides the date in which a state will finish sending mail ballots to all registered voters in an all mail election. Not collected for most all mail elections. ballotReceiveExpectedStartDate: type: string description: Provides the date in which states expect voters to start receiving their mail ballots in an all mail election. Not collected for most all mail elections. ballotReceiveExpectedEndDate: type: string description: Provides the date in which states expect voters to have received their mail ballots in an all mail election. Not collected for most all mail elections. deadline: type: object properties: postmarkedOrReceived: type: string description: Provides the deadline type for whether the the voted ballot needs to be postmarked by or received by the ballot return deadline. Only collected for specific elections. receivedNoLaterThan: type: object properties: date: type: string description: Provides the last date that the election office can receive a voted ballot in the mail if the return deadline has a "must be postmarked by YYYY-MM-DD if received by YYYY-MM-DD" deadline. Only collected for specific elections. timestamp: type: string description: Provides the ISO timestamp deadline for the last day for the election office to receive a voted ballot in the mail if the return deadline has a "must be postmarked by YYYY-MM-DD if received by YYYY-MM-DD" deadline. Only collected for specific elections. description: type: string description: Provides the time deadline on the last day the election office can receive a voted ballot in the mail if the return deadline is expressed in a "must be postmarked by YYYY-MM-DD if received by YYYY-MM-DD" format if the time deadline is expressed in a phrase instead of an ISO timestamp. Examples could include "close of business" or "close of polls". Only collected for specific elections. returnInPerson: type: object properties: date: type: string description: Provides the date deadline to return a voted ballot in person. Only collected for specific elections. timestamp: type: string description: Provides the ISO timestamp deadline to return a voted ballot in person. Not collected for most elections. description: type: string description: 'Provides the time deadline to return a voted ballot in person if the deadline is expressed in a phrase instead of an ISO timestamp. Examples include "close of business" or "close of polls". Not collected for most elections. `Localized` ' returnByMail: type: object properties: date: type: string description: Provides the deadline date to return a voted ballot in the mail. Only collected for specific elections. timestamp: type: string description: Provides the ISO timestamp deadline to return a voted ballot in the mail on the last day to return a voted ballot. Not collected for most elections. description: type: string description: 'Provides the time deadline to return a voted ballot in the mail on the last day to return a voted ballot if the deadline is expressed in a phrase and not in an ISO timestamp. Examples include "close of business" or "close of polls". Only collected for specific elections. `Localized` ' ballotRequest: type: object properties: postmarkedOrReceived: type: string description: Provides the deadline type for the deadline to request a ballot by mail. Types include postmarked or received. Only collected for specific elections. date: type: string description: Provides the last date to request a ballot by mail for the election. If there are different deadlines for submitting an application in-person and by-mail, this is the by-mail application request deadline. All mail elections in which all voters receive a ballot in the mail will not have a ballot request deadline. timestamp: type: string description: Provides the ISO timestamp deadline date to request a ballot by mail for the election on the last day voters are able to do so. This time deadline is not collected for most elections. description: type: string description: 'Provides the time deadline to request a ballot by mail if the deadline is described by a phrase and not by an ISO timestamp. Examples include "close of business" or "close of polls". Only collected for specific elections. `Localized` ' inPerson: type: object properties: idRequiredAllVoters: type: boolean description: Indicates whether an ID is required for all voters. idInstructions: type: string description: Provides the election-specific instructions to vote in person including what identification voters may need to show at the voting location for states that have a voting.predominantMethod of byMail. electionDay: type: object properties: closing: type: object properties: timestamp: type: string description: Provides the ISO timestamp that in person voting closes on Election Day. Only collected for specific elections. description: type: string description: 'Provides time of day deadline that indicates when in person voting closes on Election Day when the deadline is expressed in a phrase as opposed to an ISO timestamp. Examples include "close of business" or "close of polls". Only collected for specific elections. `Localized` ' registration: type: object properties: explainerUrl: type: string description: 'Provides a URL where voters can learn more about registering to vote. `Localized` ' inPerson: type: object properties: atPollingPlaceOnElectionDay: type: boolean description: Defines whether election day registration is available for the election at all voting locations. If election day registration takes place at a location other than the voting location, this field will be "false". localSamedayRegistrationAuthorityLookupUrl: type: string description: Provides a URL where voters can look up the authority with which they can register to vote on election day. deadline: type: object properties: date: type: string description: Provides the deadline date to register in-person at the local election office for the election. timestamp: type: string description: Provides the ISO timestamp to register in-person at their local election office for the election on the last day that voters can register to vote in person at their local election office. Only collected for specific elections. description: type: string description: 'Provides the time deadline to register in-person at the local election office for the election on the last day that voters can register to vote in person at their local election office if the time deadline is a phrase as opposed to an ISO timestamp. Examples include "close of business" or "close of polls". Only collected for specific elections. `Localized` ' online: type: object properties: url: type: string description: Provides a URL with information regarding the online registration process. instructions: type: string description: 'Provides instructions for online registration. `Localized` `Formatted` ' deadline: type: object properties: date: type: string description: Provides the deadline date to register online for the election. Only applicable to elections in states that allow online voter registration. timestamp: type: string description: Provides ISO timestamp in which online voter registration closes on the online voter registration deadline. Only collected for specific elections. description: type: string description: 'Provides phrase time of day deadline that indicates when online voter registration closes on the online voter registration deadline. Example would be "close of business". Not collected for most elections. `Localized` ' byMail: type: object properties: idInstructions: type: string description: 'Provides instructions regarding ID requirements for registering to vote by mail. `Localized` `Formatted` ' signatureInstructions: type: string description: 'Provides instructions regarding signature requirements for submitting a voter registration application by mail. `Localized` `Formatted` ' newVoterInstructions: type: string description: 'Provides instructions for new voters who are submitting a voter registration application by mail. `Localized` `Formatted` ' deadline: type: object properties: date: type: string description: Provides the last date to register by mail for the election. timestamp: type: string description: Provides the ISO timestamp deadline to register by mail for the election on the last day to registrer to vote. Only collected for specific elections. description: type: string description: 'Provides the time deadline to register by mail for the election on the last day to register to vote if the deadline is expressed in a phrase as opposed to an ISO timestamp. Examples include "close of business" or "close of polls". Only collected for specific elections. `Localized` ' postmarkedOrReceived: type: string description: Defines whether a paper registration form needs to be received by or postmarked by the reg-by-mail deadline date for the election. questionAndAnswer: type: object properties: keyChanges: type: object description: 'Provides updates on key voting or registration process changes within a state. `Localized` `Formatted` ' properties: question: type: string answer: type: string keyChangesElection: type: object description: 'Provides updates on key voting or registration process changes that may be relevant to an election. `Localized` `Formatted` ' properties: question: type: string answer: type: string whoCanVote: type: object description: 'Provides the eligibility criteria for a voter to register to vote in a state. `Localized` `Formatted` ' properties: question: type: string answer: type: string voteInPerson: type: object description: 'Provides information on where to vote on Election Day, early voting, voter identification requirements, and how to check the status of your ballot if available. `Localized` `Formatted` ' properties: question: type: string answer: type: string voteByMail: type: object description: 'Provides information on whether or not an excuse is required to vote by mail, instructions on requesting and returning a ballot, instructions on how to check the status of your ballot if available, and information on what to do if you have recently moved and would like to request a ballot. `Localized` `Formatted` ' properties: question: type: string answer: type: string onlineVoterRegistration: type: object description: 'Indicates whether or not online voter registration is available. If available, provides a URL and instructions on how to register to vote online. `Localized` `Formatted` ' properties: question: type: string answer: type: string byMailRegistration: type: object description: 'Provides instructions for a voter to register to vote by mail using the National Voter Registration Form. If the National Voter Registration Form is not accepted within a state, provides instructions to register to vote by mail using the state voter registration form. `Localized` `Formatted` ' properties: question: type: string answer: type: string electionDayRegistration: type: object description: 'Indicates whether or not same day registration on Election Day is available. `Localized` `Formatted` ' properties: question: type: string answer: type: string inPersonRegistration: type: object description: 'Provides instructions on how to register to vote in person. `Localized` `Formatted` ' properties: question: type: string answer: type: string primaryRegistration: type: object description: "Provides instructions for voter registration and party affiliation requirements in partisan primary elections. \n\n`Localized` `Formatted`\n" properties: question: type: string answer: type: string primaryVote: type: object description: 'Provides instructions for voting in a primary election. `Localized` `Formatted` ' properties: question: type: string answer: type: string datesAndDeadlines: type: object description: 'Provides a summary of all voting and registration deadlines associated with an election. `Localized` `Formatted` ' properties: question: type: string answer: type: string voterId: type: object description: 'Indicates whether or not voter identification will be necessary to vote in person for all voters and provides a list of accepted voter identification. `Localized` `Formatted` ' properties: question: type: string answer: type: string whatsOnTheBallot: type: object description: 'Provides a URL to the state''s sample ballot lookup tool for statewide elections if available. If a URL isn''t available, provides a link to Ballotpedia. This will be null for local elections. `Localized` `Formatted` ' properties: question: type: string answer: type: string militaryAndOverseas: type: object description: 'Provides instructions for military and overseas voters on how to vote in an election. `Localized` `Formatted` ' properties: question: type: string answer: type: string checkRegistration: type: object description: 'Provides instructions on how to check your registration status. If available, provides a URL to check your registration status. `Localized` `Formatted` ' properties: question: type: string answer: type: string stateContactInfo: type: object description: 'Provides contact information for the office of the State Election Authority. This will be null for local elections. `Localized` `Formatted` ' properties: question: type: string answer: type: string localContactInfo: type: object description: 'Provides URL to find contact information for the office of the Local Election Authority. `Localized` `Formatted` ' properties: question: type: string answer: type: string ballotMeasures: $ref: '#/components/schemas/ballotMeasure' contests: $ref: '#/components/schemas/contest' errors: type: object properties: status: type: integer message: type: array required: - status - message contest: description: Information on the race for the specific office up for election, including the list of candidates and candidate information. type: object required: - id - name - level - districtName - ocdId - seatsUpForElection - candidates properties: id: type: string description: The ID of the contest. name: type: string description: 'The name of the office (ex: President).' level: type: string description: The level of the contest. enum: - federal - state - local branch: type: string description: The branch of government of the office. enum: - executive - judicial - legislative districtName: type: string description: The name of the district that elects the office. districtType: type: string description: The type of district that elects the office. enum: - cityTown - cityTownSubdivision - congress - county - countySubdivision - judicialDistrict - judicialDistrictSubdivision - schoolDistrict - schoolDistrictSubdivision - specialDistrict - specialDistrictSubdivision - state - stateLegislativeLower - stateLegislativeUpper - stateSubdivision contestType: type: string description: The type of contest. enum: - regular - special - recall ocdId: type: string description: The OCD-ID of the contest. seatsUpForElection: type: string description: The number of seats up for election. hasPrimary: type: boolean description: For a general election, indicates if an associated primary election exists. primaryDate: type: string description: For a general election, provides the date of the associated primary election. candidates: type: array items: $ref: '#/components/schemas/candidate' description: A list of candidates running for election for the contest. gatewayErrors: type: object properties: message: type: string required: - message ballotMeasure: description: Information on the ballot measures on the ballot, including a summary and the full text of the ballot measure. type: object required: - id - name - shortName - districtName - districtType - type - topics - summary - yesVote - noVote - ballotQuestion - ocdId properties: id: type: string description: The ID of the ballot measure. name: type: string description: The name of the ballot measure. shortName: type: string description: The concise name of the ballot measure. streamlinedName: type: string description: The ballot measure name without reference to the state name or year. districtName: type: string description: The name of the district covered by the ballot measure. districtType: type: string description: The type of district relevant to the ballot measure. enum: - cityTown - cityTownSubdivision - congress - county - countySubdivision - judicialDistrict - judicialDistrictSubdivision - schoolDistrict - schoolDistrictSubdivision - specialDistrict - specialDistrictSubdivision - state - stateLegislativeLower - stateLegislativeUpper - stateSubdivision type: type: string description: The type of ballot measure. topics: type: array items: type: string description: An array of topics covered by a ballot measure. topicAreas: type: array items: type: string description: 'An array of topic areas covered by a ballot measure. `Localized` ' summary: type: string description: Describes a summary of the ballot measure. yesVote: type: string description: Describes what a vote supporting the ballot measure means. noVote: type: string description: Describes what a vote opposed to the ballot measure means. ballotQuestion: type: string description: The full text of the ballot measure. ocdId: type: string description: The OCD-ID associated with the jurisidiction covered by the ballot measure. status: type: string examples: elections: summary: Sample elections response description: 'This is **fictional** data to provide examples of fields values. The first election has all fields populated for demonstration purposes. The second election is a more realistic example which shows that not all fields are applicable to every election. ' value: data: elections: - ocdId: ocd-division/country:us/state:wi createdAt: '2020-01-01T00:00:00.000-05:00' updatedAt: '2020-02-01T00:00:00.000-05:00' date: '2020-11-03' description: Wisconsin General Election type: state pollingLocationUrl: https://myvote.wi.gov/en-us/FindMyPollingPlace canonicalUrl: https://voting.democracy.works/en/elections/wi/2020-11-03.html website: https://myvote.wi.gov/en-us/ guidancePhase: past population: 5,880,101 voting: inPersonVotingAvailable: true mailBallotsSentAutomatically: false early: url: https://voting.democracy.works/en/elections/wi/2023-02-21.html startDate: '2023-02-07' endDate: '2023-02-19' varies: true byMail: idInstructions: 'Active military, permanent overseas voters, and confidential electors are not required to provide a Photo ID when they vote by absentee ballot. An indefinitely confined voter does not need to provide a copy of Photo ID. Instead, the witness signature on the Absentee Ballot Certificate Envelope satisfies the Photo ID requirement. For all other absentee voters, you will need to provide a copy of your acceptable photo ID with your request. If you have not previously provided a copy of photo ID, photo ID must accompany your first application by mail.

These photo IDs are acceptable and can be unexpired or expired after the date of the most recent general election: A Wisconsin DOT-issued driver license, even if driving privileges are revoked or suspended; A Wisconsin DOT-issued identification card; Military ID card issued by a U.S. uniformed service; A U.S. passport. An identification card issued by a federally recognized Indian tribe in Wisconsin; A photo identification card issued by a Wisconsin accredited university or college that contains date of issuance, expiration date no later than two years after issuance, and signature of student (must be accompanied by a separate document that proves enrollment if the student ID is expired).

These photo IDs are also acceptable for voting purposes, but must be unexpired: A veteran''s photo identification card issued by the Veterans Health Administration of the federal Department of Veterans Affairs; A certificate of naturalization that was issued not earlier than two years before the date of an election at which it is presented; A driving receipt issued by Wisconsin DOT (valid for 45 days); An identification card receipt issued by Wisconsin DOT (valid for 45 days); a temporary identification card receipt issued by Wisconsin DOT through the Identification Petition Process (IDPP) (valid for 60 days). ' explainerUrl: https://myvote.wi.gov/en-us/vote-by-mail allMail: ballotInfoUrl: https://myvote.wi.gov/en-us/ballot-info ballotSendStartDate: '2020-10-10' ballotSendEndDate: '2020-10-30' ballotReceiveExpectedStartDate: '2020-10-25' ballotReceiveExpectedEndDate: '2020-11-03' deadline: postmarkedOrReceived: received receivedNoLaterThan: date: '2020-11-14' timestamp: '17:00' description: Close of business returnInPerson: date: '2020-11-03' timestamp: '17:00' description: Close of polls returnByMail: date: '2020-11-03' timestamp: '17:00' description: Close of business ballotRequest: postmarkedOrReceived: postmarked date: '2023-02-16' timestamp: '17:00' description: Close of business inPerson: idRequiredAllVoters: true idInstructions: 'You will need to show a photo ID to vote in Wisconsin.
An acceptable photo ID is not required to contain a current address. These photo IDs are acceptable and can be unexpired or expired after the date of the most recent general election: Wisconsin DOT-issued driver license, even if driving privileges are revoked or suspended, with or without a star in the right-hand corner; Wisconsin DOT-issued identification card, with or without a star in the right-hand corner; Wisconsin DOT-issued identification card or driver license without a photo issued under the religious exemption; military ID card issued by a U.S. uniformed service; U.S. passport

The following photo ID is also acceptable for voting purposes, and can be expired before the date of the most recent general election: identification card issued by a federally recognized Indian tribe in Wisconsin; photo identification card issued by a Wisconsin accredited university or college that contains date of issuance, expiration date no later than two years after issuance, and signature of student (must be accompanied by a separate document that proves enrollment if the student ID is expired)


The following photo IDs are also acceptable for voting purposes, but must be unexpired: veteran''s photo identification card issued by the Veterans Health Administration of the federal Department of Veterans Affairs; certificate of naturalization that was issued not earlier than two years before the date of an election at which it is presented; driving receipt issued by Wisconsin DOT (valid for 45 days); identification card receipt issued by Wisconsin DOT (valid for 45 days); temporary identification card receipt issued by Wisconsin DOT through the Identification Petition Process (IDPP) (valid for 60 days)

Voters without ID: If you are unable to provide photo ID, you will be able to vote a provisional ballot. Your provisional ballot will not count unless you provide an acceptable photo ID to the poll workers by 8:00 p.m. on Election Day or to your municipal clerk in person by 4:00 p.m. the Friday after the election. ' electionDay: closing: timestamp: '17:00' description: Close of polls registration: explainerUrl: https://myvote.wi.gov/en-us/register-by-mail inPerson: atPollingPlaceOnElectionDay: true localSamedayRegistrationAuthorityLookupUrl: https://myvote.wi.gov/en-us/register deadline: date: '2023-02-17' timestamp: '17:00' description: Close of business online: url: https://myvote.wi.gov/en-us/RegisterToVote instructions: 'You should know: you need a Wisconsin driver''s license or state ID card to use Wisconsin''s online voter registration system. The address where you''re registering needs to match the address the DMV has on file for you. If you don''t have a Wisconsin ID, you can still register by mail to vote. ' deadline: date: '2023-02-01' timestamp: '17:00' description: Close of business byMail: idInstructions: 'When submitting your application by mail in Wisconsin, you are required to provide your valid and unexpired Wisconsin driver license or Wisconsin state ID number and the expiration date. If you have not been issued a Wisconsin ID, or if you have an expired, canceled, suspended, or revoked Wisconsin-issued ID, you must provide the last four digits of your Social Security number. If you have not been issued any of these numbers, check the box that indicates you do not have an ID number. You must also provide proof of residence when registering to vote. If you submit your application by mail, you must include a copy of proof of residence or submit proof of residence in an electronic format. Acceptable forms include but are not limited to: current and valid State of Wisconsin Driver License or State ID card or any official ID card or license issued by the Wisconsin government. When filling out a voter registration application, you must review the registration qualifications in Box 1. If you meet the requirements, check all of the boxes. If you do not meet all of the requirements, do not submit the form.' signatureInstructions: 'To register in Wisconsin you must:
be a citizen of the United States
be a resident of Wisconsin and have resided at the registration address for at least 28 days prior to the election
be 18 years old on or before Election Day
not have been convicted of treason, felony or bribery, or if you have, your civil rights have been restored after completion of your sentence or a pardon
not have been found by a court to be incapable of understanding the objective of the electoral process
not make or benefit from a bet or wage depending on the result of an election
not have voted at any other location, if registering on Election Day' newVoterInstructions: New voters should follow the instructions on the website to register. deadline: date: '2023-02-01' timestamp: '17:00' description: Close of business postmarkedOrReceived: postmarked questionAndAnswer: keyChanges: question: What key changes should voters know about? answer: '
Key changes to voting requirements in Wisconsin: