Connect your league software to Whistle
Send your schedule straight into Whistle's officiating marketplace, see assignments and check-ins in your own system, and keep your roster in sync. No CSV exports, no double entry.
Authentication
Every request is authenticated with a scoped API key sent as a bearer token:Authorization: Bearer whst_live_…
Keys are created from your Whistle account and come in two types: host keys work on games you host (create, edit, cancel), while organizer keys are tied to one organization and can read its schedule, assignments, and roster. Each key only has the permissions (scopes) you give it.
The full key is shown only once, when you create it, so store it somewhere safe. You can revoke a key at any time, set an expiry date, and see when it was last used.
Endpoints (v1)
| Endpoint | Scope | What it does |
|---|---|---|
GET/api/v1/games | games:read | List your games. Filter by status and start time (`from` / `to`); page through results with `limit` and `offset`. |
GET/api/v1/games/:id | games:read | Fetch a single game. |
POST/api/v1/games | games:write | Create a game (host keys only). Supports an Idempotency-Key header so retrying a failed request never creates a duplicate game. |
PATCH/api/v1/games/:id | games:write | Update game details. Editable fields depend on your key type; assigned officials are notified automatically. |
POST/api/v1/games/:id/cancel | games:write | Cancel a game. Assigned officials are notified automatically. Idempotent. |
GET/api/v1/games/:id/assignments | assignments:read | See who is covering a game: role, acceptance status, and check-in time. |
GET/api/v1/assignments | assignments:read | All assignments across your games in one call, so you do not have to request each game separately. |
POST/api/v1/games/:id/claim | assignments:write | Place one of your roster officials on an open slot (organizer keys). Whistle checks capacity, certification, and pay first, then notifies the official. |
POST/api/v1/assignments/:id/respond | assignments:write | Accept or decline a pending offer on an official’s behalf (organizer keys), for example when officials confirm through your own system. |
GET/api/v1/roster | roster:read | Your organization's active officials (organizer keys only): name, certification level, rating. |
Responses under /api/v1 keep a stable format. Breaking changes only appear under a new version, such as /api/v2.
Quick examples
Push a game from your scheduler
curl -X POST https://www.whistleapp.ca/api/v1/games \
-H "Authorization: Bearer whst_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: sched-2026-08-01-court1-1800" \
-d '{
"organization_id": "9c1f...",
"location_name": "Community Arena",
"location_address": "100 Main St",
"location_city": "Vancouver",
"location_province": "BC",
"start_time": "2026-08-01T18:00:00-07:00",
"end_time": "2026-08-01T20:00:00-07:00",
"pay_rate": 55,
"num_referees_required": 2
}'Send the same Idempotency-Key on retries and you'll get the original response back instead of a duplicate game.
Mirror your assigned schedule
curl "https://www.whistleapp.ca/api/v1/games?status=assigned&from=2026-08-01T00:00:00Z&limit=50" \
-H "Authorization: Bearer whst_live_..."Errors & rate limits
| Status | Code | Meaning |
|---|---|---|
| 401 | unauthorized | Missing, invalid, revoked, or expired API key. |
| 403 | insufficient_scope / forbidden | Your key lacks the required scope, or the operation is not allowed for its type. |
| 404 | not_found | The resource does not exist or is outside your key’s scope. |
| 409 | conflict | The resource is in a state that does not allow this operation. |
| 422 | invalid_request / idempotency_conflict | Validation failed. The details field lists each problem. |
| 429 | n/a | Too many requests. Wait for the time in the Retry-After header, then try again. |
Errors return a JSON envelope: { "error": { "code": "...", "message": "..." } }. Limits apply per key: 120 read and 30 write requests per minute.
Security & data boundaries
- Every key is limited to one organization or host account. Requests for another account's data are rejected, and automated tests check this isolation.
- Officials' personal information (contact details, addresses, check-in locations) is never exposed through the API.
- Keys are stored hashed, can be revoked instantly, and stop working automatically if their creator loses their role.
- Payment and billing data is not available through the API.
Webhooks are next
Outbound event delivery (assignment accepted, official checked in, game cancelled) is planned. If you would rather have Whistle push events to your system than poll for changes, let us know. Partner feedback decides what we build first.