20FIT

Open API

REST API for your organizer data — reads plus scoped catalog writes — with signed webhooks. Base URL: https://ticket.20fit.id/api/v1

Authentication

Create keys in your dashboard → Developers. Send them as a bearer token:

curl https://ticket.20fit.id/api/v1/events \
  -H "Authorization: Bearer sk_live_xxx.yyy"
  • pk_ publishable keys → events:read only.
  • sk_ secret keys → scoped organizer reads + add-on consumption (addons:write). Catalog writes need events:write. Keep them server-side.
  • Rate limit: 120 requests / minute / key on /api/v1 (240 on /api/embed/v1). Every response — success or error, including 401/403 — carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy; a 429 adds Retry-After.
  • Failed authentication: requests with a missing or invalid key are limited to 30 / minute / client IP on each plane (/api/v1, /api/embed/v1). Once exhausted, the plane answers 429 with Retry-After until the window resets. Requests with a valid key never count toward this limit.
  • Public endpoints (quote, reserve, OTP) are limited per IP with the same headers.

Endpoints

MethodPathScopeDescription
GET/v1/eventsevents:readList your events with ticket types and poster URL (posterUrl). Publishable keys return published events only.
GET/v1/ordersorders:readList orders. Query: ?status=paid&limit=50 (max 100).
GET/v1/orders/{orderNumber}orders:readOrder detail with fee breakdown, items, tickets. Keys granted orders:read:pii (not a default — ask 20FIT) also get buyer {email, name, phone} and per ticket holderName, bib, category and qrValue (static QR content the gate accepts); each such read is audited.
GET/v1/ticketstickets:readList issued tickets. Query: ?eventId=&status=&limit= (max 200).
GET/v1/settlementssettlements:readPer-event settlement accounting. Query: ?eventId=&limit= (max 200).
GET/v1/addonsaddons:readPurchased add-ons / consumable entitlements. Query: ?email=&eventId=&type=&consumed=&limit= (max 200).
POST/v1/addons/consumeaddons:writeConsume N units of an entitlement (idempotent per ref).
POST/PATCH/v1/events, /v1/events/{id}, …/ticket-types, …/addonsevents:writeCatalog writes (create/update/archive). Not granted by default — ask 20FIT to enable it on your key.

Webhooks

Register an endpoint in Developers. We POST events (e.g. order.paid) with a signature header:

X-20FIT-Signature: t=1720000000,v1=<hex hmac>
// verify: HMAC_SHA256(secret, `${t}.${rawBody}`) === v1

Reject requests where the timestamp is older than ~5 minutes to prevent replay.