Democracy Works Candidates API
The Candidates API from Democracy Works — 1 operation retrieving a single candidate by id, with party affiliation, incumbency, write-in status, running mate, ranked-choice round and Ballotpedia link.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/democracy-works:democracy-works-candidates-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Democracy Works Candidates API
version: '2.0'
description: '# Introduction
The 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.'
servers:
- url: https://api.democracy.works/v2
tags:
- name: Candidates
paths:
/candidates:
get:
operationId: getCandidate
summary: Candidate
description: This endpoint gets one candidate by `id`.
security:
- ApiKeyAuth: []
parameters:
- name: id
in: path
schema:
type: string
description: Hash identifier of the candidate to get.
example: can_6669354db52bcd7c83d732ffa7e006a81aabba0e
required: true
responses:
'200':
description: Candidate fetched by query.
content:
application/json:
schema:
$ref: '#/components/schemas/candidate'
examples:
sampleCandidateResponse:
$ref: '#/components/examples/candidates'
'400':
$ref: '#/components/responses/badRequestError'
'404':
description: Not Found Error
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
example:
status: 404
message:
- Candidate not found.
'429':
$ref: '#/components/responses/tooManyRequestsError'
'500':
$ref: '#/components/responses/internalServerError'
tags:
- Candidates
components:
schemas:
errors:
type: object
properties:
status:
type: integer
message:
type: array
required:
- status
- message
gatewayErrors:
type: object
properties:
message:
type: string
required:
- message
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
isIncumbent:
type: boolean
description: Indicates whether a candidate is an incumbent.
isWriteIn:
type: boolean
description: Indicates whether a candidate is a write-in candidate.
ballotpediaUrl:
type: string
description: The URL of the candidate's Ballotpedia page.
status:
type: string
description: The status of the candidate in that contest.
enum:
- won
- lost
- advanced
- declared
- disqualified
- onBallot
- withdrew
- notable
- acclaimed
- withdrewStillOnBallot
runningMateFullName:
type: string
description: The full name of the candidate's running mate.
runningMateTitle:
type: string
description: The title of the candidate's running mate.
rankedChoiceVotingRound:
type: number
description: RCV results are reported in “rounds” of calculations. Ballotpedia reports each round of these results, so a candidate in an RCV will have a row for each round of calculation in that stage. The first round of results reported will have this attribute = 1. Rounds will count up until the final round.
endorsementCount:
type: number
description: The number of endorsements available for this candidate.
contact:
type: object
properties:
campaign:
type: object
properties:
email:
type: string
description: The candidate’s campaign email address.
website:
type: string
description: The candidate’s campaign website.
facebook:
type: string
description: The candidate’s campaign Facebook.
twitter:
type: string
description: The candidate’s campaign Twitter.
instagram:
type: string
description: The candidate’s campaign Instagram.
youtube:
type: string
description: The candidate’s campaign YouTube.
mailingAddress:
type: string
description: The candidate’s campaign mailing address.
phone:
type: string
description: The candidate’s campaign phone number.
personal:
type: object
properties:
website:
type: string
description: The candidate’s personal website.
facebook:
type: string
description: The candidate’s personal Facebook.
twitter:
type: string
description: The candidate’s personal Twitter.
instagram:
type: string
description: The candidate’s personal Instagram.
youtube:
type: string
description: The candidate’s personal YouTube.
linkedIn:
type: string
description: The candidate’s personal LinkedIn.
examples:
candidates:
summary: Sample Candidate response
description: 'This is **fictional** data to provide examples of fields values.
'
value:
data:
candidates:
id: can_92800009b57ea6d51a701ebaec4ce10be78494f3
fullName: Jesse Lee Gunn
firstName: Jesse
lastName: Gunn
partyAffiliation:
- Nonpartisan
isIncumbent: false
isWriteIn: false
ballotpediaUrl: https://ballotpedia.org/Jesse_Lee_Gunn
status: lost
runningMateFullName: null
runningMateTitle: null
rankedChoiceVotingRound: null
endorsementCount: 1
contact:
campaign:
email: jg4act@gmail.com
website: https://www.jesse2024.com/
facebook: https://www.facebook.com/jesse4transit
twitter: null
instagram: https://www.instagram.com/jesse4transit
youtube: null
mailingAddress: 510 Schafer Road Hayward CA 94544
phone: 510-512-4236
personal:
website: null
facebook: https://www.facebook.com/jesse4transit
twitter: jessegunnmath
instagram: null
youtube: https://www.youtube.com/@jessegunn5994
linkedIn: https://www.linkedin.com/in/jesse4transit/
responses:
badRequestError:
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
example:
status: 400
message:
- Something has gone wrong parsing your request. 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.
internalServerError:
description: InternalServerError
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
example:
status: 500
message:
- Something went wrong.
tooManyRequestsError:
description: TooManyRequestsError
content:
application/json:
schema:
$ref: '#/components/schemas/gatewayErrors'
example:
message: Too Many Requests
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY