openapi: 3.1.0
info:
  title: FiscalNote AppData Bills Stakeholders API
  description: The FiscalNote AppData API provides access to FiscalNote's data on legislation and regulations, both past and present, in the United States and globally. It also exposes organizational data from the FiscalNote platform including issues and labels. Developers can use the API to integrate legislative tracking, regulatory monitoring, and policy analysis capabilities into their own applications and workflows.
  version: '1.0'
  contact:
    name: FiscalNote Support
    url: https://fiscalnote.com/contact
  termsOfService: https://fiscalnote.com/terms
servers:
- url: https://api.fiscalnote.com
  description: Production Server
security:
- apiKey: []
tags:
- name: Stakeholders
  description: Access stakeholder intelligence including government officials and organizational relationships.
paths:
  /policynote/v1/stakeholders:
    get:
      operationId: listStakeholders
      summary: FiscalNote List stakeholders
      description: Returns a paginated list of stakeholder records including government officials, legislators, and other key policy actors.
      tags:
      - Stakeholders
      parameters:
      - $ref: '#/components/parameters/jurisdictionParam'
      - $ref: '#/components/parameters/queryParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      responses:
        '200':
          description: A paginated list of stakeholder records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StakeholderListResponse'
        '401':
          description: Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    limitParam:
      name: limit
      in: query
      required: false
      description: Maximum number of results to return per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
    jurisdictionParam:
      name: jurisdiction
      in: query
      required: false
      description: Filter by jurisdiction code such as US, US-CA, GB, or EU.
      schema:
        type: string
    queryParam:
      name: q
      in: query
      required: false
      description: Full-text search query to filter results.
      schema:
        type: string
    offsetParam:
      name: offset
      in: query
      required: false
      description: Number of results to skip for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
  schemas:
    CommitteeRef:
      type: object
      description: A reference to a legislative committee.
      properties:
        id:
          type: string
          description: Unique identifier of the committee.
        name:
          type: string
          description: Name of the committee.
        chamber:
          type: string
          description: Chamber the committee belongs to.
    StakeholderListResponse:
      type: object
      description: Paginated response containing a list of stakeholder records.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Stakeholder'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Pagination:
      type: object
      description: Pagination metadata for list responses.
      properties:
        total:
          type: integer
          description: Total number of records matching the query.
        limit:
          type: integer
          description: Maximum number of records returned per page.
        offset:
          type: integer
          description: Number of records skipped.
        hasMore:
          type: boolean
          description: Indicates whether more records are available.
    Error:
      type: object
      description: Error response returned when a request fails.
      properties:
        code:
          type: integer
          description: HTTP status code.
        message:
          type: string
          description: Human-readable error message.
        details:
          type: string
          description: Additional details about the error.
    Stakeholder:
      type: object
      description: A government official, legislator, or other key policy stakeholder.
      properties:
        id:
          type: string
          description: Unique identifier for the stakeholder record.
        name:
          type: string
          description: Full name of the stakeholder.
        title:
          type: string
          description: Official title or position.
        party:
          type: string
          description: Political party affiliation.
        jurisdiction:
          type: string
          description: Jurisdiction the stakeholder represents or operates in.
        chamber:
          type: string
          description: Legislative chamber if applicable.
        district:
          type: string
          description: District the stakeholder represents.
        committees:
          type: array
          description: Committees the stakeholder serves on.
          items:
            $ref: '#/components/schemas/CommitteeRef'
        contactInfo:
          type: object
          description: Contact information for the stakeholder.
          properties:
            email:
              type: string
              format: email
              description: Email address.
            phone:
              type: string
              description: Phone number.
            website:
              type: string
              format: uri
              description: Official website.
        url:
          type: string
          format: uri
          description: URL to the stakeholder profile on the FiscalNote platform.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: API key provided by FiscalNote. Include in the Authorization header of each request.
externalDocs:
  description: FiscalNote AppData API Documentation
  url: https://apidocs.fiscalnote.com/apis