openapi: 3.0.2
info:
title: Democracy Works Authorities 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: <YOUR 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: Authorities
paths:
/authorities/state/{stateCode}:
get:
operationId: getStateAuthorities
summary: State authorities
description: "This endpoint includes statewide evergreen information and instructions on how to register and vote for each state (and Washington, D.C.). It includes contact information for state election authorities, registration methods, voting methods, state-specific URLs to authoritative government websites, and more. \n\nAuthorities do not contain election-specific information such as dates, and while we closely monitor this data for changes and update when needed, Authorities information generally does not change from election to election.\n\nAuthorities are returned sorted alphabetically by OCD-ID. \n\nSupports standard the following parameters: see __[Pagination](#section/Standard-Parameters/Pagination)__, __[Localization](#section/Standard-Parameters/Localization)__, and __[Content Formatting](#section/Standard-Parameters/Content-Formatting)__.\n"
security:
- ApiKeyAuth: []
parameters:
- name: stateCode
in: path
schema:
type: string
description: 'The 2-letter postal code of the state to get top-level authority for. DC is accepted as well.
If no value is provided, it will request all top-level authorities (51 total). If a value
is provided, at most one authority will be returned.
'
example: ny
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
responses:
'200':
description: Authorities fetched by query.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
authorities:
type: array
items:
$ref: '#/components/schemas/authority'
pagination:
$ref: '#/components/schemas/pagination'
examples:
sampleStateAuthoritiesResponse:
$ref: '#/components/examples/stateAuthorities'
'400':
$ref: '#/components/responses/badRequestError'
'429':
$ref: '#/components/responses/tooManyRequestsError'
'500':
$ref: '#/components/responses/internalServerError'
tags:
- Authorities
/authorities:
get:
operationId: getAuthorities
summary: All authorities
description: "This endpoint includes all statewide and local authorities that correspond to a given address or state parameter. \n\nThe statewide authorities include evergreen information and guidance on how to register and vote in that state, as well as contact information for state election authorities. Local authorities provide contact information for the local election office. \n\nAuthorities do not contain election-specific information such as dates, and while we closely monitor this data for changes and update when needed, Authorities information generally does not change from election to election.\n\nAuthorities are returned sorted alphabetically by OCD-ID. \n\nSupports the following standard parameters: see __[Pagination](#section/Standard-Parameters/Pagination)__, __[Localization](#section/Standard-Parameters/Localization)__, and __[Content Formatting](#section/Standard-Parameters/Content-Formatting)__.\n"
security:
- ApiKeyAuth: []
parameters:
- name: address
in: query
schema:
type: string
description: The address get authorities for.
example: 1101 Biscayne Blvd, Miami, FL 33132
required: false
- name: stateCode
in: query
schema:
type: string
description: 'The 2-letter postal code to get authorities within a respective state. DC is accepted as well.
'
example: CA
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
responses:
'200':
description: Authorities fetched by query. Local (non-state) authorities will only have required fields.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
authorities:
type: array
items:
$ref: '#/components/schemas/authority'
pagination:
$ref: '#/components/schemas/pagination'
examples:
sampleAuthoritiesResponse:
$ref: '#/components/examples/allAuthorities'
'400':
$ref: '#/components/responses/badRequestError'
'429':
$ref: '#/components/responses/tooManyRequestsError'
'500':
$ref: '#/components/responses/internalServerError'
tags:
- Authorities
/authorities/local:
get:
operationId: getLocalAuthorities
summary: Local authorities
description: "This endpoint provides contact information for over 8,500 local election offices at the county and municipal levels.\n\nAuthorities are returned sorted alphabetically by OCD-ID. \n\nSupports the following standard parameters: see __[Pagination](#section/Standard-Parameters/Pagination)__ and __[Localization](#section/Standard-Parameters/Localization)__.\n"
security:
- ApiKeyAuth: []
parameters:
- name: address
in: query
schema:
type: string
description: The address get authorities for.
example: 1101 Biscayne Blvd, Miami, FL 33132
required: false
- name: stateCode
in: query
schema:
type: string
description: 'The 2-letter postal code to get authorities within a respective state.
'
example: CA
required: false
responses:
'200':
description: Local authorities fetched. As all authorities will be local (non-state), they will only have required fields.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
authorities:
type: array
items:
$ref: '#/components/schemas/authority'
examples:
sampleLocalAuthoritiesResponse:
$ref: '#/components/examples/localAuthorities'
'400':
$ref: '#/components/responses/badRequestError'
'429':
$ref: '#/components/responses/tooManyRequestsError'
'500':
$ref: '#/components/responses/internalServerError'
tags:
- Authorities
components:
examples:
allAuthorities:
summary: Sample authorities response
description: 'This is **fictional** data to provide examples of fields values.
The first authority is a state authority with all fields populated for demonstration purposes.
The second authority is a local authority.
Note that state and local authorities will both be returned by this endpoint; local authorities will only return required fields, plus an extra `isRegistrationContact` field that is not returned on state authorities.
'
value:
data:
authorities:
- ocdId: ocd-division/country:us/state:al
officeName: Alabama
officialTitle: Office of the Secretary of State
homepageUrl: https://sos.alabama.gov/alabama-votes
pollingLocationUrl: https://myinfo.alabamavotes.gov/voterview
votingWithDisabilitiesUrl: https://www.sos.alabama.gov/alabama-votes/voter/assistance-disability
votingWithPastConvictionsUrl: https://www.sos.alabama.gov/sites/default/files/Voting-Rights-Final-Version.pdf
canonicalUrl: https://staging.voting.democracy.works/en/vote/al.html
partyInstructions: If you choose not to declare a political preference at the primary election, you will not be eligible to vote in any political partys primary election. You are, however, still eligible to vote on any proposed constitutional amendments that are up for a vote.
updatedAt: '2023-12-05T10:05:43.853825+00:00'
timezone: Central
secondaryTimezone: Eastern
localElectionAuthorityOfficeAlias: Absentee Election Manager
separateRegistrationAndElectionAuthorities: true
localElectionAuthorityName: Local Authority
localRegistrationAuthorityName: Board of Registrars
localRegistrationAuthorityLookupUrl: https://www.sos.alabama.gov/city-county-lookup/bor
localElectionAuthorityLookupUrl: https://www.sos.alabama.gov/city-county-lookup/absentee-election-manager
registrationAuthorityLevel: county
electionAuthorityLevel: county
contact:
phone: (334) 242-7210
email: alavoter@vote.alabama.gov
physicalAddress:
street: 600 Dexter Ave, Suite E-206
city: Montgomery
state: AL
zip: '36130'
mailingAddress:
street: P. O. Box 5616
city: Montgomery
state: AL
zip: 36103-5616
voting:
inPersonVotingAvailable: true
mailBallotsSentAutomatically: false
inPerson:
idRequiredAllVoters: true
idInstructions: 'You will need to show photo ID to vote in Alabama.<br>Acceptable
forms of valid photo ID include: Alabama driver''s license (may be expired up
to 60 days); Alabama non-driver''s ID card (may be expired up to 60 days); Alabama
photo voter ID card; digital driver''s license or non-driver ID issued by the
Alabama Law Enforcement Agency; photo ID card issued by Alabama or any other
state (examples include AL Department of Corrections Release - Temporary ID,
AL Movement/Booking Sheet from Prison/Jail System, or a pistol permit); federal
government issued ID; US passport; employee ID card issued by the federal government,
the State of Alabama, county, municipality, board or other entity in Alabama;
student or employee ID issued by a public or private college or university in
Alabama; US military ID; valid tribal ID<br><br>Voters without ID: If you are
unable to provide ID, you will be able to vote a provisional ballot. In order
for your ballot to be counted, you must provide your ID, including your address
and your telephone number, to the board of registrars no later than 5:00 P.M.
on the Friday following the election. If you fail to provide ID to the board
of registrars by that time, your ballot will not be counted. In addition, voters
who do not show valid photo ID at the polls can vote a regular ballot if they
are positively identified by two election officials as a voter on the poll list
who is eligible to vote and the election officials sign a sworn affidavit.
'
early:
supported: false
excuseRequired: false
alias: early vote
byMail:
ballotApplicationOnline: https://www.sos.alabama.gov/alabama-votes/voter/absentee-voting
returnByMailUrl: https://www.sos.alabama.gov/alabama-votes/voter/absentee-voting
eligibilityUrl: https://www.sos.alabama.gov/alabama-votes/voter/absentee-voting
returnInPersonUrl: https://www.sos.alabama.gov/alabama-votes/voter/absentee-voting
excuseRequired: true
excuses:
- excuse: absence
example: I expect to be out of the county or the state on election day.
- excuse: illnessDisability
example: I am physically incapacitated and will not be able to vote in person on election day.
- excuse: illnessAgeDisability
example: "I have a physical illness or infirmity which prevents my attendance at the polls. I am unable to access my assigned polling place due to a neurological, musculoskeletal, respiratory (including speech organs), cardiovascular, or other life-altering disorder that affects my ability to perform manual tasks, stand for any length of time, walk unassisted, see, hear or speak and: \ra) I am an elderly voter aged 65 or older; or \rb) I am a voter with a disability."
- excuse: employment
example: I expect to work a shift which has at least ten (10) hours that coincide with the polling hours at my regular polling place.
- excuse: student
example: I am enrolled as a student at an educational institution located outside the county of my personal residence and am therefore unable to vote at my usual polling place on election day.
- excuse: uocava
example: I am a member of, or a spouse or dependent of a member of, the Armed Forces of the United States or am otherwise similarly qualified to vote absentee pursuant to the Uniformed and Overseas Citizens Absentee Voting Act, 52 U.S.C. � 20302.
- excuse: electionWorker
example: I have been appointed as an election officer at a polling place which is not my regular polling place.
- excuse: caregiver
example: I am a caregiver for a family member to the second degree of kinship by affinity or consanguinity and the family member is confined to his or her home.
- excuse: incarcerated
example: I am currently incarcerated in prison or jail and have not been convicted of a felony involving moral turpitude.
ballotTrackingUrl: https://myinfo.alabamavotes.gov/voterview
ballotApplicationDownload: https://www.sos.alabama.gov/alabama-votes/absentee-ballot-applications
idInstructions: ID is required for all voters.
alias: absentee
registration:
statusUrl: https://myinfo.alabamavotes.gov/voterview
formUrl: https://www.sos.alabama.gov/sites/default/files/voter-pdfs/nvra-2.pdf
noRegistrationRequiredInstructions: You cannot vote without valid registration.
methods:
- byMail
- online
byMail:
supported: true
url: https://www.sos.alabama.gov/alabama-votes/voter/register-to-vote
forms: nvrf
raceFieldRequired: false
raceFieldInstructions: You are required to fill in this box; however, your application will not be rejected if you fail to do so.
idInstructions: If you have one, you must provide your Alabama driver's license number or Alabama non-driver's identification card number. If you do not have an Alabama driver's license or non-driver's identification card, you must provide the last four digits of your Social Security number. If you have not been issued any of these numbers you must write the word "NONE" and a unique identifier will be provided for you.
signatureInstructions: 'To register in Alabama you must: <br>be a citizen of the United States<br>be a resident of Alabama and your county at the time of registration <br>be 18 years old on or before Election Day<br>not be barred from voting by reason of a disqualifying felony conviction, or if you have been convicted, you must have had your civil rights restored. You can find the list of disqualifying felonies on the Secretary of States website here at: <a href="http://www.sos.alabama.gov/mtfelonies" target="_blank">sos.alabama.gov/mtfelonies</a><br>not have been declared mentally incompetent in a court<br>swear or affirm to "support and defend the Constitution of the U.S. and the State of Alabama and further disavow any belief or affiliation with any group which advocates the overthrow of the governments of the U.S. or the State of Alabama by unlawful means and that the information contained herein is true"'
citizenInstructions: You must be a citizen to vote in Alabama.
newVoterInstructions: 'If you are registering to vote for the first time in your jurisdiction and are mailing this registration application, federal law requires you to show proof of identification the first time you vote. Proof of identification includes: current and valid photo identification or current utility bill, bank statement, government check, paycheck or government document that shows your name and address. <br>More information <a href="https://www.eac.gov/sites/default/files/eac_assets/1/6/Federal_Voter_Registration_ENG.pdf">here</a>.'
online:
supported: true
instructions: 'You should know: you need an Alabama driver''s license or non-driver
ID to use Alabama''s online voter registration system. If you don''t have an
Alabama-issued ID, you can still register by mail to vote.
'
url: https://www.alabamainteractive.org/sos/voter_registration/voterRegistrationWelcome.action
inPerson:
supported: false
electionDayInstructions: You cannot register to vote in person on Election Day in Alabama.
advanceUrl: https://www.sos.alabama.gov/alabama-votes/voter-registration/general-info?_ga=2.13156215.1931915915.1655313501-640998901.1644592274
youthRegistration:
url: https://www.sos.alabama.gov/alabama-votes/youth-voter-registration
formUrl: https://www.sos.alabama.gov/alabama-votes/youth-voter-registration
supported: byElection
methods: online,by-mail,in-person
onlineInstructions: 'To register using the Alabama online voter registration system,
you are required to provide ONE of the following valid ID numbers: Alabama Driver''s
License; Alabama Non-Driver''s Identification card<br><br>If you dont have an
Alabama-issued ID, you can still submit a voter registration application by mail
or in person.
'
inPersonInstructions: 'You can complete a voter registration application in person at your local County Board of Registrars in Alabama. <br><br>You can also obtain a voter registration application in person at any of the following public agencies in Alabama: driver''s licensing office; county and select municipal public libraries; public four-year universities and select private four-year universities<br><br>You can find a list of locations that provide voter registration services and voter registration application on the <a href="https://www.sos.alabama.gov/alabama-votes/voter-registration/general-info">Alabama Secretary of States</a> website.'
byMailInstructions: When submitting your application by mail in Alabama, you are required to provide your Alabama Drivers License number or Alabama Non-Driver ID number. If you do not have one, you are required to 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 may send with your application a copy of your valid photo ID.
eligibilityAge: '18'
statusAvailability: Unknown
questionAndAnswer:
whoCanVote:
question: Who can register to vote?
answer: '<div>To register in Alabama you must: <ul> <li>be a citizen of the United States</li><li>be a resident of Alabama and your county at the time of registration </li><li>be 18 years old on or before Election Day</li><li>not be barred from voting by reason of a disqualifying felony conviction, or if you have been convicted, you must have had your civil rights restored. You can find the list of disqualifying felonies on the Secretary of States website here at: <a href="http://www.sos.alabama.gov/mtfelonies" target="_blank">sos.alabama.gov/mtfelonies</a></li><li>not have been declared mentally incompetent in a court</li><li>swear or affirm to "support and defend the Constitution of the U.S. and the State of Alabama and further disavow any belief or affiliation with any group which advocates the overthrow of the governments of the U.S. or the State of Alabama by unlawful means and that the information contained herein is true"</li></ul></div>'
byMailRegistration:
question: Can I submit voter registration forms by mail?
answer: '<div><div><h4>Use the National Voter Registration Form</h4><ol><li>Print and fill out the <a href="https://www.eac.gov/sites/default/files/eac_assets/1/6/Federal_Voter_Registration_ENG.pdf"> National Voter Registration Form.</a></li><li>Box 6 - ID Number: If you have one, you must provide your Alabama driver''s license number or Alabama non-driver''s identification card number. If you do not have an Alabama driver''s license or non-driver''s identification card, you must provide the last four digits of your Social Security number. If you have not been issued any of these numbers you must write the word "NONE" and a unique identifier will be provided for you.</li><li>Box 7 - Choice of Party: If you choose not to declare a political preference at the primary election, you will not be eligible to vote in any political partys primary election. You are, however, still eligible to vote on any proposed constitutional amendments that are up for a vote.</li><li>Box 8 - Race or Ethnic Group: You are required to fill in this box; however, your application will not be rejected if you fail to do so.</li><li>Review the "Who can register to vote?" section above and check that you''re eligible.</li><li>Sign the form.</li><li>Send the completed form to your <a href="https://www.sos.alabama.gov/city-county-lookup/bor">Board of Registrars</a></li><li>If you are registering to vote for the first time in your jurisdiction and are mailing this registration application, federal law requires you to show proof of identification the first time you vote. Proof of identification includes: current and valid photo identification or current utility bill, bank statement, government check, paycheck or government document that shows your name and address. <ul> <li>More information <a href="https://www.eac.gov/sites/default/files/eac_assets/1/6/Federal_Voter_Registration_ENG.pdf">here</a>.</li></ul></li></ol></div></div>'
electionDayRegistration:
question: Can I register to vote on Election Day?
answer: Alabama <em>does not</em> offer registration on Election Day.
inPersonRegistration:
question: Can I submit voter registration forms in person?
answer: <ul><li>You can also register to vote in person. Contact your <a href="https://www.sos.alabama.gov/city-county-lookup/bor">Board of Registrars</a> for information on when and where to register to vote.</li><li>Learn more by visiting the <a href="https://sos.alabama.gov/alabama-votes">Alabama Office of the Secretary of State</a>'s website or contacting your <a href="https://www.sos.alabama.gov/city-county-lookup/bor">Board of Registrars</a>.</li></ul>
youthRegistrationEligibility:
question: Can I register to vote before I turn 18?
answer: ' You can register to vote in Alabama before you turn 18 if you:<ul> <li> are at least 18 years old on or before Election Day</li><li> are a citizen of the United States</li><li> live in Alabama</li><li> have not been convicted of a disqualifying felony (or have had rights restored)</li><li> have not been legally declared "mentally incompetent" by a court</li></ul><br>You must be at least 18 years old to vote. <br> '
youthInPersonRegistration:
question: Can I complete a voter registration application in person before I turn 18?
answer: <a href="https://www.sos.alabama.gov/alabama-votes/voter-registration/general-info?_ga=2.13156215.1931915915.1655313501-640998901.1644592274">Yes, you can learn more about registering to vote in person on the Alabama Office of the Secretary of State website</a>. You can complete a voter registration application in person at your local County Board of Registrars in Alabama. <br>You can also obtain a voter registration application in person at any of the following public agencies in Alabama:<ul> <li> driver's licensing office</li><li> county and select municipal public libraries</li><li> public four-year universities and select private four-year universities</li></ul><br>You can find a list of locations that provide voter registration services and voter registration application on the <
# --- truncated at 32 KB (126 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/democracy-works/refs/heads/main/openapi/democracy-works-authorities-api-openapi.yml