Learn more about the App platform project.
SpotTheSplat API v2.3
Base URL: https://spotthesplat.fly.dev/api/v2
Authentication
All endpoints require the X-API-Key header unless marked as public.
Header: X-API-Key: your-api-key
Endpoints
Core
Platform health, organisations, activities, and user management.
/health/Health checkReturns service status. Use to verify the API is running.
/organisations/List organisationsReturns all organisations registered on the platform with name, subdomain, and branding.
/activities/List activitiesReturns app instances (activities) for organisations. Each activity links an app to an organisation.
| Parameter | Type | Required | Description |
|---|---|---|---|
org | string | No | Filter by organisation subdomain |
/user/Check user existsCheck if a Django user account exists for the given email address.
| Parameter | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Email address to look up |
Authentication
Social sign-in flows for mobile apps and WordPress plugins. Google and Apple are supported; Facebook is planned.
/auth/google/mobile/Google mobile sign-inPublicExchange a Google ID token (from native Google Sign-In) for an opaque bearer session token. The token is returned alongside the member's profile and organisation.
| Parameter | Type | Required | Description |
|---|---|---|---|
id_token | string | Yes | Google ID token from the mobile SDK |
/auth/apple/mobile/Apple mobile sign-inPublicExchange an Apple identity token (from ASAuthorizationAppleIDCredential) for a bearer session token. Audience must match the app's bundle ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
identity_token | string | Yes | Apple identity token JWT from the iOS SDK |
first_name | string | No | First name (Apple only provides this on first sign-in) |
last_name | string | No | Last name (Apple only provides this on first sign-in) |
/auth/apple/web/start/Apple web sign-in (start)PublicRedirects the browser to Apple's authorize URL. Used by WordPress plugins to initiate Sign in with Apple. Apple POSTs back to the callback endpoint.
| Parameter | Type | Required | Description |
|---|---|---|---|
return_to | string | Yes | HTTPS URL to redirect back to after Apple auth (e.g. the WP callback page) |
/auth/apple/web/Apple web sign-in (callback)PublicReceives Apple's form_post callback with an authorization code + state. Exchanges the code for tokens, verifies the ID token, finds the member, and redirects back to the return_to URL with a signed payload (ok, email, expires, sig). If the member is not found, ok=false and apple_sub is included for linking.
| Parameter | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Authorization code from Apple (form-posted) |
state | string | Yes | HMAC-signed state containing the return URL (form-posted) |
/auth/apple/link/start/Apple link account (start)PublicFor Hide-My-Email Apple users whose relay email doesn't match a membership. Sends a verification email to the provided club email. The email contains a signed link that binds the Apple subject to the membership.
| Parameter | Type | Required | Description |
|---|---|---|---|
apple_sub | string | Yes | Apple subject identifier from the failed sign-in |
email | string | Yes | The member's club email address |
return_to | string | Yes | HTTPS URL to redirect to after verification |
/auth/apple/link/verify/Apple link account (verify)PublicConsumes a signed link token from email, binds apple_subject to the membership, and redirects back to the WP site with ok=true.
| Parameter | Type | Required | Description |
|---|---|---|---|
token | string | Yes | HMAC-signed link token from the verification email |
return_to | string | Yes | HTTPS URL to redirect to after successful linking |
Members
Member directory and verification for SSO-protected content.
/members/List all membersReturns all active members with name, email, mobile, member type, access role, and organisation.
/members/verify/Verify membershipChecks if an email belongs to an active member. Used by WordPress plugins to gate content behind Google SSO.
| Parameter | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Email address to verify |
Groups & Positions
Member groups (committees, teams), organisational positions (President, Secretary), and year-scoped assignments. Used for access control, leadership displays, and committee listings.
/groups/List groupsReturns all active member groups for the organisation.
/groups/{id}/members/Group membersReturns members of a group for a given year, including ongoing (year-less) memberships. Includes role_label for each member.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | Group ID |
year | string | No | OrgYear label (e.g. '2025-26') or 'current' (default) |
/groups/{id}/team/Group team with positionsReturns group members enriched with their position assignments. Members are derived from both explicit MemberGroupMembership and PositionAssignments where the position is scoped to this group. Sorted by position display_order. Also returns all OrgYears for a year picker.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | Group ID |
year | string | No | OrgYear label or 'current' (default) |
/groups/all-teams/All groups with teamsReturns every active group for the organisation, each with its members and positions for the given year. Groups sorted by display_order; members within each group sorted by position display_order then last name. Designed for committee overview pages.
| Parameter | Type | Required | Description |
|---|---|---|---|
year | string | No | OrgYear label or 'current' (default) |
org | integer | No | Organisation ID (required when using the global API key) |
/officers/Current officersReturns all positions for the organisation with their current holders. Designed for 'Meet the Team' displays. Positions are ordered by display_order.
| Parameter | Type | Required | Description |
|---|---|---|---|
year | string | No | OrgYear label or 'current' (default) |
Notices
Organisation announcements and events with date-ranged visibility.
/notices/List active noticesReturns notices currently within their visibility window. Includes title, description, event date/time, price, contact details, and access level.
/notices/{id}/qr/Notice QR codeReturns a QR code PNG image encoding the notice's website URL.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | Notice ID |
Calendar
ICS calendar feed integration for club/organisation calendars.
/calendar/events/Get calendar eventsFetches and parses the ICS feed configured for the given activity. Returns events with name, start, end, location, description, and access level.
| Parameter | Type | Required | Description |
|---|---|---|---|
activity_id | integer | Yes | Activity ID with calendar config |
Events
Organisation events with maps, QR codes, and per-event access control.
/events/List eventsReturns published events with date, time, location, description, website, QR code URL, and access level.
| Parameter | Type | Required | Description |
|---|---|---|---|
org | string | No | Filter by organisation subdomain |
upcoming | boolean | No | Set to 'true' to show only future events |
/events/{id}/qr/Event QR codePublicReturns a QR code PNG image encoding the event's website URL.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | Event ID |
Breakfast
Breakfast meeting RSVP system with choice selection, guest bookings, and reports.
/breakfast/events/Next breakfast eventPublicReturns the next upcoming breakfast event with title, date, time, and location.
/breakfast/submit/Submit breakfast bookingPublicSubmit a breakfast choice for an event. Validates the choice code.
| Parameter | Type | Required | Description |
|---|---|---|---|
event_id | integer | Yes | Breakfast event ID |
email | string | Yes | Member email |
breakfast_choice | string | Yes | Choice code: full, continental, bacon, none, apology |
/breakfast/{org_slug}/current/Current breakfast statusReturns the current breakfast activity for the organisation, including deadline and the member's latest choice.
| Parameter | Type | Required | Description |
|---|---|---|---|
org_slug | string | Yes | Organisation subdomain |
email | string | Yes | Member email |
/breakfast/{org_slug}/{activity_id}/submit/Submit or update choiceSubmit or change a breakfast choice. Validates deadline, normalises choice codes, supports guest bookings.
| Parameter | Type | Required | Description |
|---|---|---|---|
org_slug | string | Yes | Organisation subdomain |
activity_id | integer | Yes | Activity ID |
email | string | Yes | Member email |
breakfast_choice | string | Yes | Choice code |
bringing_guest | boolean | No | Set to true if bringing a guest |
guest_first_name | string | No | Guest first name |
guest_last_name | string | No | Guest last name |
guest_breakfast_choice | string | No | Guest choice code |
/breakfast/{org_slug}/{activity_id}/report/Breakfast attendance reportFull attendance report listing all members with their choices and summary totals.
| Parameter | Type | Required | Description |
|---|---|---|---|
org_slug | string | Yes | Organisation subdomain |
activity_id | integer | Yes | Activity ID |
Charities & Funders
Directory of charities and grant funders, filterable by UK county.
/charities/List charitiesReturns charities with Charity Commission data, income, contact details, areas served, and tags.
| Parameter | Type | Required | Description |
|---|---|---|---|
county | string | No | UK county code (e.g. bedfordshire) |
org | string | No | Filter by organisation subdomain |
tag | string | No | Filter by tag (e.g. homelessness) |
search | string | No | Search name, description, and address |
/funders/List fundersReturns grant funders with type, geographic focus, grant range, eligibility, and how to apply.
| Parameter | Type | Required | Description |
|---|---|---|---|
county | string | No | UK county code |
org | string | No | Filter by organisation subdomain |
search | string | No | Search name, notes, and eligibility |
Alpaca Portfolio
Alpaca paper/live trading portfolio for club investment activities. Data is server-cached for 5 minutes per activity.
/alpaca/{activity_id}/Portfolio snapshotReturns the cached Alpaca portfolio for an activity: account summary (equity, cash, buying power), open positions, recent orders (last 10), and intraday portfolio history (5-min intervals). Refreshes from Alpaca if the cache is older than 5 minutes. Respects per-member access control via ActivityMemberAccess and ActivityGroupAccess.
| Parameter | Type | Required | Description |
|---|---|---|---|
activity_id | integer | Yes | Activity ID (must be an Alpaca Portfolio activity with credentials configured) |
member_email | string | No | Member email for access check (used by WP plugins; mobile apps use the Bearer token instead) |
QuickBooks Online
Integration with QuickBooks Online for bank balances and balance sheet. Requires OAuth2 connection per organisation.
/qbo/connect/Connect to QuickBooks (OAuth start)PublicInitiates the QBO OAuth2 flow. Redirects the browser to Intuit's authorisation page. The organisation must have a QboConnection with Client ID and Secret configured in Django admin first.
| Parameter | Type | Required | Description |
|---|---|---|---|
org | integer | Yes | Organisation ID |
/qbo/callback/QuickBooks OAuth callbackPublicIntuit redirects here after authorisation. Exchanges the authorisation code for access and refresh tokens, stores the realm_id (QBO Company ID), and confirms the connection.
| Parameter | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Authorisation code from Intuit |
state | string | Yes | HMAC-signed state for CSRF protection |
realmId | string | Yes | QBO Company ID |
/qbo/{org_id}/summary/Finance summaryReturns cached bank account balances and a simplified balance sheet (one level deep with sub-sections). Data is refreshed from QBO if the cache is older than 5 minutes. Access tokens are auto-refreshed if expired.
| Parameter | Type | Required | Description |
|---|---|---|---|
org_id | integer | Yes | Organisation ID (must have a connected QboConnection) |
Audit
User action logs, model change logs, web sign-in tracking, and member platform access summary.
/audit/actions/Action logsReturns custom action logs (sign-ins, page views, connections) for the organisation. Paginated with limit and offset.
| Parameter | Type | Required | Description |
|---|---|---|---|
org | integer | No | Organisation ID (required when using the global API key) |
limit | integer | No | Max results (default 50, max 200) |
offset | integer | No | Pagination offset (default 0) |
/audit/changes/Model change logsReturns django-auditlog model change logs (create/update/delete) with field-level old and new values. Paginated.
| Parameter | Type | Required | Description |
|---|---|---|---|
org | integer | No | Organisation ID (required when using the global API key) |
limit | integer | No | Max results (default 50, max 200) |
offset | integer | No | Pagination offset (default 0) |
/audit/web-signin/Track web sign-inCalled by the WordPress plugin after a successful sign-in to record web platform access for audit tracking.
| Parameter | Type | Required | Description |
|---|---|---|---|
email | string | Yes | The signed-in member's email address |
/audit/member-access/Member platform accessReturns all active members with their platform access status (web, iOS, Android) and counts. Used by the Member Access summary table.
| Parameter | Type | Required | Description |
|---|---|---|---|
org | integer | No | Organisation ID (required when using the global API key) |
Communications
Channel-agnostic message dispatch system. Email channel working via Resend; push, WhatsApp, and SMS channels planned.
/comms/send/Send messageCompose and immediately dispatch a message to all org members, a group, or explicit recipients via the specified channel. Per-org API key required.
| Parameter | Type | Required | Description |
|---|---|---|---|
channel | string | Yes | Channel type: email, push, whatsapp, or sms |
subject | string | No | Email subject or push notification title |
body | string | Yes | Message body (HTML for email, plain text for push/SMS) |
body_plain | string | No | Plain text fallback for email |
target_all_members | boolean | No | Send to all active members (default false) |
target_group_id | integer | No | Send to members of this group |
source_app | string | No | Which app triggered the message (e.g. breakfast, notices) |
/comms/history/Message historyReturns sent message history for the organisation with recipient counts and delivery status. Paginated.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | integer | No | Max results (default 20, max 100) |
offset | integer | No | Pagination offset (default 0) |
Reference: Breakfast Choices
full Full English Breakfast (Cook)continental Continental Breakfast (Cont)bacon Bacon Sandwich (Bacon)none No Breakfast (None)apology Apologies (Apol)SpotTheSplat API v2.3 — Schema auto-generated from /api/v2/schema/
