Democracy Works

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.

Documentation GitHub OpenAPI

Operations 1

GET /candidates Candidate #

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.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/democracy-works-candidates-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

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.

GitHub Google LinkedIn

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:
  responses:
    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 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.
    tooManyRequestsError:
      description: TooManyRequestsError
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/gatewayErrors'
          example:
            message: Too Many Requests
  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/
  schemas:
    gatewayErrors:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    errors:
      type: object
      properties:
        status:
          type: integer
        message:
          type: array
      required:
      - status
      - 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.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY