> ## Documentation Index
> Fetch the complete documentation index at: https://huddleup-sports.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List a league's officials

> Memberships with role `official` in **any** status (`pending`, `approved`, `denied`), oldest first. Filter on `status` yourself.



## OpenAPI

````yaml /api-reference/openapi.json get /leagues/{leagueId}/officials
openapi: 3.1.0
info:
  title: Whistle Partner API
  version: 1.0.0
  summary: >-
    Server-to-server REST API for Whistle — post games, manage officials, track
    payouts.
  description: >-
    Whistle's v1 partner API lets league management systems and partner
    automations create leagues and games, add and assign sports officials, read
    the payout ledger, and receive webhooks. All requests require a partner API
    key (`Authorization: Bearer whk_…`). Responses use a consistent envelope:
    success is `{"data": …}`, failure is `{"error": "<code>"}`.


    **Scoping:** partner keys are bound to a `source` namespace. A key reads and
    mutates only leagues whose `source` matches (plus leagues explicitly granted
    to it), and webhook endpoints it registered. Out-of-scope resources answer
    `404` identically to nonexistent ones — "not yours" and "not there" are
    deliberately indistinguishable. Write `source` is derived from the key: omit
    the field or echo your own value; any other value returns `400
    source_mismatch`.


    **Contract stability:** v1 response field shapes, status strings, and
    webhook event names are additive-only. Breaking changes ship as `/api/v2` —
    v1 is never mutated in place.


    **Idempotency:** `source` + `externalId` form the upsert key on leagues,
    games, and officials. Re-posting the same `(source, externalId)` updates
    instead of duplicating. Re-using a game `externalId` under a different
    league returns `409 external_id_conflict`.


    **Money:** requests take dollars (`payDollars`); responses return both
    integer cents (`payCents`, `amountCents`) and dollars. **Time:** all
    timestamps are ISO 8601 UTC (`2026-07-09T18:00:00.000Z`).


    List endpoints are not paginated and take no filter parameters (except
    `?limit=` on webhook deliveries). The API has no CORS support — it is
    server-to-server only.
  contact:
    name: HuddleUp Sports support
    email: tommy@huddleup-sports.com
    url: https://huddleup-sports.com/docs/developers
servers:
  - url: https://whistle.huddleup-sports.com/api/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Index
    description: Self-describing API index
  - name: Leagues
    description: Create, read, and update leagues
  - name: Games
    description: Batch-import games, read, update, cancel
  - name: Officials
    description: Add, approve, list, and remove officials; assign them to games
  - name: Assignments
    description: Who is covering which game
  - name: Payments
    description: Read-only payout ledger
  - name: Webhooks
    description: Register endpoints and inspect deliveries
paths:
  /leagues/{leagueId}/officials:
    parameters:
      - $ref: '#/components/parameters/leagueId'
    get:
      tags:
        - Officials
      summary: List a league's officials
      description: >-
        Memberships with role `official` in **any** status (`pending`,
        `approved`, `denied`), oldest first. Filter on `status` yourself.
      operationId: listOfficials
      responses:
        '200':
          description: Array of officials
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Official'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    leagueId:
      name: leagueId
      in: path
      required: true
      schema:
        type: string
      description: Whistle league id (`id` from league responses).
  schemas:
    Official:
      type: object
      properties:
        membershipId:
          type: string
        userId:
          type: string
          description: Whistle user id — use this for assign/remove calls.
        name:
          type: string
        email:
          type: string
          description: >-
            May be a synthesized placeholder
            (`<source>.<externalId>@partner.whistle`) when no real email was
            provided.
        status:
          type: string
          enum:
            - pending
            - approved
            - denied
        joinedAt:
          type: string
          format: date-time
      required:
        - membershipId
        - userId
        - name
        - email
        - status
        - joinedAt
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: >-
            snake_case error code. Two codes carry a parameter suffix:
            `invalid_startsAt:<value>` and `unknown_event:<name>`.
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: unauthorized
    NotFound:
      description: >-
        Resource not found **or outside your key's scope** — the two cases are
        deliberately indistinguishable (same status and code). Codes:
        `league_not_found`, `game_not_found`, `official_not_found`,
        `position_not_found`, `not_a_member`, `endpoint_not_found`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: league_not_found
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Partner API key: `Authorization: Bearer whk_…`. Keys are issued by the
        Whistle team (email tommy@huddleup-sports.com), shown once at issuance,
        and bound to your `source` namespace — they access only your leagues
        (plus explicit grants) and your webhook endpoints. Any auth failure
        returns `401 {"error":"unauthorized"}`; the API never returns 403 —
        out-of-scope resources answer 404 exactly like nonexistent ones.

````