openapi: 3.2.0
info:
  title: Democracy Works Endorsements 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 key of that header should be lowercase. 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: Endorsements
paths:
  /endorsements:
    get:
      operationId: getEndorsement
      summary: Endorsement
      description: 'This endpoint gets one endorsement by `endorsement id`.

        '
      security:
      - ApiKeyAuth: []
      parameters:
      - name: id
        in: path
        schema:
          type: string
          description: Hash identifier of the endorsement to get.
          example: ben_682d473ab8a590c2f1ed2d4fd8dd11c49a44b62f
        required: true
      responses:
        '200':
          description: Endorsement fetched by query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/endorsement'
              examples:
                sampleBallotMeasureEndorsementResponse:
                  $ref: '#/components/examples/bmEndorsement'
                sampleCandidateEndorsementResponse:
                  $ref: '#/components/examples/cEndorsement'
        '400':
          $ref: '#/components/responses/badRequestError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '429':
          $ref: '#/components/responses/tooManyRequestsError'
        '500':
          $ref: '#/components/responses/internalServerError'
      tags:
      - Endorsements
  /endorsements/bulk/byMatchingEntity:
    get:
      operationId: getEndorsementBulk
      summary: Endorsement Bulk
      description: 'This endpoint a list of endorsements by ballot measure or candidate id.


        You may not provide an ballot measure and candidate id at the same time.  No endorsement is associated with both a ballot measure & candidate.


        Supports the following standard parameters: see __[Pagination](#section/Standard-Parameters/Pagination)__.

        '
      security:
      - ApiKeyAuth: []
      parameters:
      - name: candidateId
        in: query
        schema:
          type: string
          description: Hash identifier of a candidate, returns all endorsements associated with this candidate.
          example: can_682d473ab8a590c2f1ed2d4fd8dd11c49a44b62f
        required: false
      - name: ballotMeasureId
        in: query
        schema:
          type: string
          description: Hash identifier of a ballot measure, returns all endorsements associated with this allot measure.
          example: bm_682d473ab8a590c2f1ed2d4fd8dd11c49a44b62f
        required: false
      responses:
        '200':
          description: Endorsement fetched by query.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/endorsement'
                  pagination:
                    $ref: '#/components/schemas/pagination'
              examples:
                sampleBallotMeasureEndorsementResponse:
                  $ref: '#/components/examples/bmEndorsements'
                sampleCandidateEndorsementResponse:
                  $ref: '#/components/examples/cEndorsements'
        '400':
          $ref: '#/components/responses/badRequestError'
        '413':
          $ref: '#/components/responses/contentTooLargeError'
        '429':
          $ref: '#/components/responses/tooManyRequestsError'
        '500':
          $ref: '#/components/responses/internalServerError'
      tags:
      - Endorsements
components:
  examples:
    bmEndorsement:
      summary: Sample ballot measure endorsements response
      description: 'This is **fictional** data to provide examples of fields values.

        '
      value:
        id: ben_92800009b57ea6d51a701ebaec4ce10be78494f3
        type: Organization
        name: Name of the Organization
        source: website
        position: 'yes'
    bmEndorsements:
      summary: Sample endorsements response by ballotMeasureId
      description: 'This is **fictional** data to provide examples of fields values.

        '
      value:
        data:
        - id: ben_92800009b57ea6d51a701ebaec4ce10be78494f3
          type: Organization
          name: Name of the Organization
          source: website
          position: 'yes'
        pagination:
          totalRecordCount: 1
          currentPage: 1
          pageSize: 10
    cEndorsement:
      summary: Sample candidate endorsements response
      description: 'This is **fictional** data to provide examples of fields values.

        '
      value:
        id: cen_92800009b57ea6d51a701ebaec4ce10be78494f3
        type: Individual-Other
        name: Individual Name
        source: website
        position: null
    cEndorsements:
      summary: Sample endorsements response by candidateId
      description: 'This is **fictional** data to provide examples of fields values.

        '
      value:
        data:
        - id: cen_92800009b57ea6d51a701ebaec4ce10be78494f3
          type: Individual-Other
          name: Individual Name
          source: website
          position: null
        pagination:
          totalRecordCount: 1
          currentPage: 1
          pageSize: 10
  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.
    contentTooLargeError:
      description: Content Too Large Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errors'
          example:
            status: 413
            message:
            - Response size too large. Try again with a smaller pageSize.
    internalServerError:
      description: InternalServerError
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errors'
          example:
            status: 500
            message:
            - Something went wrong.
    notFoundError:
      description: Not Found Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errors'
          example:
            status: 404
            message:
            - Object not found.
    tooManyRequestsError:
      description: TooManyRequestsError
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/gatewayErrors'
          example:
            message: Too Many Requests
  schemas:
    endorsement:
      description: Information regarding an endorsement for a candidate or ballot measure.
      type: object
      required:
      - id
      - name
      - source
      properties:
        id:
          type: string
          description: The ID of the endorsement.
        type:
          type: string
          description: The type of endorsement
        name:
          type: string
          description: The name of the endorsement
        source:
          type: string
          description: Origin of the endorsement
        position:
          type: string
          description: Indicates whether endorsement recommends a yes or no vote on a ballot measure endorsement
          enum:
          - 'yes'
          - 'no'
    errors:
      type: object
      properties:
        status:
          type: integer
        message:
          type: array
      required:
      - status
      - message
    gatewayErrors:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    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.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY