botso.ai API

API Howto

Step-by-step guide for external companies integrating club management, ticketing, or reporting apps with the botso.ai platform.

Getting started

  1. Request partner API access from botso.ai — you receive OAuth client credentials and a sandbox organization.
  2. Read the API reference for endpoint contracts.
  3. Implement authentication (password grant for user apps, client credentials for backend sync).
  4. Send X-Botso-Organization on every /v1/botso/* request when the user belongs to more than one club.
  5. Test against local Laravel (dashboard_v2) or your assigned sandbox tenant.
The official React client dashboard (client_dashboard_v1) is the reference implementation for request headers, error handling, and org switching.

API credentials

User-facing apps (SPA, mobile)

Use the botso Client Dashboard OAuth client — a public client_id only (no secret in the client). Users authenticate with email and password.

Server-to-server (ticketing, CRM, webhooks)

Use the botso Service Client with client_id + client_secret. Store secrets server-side only. Default scope: botso:read; write scopes assigned per partnership.

Never embed client_secret in mobile apps, browser JavaScript, or public repositories.

Your first request

1. Login
curl -X POST https://api.botso.ai/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "admin@botso.ai",
    "password": "YOUR_PASSWORD",
    "client_id": "YOUR_PUBLIC_CLIENT_ID"
  }'
2. List pools
curl https://api.botso.ai/api/v1/botso/pools \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "X-Botso-Organization: your-club-slug" \
  -H "Accept: application/json"
3. Pool overview
curl https://api.botso.ai/api/v1/botso/pools/late90s-club/overview \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "X-Botso-Organization: your-club-slug" \
  -H "Accept: application/json"
4. Daily PnL chart
curl "https://api.botso.ai/api/v1/botso/pools/late90s-club/daily-pnl?month=2026-06" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "X-Botso-Organization: your-club-slug" \
  -H "Accept: application/json"

Multi-club users

Members may belong to several organizations (e.g. two GAA clubs). After login, call GET /v1/botso/organizations/mine or read user.organizations from the login response.

Login response → organizations[] ├─ length === 1 → auto-set org slug, no header required (recommended anyway) ├─ length > 1 → user picks club → store slug → send X-Botso-Organization └─ subdomain → {slug}.botso.ai can resolve org without header

If the header is missing and the user has multiple orgs, org-scoped routes return 422 asking to select an organization.

Common integration flows

Club admin app — assign ticket after cash payment

  1. Admin logs in (password grant).
  2. GET /v1/botso/pools/{slug}/filling-pool — confirm active pool.
  3. POST /v1/botso/pools/{slug}/tickets with user_id or member_name, entry_method: "cash".
  4. Optional: POST .../payments to record the payment amount.

Member purchase — payment processor (coming soon)

Ticket checkout will run through the payment processor + ticketing API using the same Passport auth and users table. Member apps should authenticate with POST /v1/auth/login today and reserve UI for checkout once processor endpoints are published in the API reference.

Treasury — fund pool and go live

  1. Track ticket sales until funding target met.
  2. POST /v1/botso/pools/{slug}/fund with transfer reference.
  3. Pool lifecycle advances automatically when funded amount ≥ target.

Reporting — payouts and earnings

  1. GET /v1/botso/pools/{slug}/payouts — historical settlements.
  2. GET /v1/botso/pools/{slug}/earnings?user_id= — per-member totals.
  3. GET /v1/botso/audit-log — compliance trail.

Ticketing platform partners

If you operate a central ticketing system (similar to event ticketing integrations):

  • Use client credentials on your backend when issuing tickets after purchase.
  • Set entry_method: "ticketing" on ticket assignment after successful payment.
  • Store your platform payment reference in payment_note.
  • Webhook delivery from botso.ai → your system is on the roadmap; until then, poll GET .../tickets or use audit log.

Product model for tickets vs payments is documented in botso.ai/docs/PLATFORM_REFERENCE.md §3.3.

Security checklist

  • HTTPS only in production.
  • Rotate service client secrets on compromise; revoke tokens via POST /v1/auth/logout.
  • Respect permission boundaries — members cannot call org-manage endpoints.
  • Log and monitor 403 responses for integration misconfiguration.
  • Configure CORS origins with botso.ai ops (BOTSO_CORS_ORIGINS) for browser-based partners.