botso.ai API

API Howto

Step-by-step guide for partners integrating member portals, syndicate tooling, ticketing, or reporting apps with the botso.ai platform — across enterprise, business, personal, teams, and clubs.

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

Member — create a private syndicate

  1. Member logs in (botso_access).
  2. GET /v1/botso/syndicate-availability — if can_create is false, show create disabled (sold out).
  3. POST /v1/botso/organizations with name, product_id, ticket_cap (≥ 2).
  4. Switch client context to the returned org slug (X-Botso-Organization).
  5. Invite friends via club-users / assign tickets; members buy equal-share tickets until the product is funded.

The creator is org owner immediately — no platform support step. Growth is limited by club product inventory seats, not by admin promotion.

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 — Revolut checkout

  1. Member logs in with Passport (POST /v1/auth/login).
  2. Optional: POST /v1/botso/pools/{slug}/ticket-commitments to create a pending ticket.
  3. POST /v1/botso/pools/{slug}/checkout/revolut (pool ticket) or …/checkout/revolut/capital (desk capital seat). Body may include redirect_url and product_id.
  4. Open returned checkout_url / Revolut widget with token. User completes payment.
  5. Revolut calls POST /v1/webhooks/revolut; ticket or capital seat activates. Poll GET …/tickets or payment-details if the UI needs confirmation.

Marketing shop purchases use shop auth + POST /v1/shop/checkout, then POST /v1/shop/orders/{ref}/desk-handoff for console SSO. See the API reference Checkout & Revolut section.

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 & payment partners

Native card checkout is Revolut Merchant (see API reference). If you operate a separate ticketing or CRM system:

  • Use client credentials on your backend when issuing tickets after an external purchase.
  • Set entry_method: "ticketing" (or revolut / cash / …) on POST …/tickets after successful payment.
  • Store your platform payment reference in payment_note.
  • Prefer listening for your own payment success, then call assign-ticket; or poll GET …/tickets / audit log. Platform-outbound partner webhooks remain optional.

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.