openapi: 3.2.0 info: title: Democracy Works Elections API v1 (legacy) version: 1.0.0 description: "# Overview\nDemocracy Works collects data about elections that happen in the US.\n\nWe record this data in two entities, one called an **Election**, and one\ncalled an **Authority**.\n\nThe **Election** has election-specific dates and deadlines, URLs to get more\ninformation and take actions, and detailed instructions. The information\nincluded reflects the voter registration and voting methods available in the\nstate for that election, such as online, in-person, and by-mail registration\nas well as by-mail, in-person, and early voting. The Election also contains\nsome information from the related Authority, or Authorities in some cases.\n\nThe **Authority** includes contact information, available registration\nmethods, available voting methods, state-specific URLs, and more.\nAuthorities do not contain election-specific information such as dates, and\nAuthority information generally does not change from election to election.\n\n## Getting Started\n\nElection and Authority data is based on Open Civic Data IDs (OCD-IDs), so\nyou should familiarize yourself with how they work before jumping into the\nrest of this document.\n\n# Open Civic Data IDs (OCD IDs)\n\nBoth Authorities and Elections are identified using an Open Civic Data ID\n(OCD-ID).\n\nOCD-IDs start with what is being identified, and in our case it is always\n`ocd-division`.\n\nThen there is a tree-like structure of strings where the longer the\nidentifier gets, the more specific or fine-grained the identifier becomes.\nIn our case, there is always `country:us`, because we only cover US\nElections. We cover all 50 States, and the District of Columbia.\n\nSince all local Elections are contained within States, every OCD-ID in our\nsystem (except one) starts with `ocd-division/country:us/state:__`, where\n`__` is a two-letter state code.\n\nThe only exception to this is for the District of Columbia, which has the\nOCD-ID `ocd-division/country:us/district:dc`.\n\nAfter the state, the OCD-ID gets more specific by getting longer and using\nvarious legal jurisdiction labels to indicate what area an Election or\nAuthority is covering. Some examples are\n\n* `county:___`,\n* `place:___` (generally means municipality),\n* `parish:__` (for Louisiana),\n* `borough:__` (for Alaska),\n* `sd:__` (for School District),\n\netc.\n\nHere are some examples:\n\n* `ocd-division/country:us/state:wi/county:ashland/place:agenda`\n* `ocd-division/country:us/state:wi/county:ashland`\n* `ocd-division/country:us/state:wi`\n* `ocd-division/country:us/state:ma/place:agawam_town`\n\nSometimes a place is nested under a county, and sometimes it is not. This\ncould indicate that the municipality is in multiple counties or that there\nare multiple unique municipalities in the state with the same name but in\ndifferent counties, but not necessarily.\n\n## OCD-IDs on the Election\n\nIf a request is made like this:\n\n```bash\ncurl -H \"Accept: application/json\" -H \"Authorization: apikey $YOUR_API_KEY\" \\\n \"https://api.democracy.works/elections/upcoming?district-divisions=ocd-division/country:us/state:il/place:chicago\"\n```\n\nThe response will contain an OCD-ID here:\n\n```json\n[\n {\n \"district-divisions\": [\n {\n \"ocd-id\": \"ocd-division/country:us/state:il/place:chicago\",\n ...\n```\n\nNote: Technically there can be more than one `district-division` because the\nvalue type is a list, but in practice we only use one, so it is safe to\ntreat the first object in the list as the value.\n\n## OCD-IDs on the Authority\n\nIf a request is made like this:\n\n```bash\ncurl -H \"Accept: application/json\" -H \"Authorization: apikey $YOUR_API_KEY\" \\\n \"https://api.democracy.works/election-authorities/states\"\n```\n\nThe response will contain an OCD-ID here:\n\n```json\n {\"authorities\": [\n {\"ocd-division\": [\"ocd-division/country:us/state:il\", ...\n```\n\nThe response contains a list of `authorities`, and the OCD-ID is the first\nitem in the list under `ocd-division`.\n\n# State Authorities\n\nThere are two ways to get information on Election Authorities, and both are\nfor the state level only.\n\nInformation from State and Local Authorities is copied over to Elections, so\noften there isn’t a need to make requests for Authorities at all. The only\nfields that are not on the Election are:\n\n* Contact information (address, phone, homepage URL, etc.)\n* `voter-registration-status-url` so voters can look up there registration\n status\n* `local-election-authority-lookup-url` so voters can look up who to contact\n about registration or voting information at the local level.\n\nYou can request these URLs with the State Authority URLs resource.\n" servers: - description: Democracy Works API url: https://api.democracy.works tags: - name: Elections v1 paths: /election-authorities/state-urls/{stateAbbreviation}: get: summary: State authority URLs description: "```bash\ncurl -H \"Accept: application/json\" \\\n -H \"Authorization: apikey $YOUR_API_KEY\" \\\n \"https://api.democracy.works/election-authorities/state-urls/ny\"\n```\n\nURLs are not required, and their availability depends on the state. The\nAuthority lookup URLs may be the same, depending on the state.\n" parameters: - in: path name: stateAbbreviation required: true schema: type: string example: ny description: 'The lowercase abbreviation of the state you want to retrieve information for. ' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/StateAuthorityUrlResponse' operationId: getStateAuthorityUrls tags: - Elections v1 /election-authorities/states: get: summary: All state authorities (contact information) description: "```bash\ncurl -H \"Accept: application/json\" \\\n -H \"Authorization: apikey $YOUR_API_KEY\" \\\n \"https://api.democracy.works/election-authorities/states\"\n```\n\nThe response will be an object with a list of Authorities. Each\nAuthority will have a `district-division`, but we recommend that you\ndisregard and get that information from the Election. As a reminder, the\nElection will have `voter-registration-methods` and the `voting-methods`\ncopied from the State and Local Authorities for the methods offered in\nthat particular Election, along with dates and deadlines. The only thing\nthe `district-division` has that the Election does not is the\n`voter-registration-status-url`, which would be simpler to obtain from\nthe “State URLs” resource.\n" responses: '200': description: Successful response content: application/json: schema: type: array items: $ref: '#/components/schemas/StateAuthorityResponse' operationId: getStateAuthorities tags: - Elections v1 /elections/upcoming: get: summary: Upcoming elections description: "An “upcoming” Election is one that is in our system and the date is in\nthe future, including the day that the request is made. Both statewide\nand local Elections are part of this data set. We define a statewide\nElection as any election where all voters in the state have something on\nthe ballot or any federal congressional election. These generally end in\na two-letter state code. All other elections are considered local. \n\nThere are two ways to request Upcoming Elections:\n\n1. all at once\n2. one (or more) OCD-ID(s) at a time\n\nBe sure to include the `Accept` header because the default\n`Content-Type` is the lesser known EDN (application/edn). The two\n`Content-Type`s supported are `application/json` and `application/edn`.\n\n### All Upcoming Elections\n\nReturns a list of all upcoming elections.\n\nAn example response is available, and all field definitions are in the\nUpcoming Elections API Reference.\n\n```bash\ncurl -H \"Accept: application/json\" \\\n -H \"Authorization: apikey $YOUR_API_KEY\" \\\n https://api.democracy.works/elections/upcoming\n```\n\n### Upcoming Elections by OCD-ID\n\nReturns a list of all upcoming elections for the provided OCD-ID(s).\nSame as the above, but filtered.\n\n```bash\ncurl -H \"Accept: application/json\" \\\n -H \"Authorization: apikey $YOUR_API_KEY\" \\\n \"https://api.democracy.works/elections/upcoming?district-divisions=ocd-division/country:us/state:il/place:chicago\"\n```\n" parameters: - in: query name: district-divisions schema: type: string description: 'A **comma-separated** list, supplied as a string, of OCD IDs that will return upcoming elections only for the OCD IDs provided. ' - in: query name: language description: 'By default, responses include instructions in English. At this time we support 2 languages: English (`en`) and Spanish (`es`). Use this parameter to receive instructions in a single language. You may also use `all` to receive instructions in both English and Spanish. Note that this changes the structure of the response; any field which supports localized instructions will be an object keyed by all supported languages, exemplified by the following JSON fragment: ``` {"instructions": {"en": "...", "es": "..."}} ``` ' schema: type: string enum: - en - es - all - in: query name: qa-status schema: type: string default: complete enum: - incomplete - complete - all description: 'See [QA Status](#tag/QAStatus) for a more in-depth discussion of the meaning of this parameter. ' - in: header name: Accept schema: type: string enum: - application/json - application/edn - in: header name: Authorization schema: type: string example: apikey $YOUR_API_KEY responses: '200': description: Successful response content: application/json: schema: type: array items: $ref: '#/components/schemas/UpcomingElectionsResponse' operationId: getUpcomingElections tags: - Elections v1 components: schemas: StateAuthorityUrlResponse: type: object properties: voter-registration-status-url: type: string format: uri description: 'URL for voter to check their status ' voter-registration-status-url-shortened: type: string format: uri description: 'Shortened URL for a voter to check their status ' local-election-authority-lookup-url: type: string format: uri example: https://tvote.org/abcd123 description: 'URL for voter to contact their local Election Authority ' local-reg-authority-lookup-url: type: string format: uri description: 'URL for voter to contact their local Registration Authority ' StateAuthorityAddress: type: object properties: street: type: string description: 'Street address for state election office ' city: type: string description: 'City for state election office ' state: type: string description: 'State abbreviation ' zip: type: string description: 'Zip code for state election office ' StateAuthorityResponse: type: object required: - id properties: id: type: string description: 'Unique ID, for internal use only. ' types: type: array items: type: string enum: - election - registration - none description: "Describes whether the state handles voter registration form and/or\nballot request application processing.\n\n* `election`: state election authority processes ballot request\n applications\n* `registration`: state election authority processes voter registration\n applications\n* `none`: voter registration and ballot request applications are not\n done at the state level\n" physical-address: $ref: '#/components/schemas/StateAuthorityAddress' description: 'Lists each element of the state election office''s physical address. ' email: type: string format: email description: 'Email address for the state election office. ' phone: type: string description: 'Phone number for the state election office. ' mailing-address: $ref: '#/components/schemas/StateAuthorityAddress' description: '' official-title: type: string description: "State election office name. \n" instructions: type: object description: '' properties: party: type: string local-election-authority-lookup-url: type: string format: uri description: '' polling-place-url: type: string format: uri description: 'Provides a link to the state''s polling place lookup page. ' polling-place-url-shortened: type: string format: uri example: https://tvote.org/asdf123 description: 'Shortened version of `polling-place-url`. ' office-name: type: string description: 'Full state name ' homepage-url: type: string format: uri description: "Link to the state election website. \n" LocalizedField: oneOf: - type: object properties: en: type: string description: English text es: type: string description: Spanish text - type: string description: Localized text dependent on the `language` parameter ByMailVotingMethod: type: object required: - type - primary properties: type: type: string enum: - by-mail primary: type: boolean description: 'Indicates whether voting by mail is the primary voting method for the particular election or not. `true`: primary voting method; `false`: not primary voting method. ' ballot-request-form-url: $ref: '#/components/schemas/LocalizedField' description: 'URL for a form that a voter can use to request an absentee/by-mail ballot. ' ballot-request-deadline-received: type: string format: date-time description: 'Indicates the date that a ballot request application must be received by the designated election official for the particular election. This [timestamp should be interpreted as a date](#tag/DateAsTimestamp). ' ballot-return-deadline-postmarked: type: string format: date-time description: 'Indicates the date that a completed ballot must be postmarked by the voter for the particular election. This [timestamp should be interpreted as a date](#tag/DateAsTimestamp). ' ballot-return-deadline-received: type: string format: date-time description: 'Indicates the date that a completed ballot must be received by the designated election official for the particular election. This [timestamp should be interpreted as a date](#tag/DateAsTimestamp). ' ballot-return-deadline-in-person: type: string format: date-time description: 'Indicates the date that a completed ballot must be returned in-person by the voter at a designated election office/dropbox for the particular election. This [timestamp should be interpreted as a date](#tag/DateAsTimestamp). ' vbm-alias: $ref: '#/components/schemas/LocalizedField' description: 'The name used by the jurisdiction to refer to voting by mail. ' excuse-required: type: boolean description: 'Indicates whether you need an excuse to vote by-mail. `true`: excuse required; `false`: excuse not required. ' acceptable-forms: type: array description: 'Lists the acceptable ballot request application form. ' items: type: object properties: name: type: string description: 'For internal use only. Name for the ballot request application. ' EarlyVotingVotingMethod: type: object required: - type properties: type: type: string enum: - early-voting description: 'Indicates that early voting is an option for the particular election. The sections following provide the state-specific requirements. This field and fields associated with early voting are only populated in states where it is available. ' primary: type: boolean description: 'Indicates whether voting early is the primary voting method for the particular election or not. `true`: primary voting method; `false`: not primary voting method. ' excuse-required: type: boolean description: 'Indicates whether you need an excuse to vote early. `true`: excuse required; `false`: excuse not required. ' start: type: string format: date-time description: 'Indicates the start date for early voting for the particular election. Early voting dates often vary within a state. This date can either be the earliest date or the latest date any jurisdiction is required to begin. This [timestamp should be interpreted as a date](#tag/DateAsTimestamp). ' end: type: string format: date-time description: 'Indicates the end date for early voting for the particular election. Early voting dates often vary within a state. This date can either be the earliest day or the latest date any jurisdiction is required to end. This [timestamp should be interpreted as a date](#tag/DateAsTimestamp). ' alias: type: string enum: - early-voting - absentee-in-person description: 'Default is empty, meaning election officials in the state use the term "early voting" or the value can explicitly list `early-voting`. If the value is `absentee-in-person` that means election officials in the state use the term "absentee in person". We don''t distinguish these two in the data because they are functionally equivalent. ' exact-dates: type: boolean deprecated: true description: Deprecated field as we reconsider date display. url: type: string format: uri description: 'If there is a website that provides information about the election or how to participate, we will provide it here. This field is often an election-specific URL, though we may include voter information portals. ' InPersonVotingMethod: type: object required: - type - primary properties: type: type: string enum: - in-person description: 'Indicates that voting in-person is an option for the particular election. The sections following provide the state-specific requirements. This field, and fields associated with voting in-person, are not available in Oregon. ' primary: type: boolean description: 'Indicates whether voting in person is the primary voting method for the particular election or not. `true`: primary voting method; `false`: not primary voting method. ' excuse-required: type: boolean description: "Indicates whether you need an excuse to vote in-person. `true`:\n excuse required; `false`: excuse not required.\n" instructions: type: object description: 'Lists the state-specific requirements for voting in-person. See [our notes on instruction fields](#tag/Instructions) for more information on interpreting these fields. ' properties: voting-id: description: 'Provides the identification requirements and other instructions for voting in-person. ' $ref: '#/components/schemas/LocalizedField' ByMailRegistrationMethod: type: object properties: type: type: string enum: - by-mail description: 'Indicates that registering to vote by mail is an option for the particular election. The sections following provide the state-specific requirements. This field, and fields associated with registering to vote by mail are not available for elections in New Hampshire or North Dakota. ' instructions: type: object description: 'Lists the state-specific signature block language and ID requirements for registering to vote by mail. ' properties: signature: description: 'Provides the state-specific language for voters to affirm when they complete and sign their paper registration form. This language varies from state to state. ' $ref: '#/components/schemas/LocalizedField' idnumber: description: 'Provides the state-specific identification requirements for registering to vote by mail. ' $ref: '#/components/schemas/LocalizedField' acceptable-forms: type: array description: 'Lists the paper registration form accepted by the state. ' items: type: object properties: name: type: string description: 'Display name for the state-accepted registration form. Most states accept the National Voter Registration Form (`nvrf`). Voters in Wyoming must use the state-specific registration form (`wy_reg`). This field is left blank in New Hampshire and North Dakota. ' deadline-received: type: string format: date-time description: 'Indicates that a by mail voter registration application must be received by the designated election office by the deadline date for the particular election. This [timestamp should be interpreted as a date](#tag/DateAsTimestamp). ' deadline-postmarked: type: string format: date-time description: 'Indicates that a by mail voter registration applications must be postmarked by the deadline date for the particular election. This [timestamp should be interpreted as a date](#tag/DateAsTimestamp). ' deadline-in-person: type: string format: date-time description: 'Indicates that a by mail voter registration must be delivered/completed in person (by the voter) by the deadline date for the particular election. This [timestamp should be interpreted as a date](#tag/DateAsTimestamp). ' new-voter: type: string ElectionDayRegistrationMethod: type: object properties: type: type: string enum: - election-day description: 'Indicates whether voter registration is available for the particular election at voting locations. ' InPersonRegistrationMethod: type: object properties: type: type: string enum: - in-person description: 'Indicates that in-person voter registration is an option in the state. This field and fields associated with in-person voter registration are only populated in states where it is available. ' start: type: string format: date-time description: 'This [timestamp should be interpreted as a date](#tag/DateAsTimestamp). ' end: type: string format: date-time description: 'This [timestamp should be interpreted as a date](#tag/DateAsTimestamp). ' OnlineRegistrationMethod: type: object properties: type: type: string enum: - online description: 'Indicates that online voter registration is an option in the state. The sections following provide the state-specific requirements. This field and fields associated with online voter registration are only populated in states where it is available. ' instructions: type: object description: 'Lists the state-specific requirements for registering to vote online. ' properties: registration: description: 'Provides the identification requirements and other instructions for registering to vote online. ' $ref: '#/components/schemas/LocalizedField' supports-iframe: type: boolean description: 'Indicates whether the state online voter registration site can be iframed. `true`: can be iframed, `false`: cannot be iframed. ' deadline-online: type: string format: date-time description: 'Provides the deadline date for registering online to vote for the particular election. This [timestamp should be interpreted as a date](#tag/DateAsTimestamp). ' url: type: string format: uri description: 'Provides the link to the state online voter registration system. ' DistrictDivision: type: object properties: ocd-id: type: string example: ocd-division/country:us/state:nc/sldl:1 description: 'The political division of the election. Represented as an Open Civic Data Identifier. Voters within these political jurisdictions are covered by this election. ' voter-registration-authority-level: type: string election-authority-level: type: string voting-methods: type: array items: anyOf: - $ref: '#/components/schemas/ByMailVotingMethod' - $ref: '#/components/schemas/EarlyVotingVotingMethod' - $ref: '#/components/schemas/InPersonVotingMethod' voter-registration-methods: type: array items: anyOf: - $ref: '#/components/schemas/ByMailRegistrationMethod' - $ref: '#/components/schemas/ElectionDayRegistrationMethod' - $ref: '#/components/schemas/InPersonRegistrationMethod' - $ref: '#/components/schemas/OnlineRegistrationMethod' primary-voting-method-source: type: string UpcomingElectionsResponse: type: object required: - date - description - type - id - qa-status properties: description: type: string description: 'Displayable name for the election. Includes the political division affected by the election and the election type. Descriptions can also provide information on whether the election will be conducted via mail ballot if elections are not typically conducted that way in the state. ' date: type: string format: date-time description: 'Day of the election. This [timestamp should be interpreted as a date](#tag/DateAsTimestamp). ' example: '2022-11-08T00:00:00Z' district-divisions: type: array items: $ref: '#/components/schemas/DistrictDivision' type: type: string enum: - congressional - county - municipal - presidential-primary - school - state - state-house - state-senate - sub-municipal description: The election type source: type: object description: 'Information about how the Election was researched. For internal use only. ' properties: type: type: string notes: type: string date: type: string format: date-time polling-place-url: type: string format: uri description: Provides a link to the state's polling place lookup page. polling-place-url-shortened: type: string format: uri example: https://tvote.org/abcd123 description: Shortened link for the state's polling place lookup page. qa-status: type: string enum: - complete - incomplete - none description: 'Only `complete` elections are shown in the API by default, but early access to `incomplete` data is available. See [QA Status](#tag/QAStatus) for more discussion. ' id: type: string description: 'Unique election ID for internal use only. This value may change. ' population: type: integer description: 'Provides the affected population number for the given election using Census data, when available. ' website: type: string format: uri description: 'Provides a link to additional information on the upcoming election, when available. '