Back to Docs

Public API


Use the PlayerPing public API to manage players, events, and player-in-event RSVPs from your own tools and scripts. Authenticate with an API key created in Settings.


Creating an API key


  • Sign in to PlayerPing and open Settings
  • In the API Keys section, enter a name (e.g. `Zapier`) and click Create API key
  • Copy the key immediately — it is shown only once
  • Store it securely (password manager, secrets vault, environment variable)

You can have up to 10 active keys. Revoke a key anytime from Settings; revoked keys stop working immediately.


Authentication


Send your API key as a Bearer token:


Authorization: Bearer pp_live_YOUR_SECRET_KEY


All public endpoints live under `/api/v1`. Session cookies are not accepted on these routes.


Base URL


https://playerping.me/api/v1


Endpoints


Players


| Method | Path | Description |

|--------|------|-------------|

| `GET` | `/players` | List your players (includes average rating) |

| `POST` | `/players` | Create a player |

| `GET` | `/players/:id` | Get one player |

| `PATCH` | `/players/:id` | Update a player |

| `DELETE` | `/players/:id` | Delete a player |


Create / update body:


{

"name": "Alex Rivera",

"phone": "+15551234567",

"gender": "M",

"sport": "Tennis",

"email": "alex@example.com",

"clubId": "optional-club-id"

}


`name`, `phone`, `gender`, and `sport` are required. Gender must be `M`, `F`, or `OTHER`. Phone must be international format (e.g. `+15551234567`).


Events


| Method | Path | Description |

|--------|------|-------------|

| `GET` | `/events` | List non-archived events (`?archived=true` to include archived) |

| `POST` | `/events` | Create an event |

| `GET` | `/events/:id` | Get event with responses (tokens stripped) |

| `PATCH` | `/events/:id` | Update an event |

| `DELETE` | `/events/:id` | Delete an event and its responses |


Create body:


{

"date": "2026-09-01",

"time": "18:00",

"location": "Central Courts",

"sport": "Tennis",

"requiredPlayers": { "M": 2, "F": 2 },

"allowProposeTime": false,

"clubId": null

}


Optional `recurrence`: `{ "frequency": "weekly"|"biweekly"|"monthly", "endDate": "ISO", "count": N }`.


Players on an event (RSVPs)


| Method | Path | Description |

|--------|------|-------------|

| `GET` | `/events/:id/players` | List responses for the event |

| `POST` | `/events/:id/players` | Add players to the event |

| `PATCH` | `/events/:id/players/:playerId` | Update RSVP status |

| `DELETE` | `/events/:id/players/:playerId` | Remove player from event |

| `POST` | `/events/:id/waitlist/:responseId/promote` | Promote waitlisted player to YES |


Add players body:


{

"playerIds": ["player_cuid_1", "player_cuid_2"],

"notify": false,

"status": "PENDING"

}


  • By default (`notify: false`), responses are created silently (no SMS/email, no credit charge).
  • Set `notify: true` to send invitations using your notification settings. SMS/WhatsApp cost credits (same as the app); email is free. Insufficient credits return HTTP `402`.
  • `status` is only allowed when `notify` is false. Valid values: `PENDING`, `YES`, `NO`, `MAYBE`, `WAITLIST`.

Update status body: `{ "status": "YES" }`


Example: list players


curl -sS https://playerping.me/api/v1/players \

-H "Authorization: Bearer pp_live_YOUR_SECRET_KEY"


Example: create event and invite players


Create event

curl -sS -X POST https://playerping.me/api/v1/events \

-H "Authorization: Bearer pp_live_YOUR_SECRET_KEY" \

-H "Content-Type: application/json" \

-d '{

"date": "2026-09-01",

"time": "18:00",

"location": "Central Courts",

"sport": "Tennis",

"requiredPlayers": { "M": 2, "F": 2 }

}'


Add players without notifying

curl -sS -X POST https://playerping.me/api/v1/events/EVENT_ID/players \

-H "Authorization: Bearer pp_live_YOUR_SECRET_KEY" \

-H "Content-Type: application/json" \

-d '{ "playerIds": ["PLAYER_ID"], "notify": false }'


Errors


Responses use `{ "error": "message" }` with standard HTTP status codes:


  • `401` — Missing or invalid API key
  • `403` — Resource belongs to another user
  • `404` — Not found
  • `402` — Insufficient credits (when `notify: true`)
  • `400` — Validation error
  • `500` — Server error

Security


  • Treat API keys like passwords. Never commit them to source control or share them in chat.
  • Revoke compromised keys immediately in Settings.
  • Magic-link RSVP tokens are never returned by the public API.
  • API keys cannot perform admin actions.

Related guides



Previous: SettingsNext: FAQ
Back to Documentation Index