Version 1
API reference
Use your assigned deployment origin as the base URL. Secret-key endpoints are server-to-server. The public widget and OpenAPI routes have their own narrower browser rules. Integer monetary amounts are NGN kobo.
Download OpenAPI 3.1The contract is assembled from implemented phase schemas. It excludes private administration and scheduler routes. Configuration/permissions and sandbox acceptance are separate from endpoint availability.
GET/api/v1/integration
Inspect the authenticated integration
See the downloadable schema for request and response fields.
Server credential / documented scope required
GET/api/v1/events
List assigned, published events that have not ended
Requires events:read. Event grants, ownership, active credential, issuer management permission and live mode are rechecked in the database. No CORS/browser secret-key use. Unknown/repeated query parameters are rejected.
Server credential / documented scope required
limit · queryNumber of records returned.
cursor · queryOpaque next_cursor from this same application, mode, resource and filters. Keep filters unchanged; limit may change.
city · queryExact city name, case insensitive.
category · queryExact category slug, such as concert.
starts_from · queryInclusive event start lower bound. ISO timezone required; at most three fractional second digits.
starts_before · queryExclusive event start upper bound. ISO timezone required; at most three fractional second digits.
GET/api/v1/events/{eventId}
Read public event information
Requires events:read. Event grants, ownership, active credential, issuer management permission and live mode are rechecked in the database. No CORS/browser secret-key use. Unknown/repeated query parameters are rejected.
Server credential / documented scope required
eventId · path · requiredGET/api/v1/events/{eventId}/tickets
Read active ticket types, current package prices and sale restrictions
Requires tickets:read. Event grants, ownership, active credential, issuer management permission and live mode are rechecked in the database. No CORS/browser secret-key use. Unknown/repeated query parameters are rejected.
Server credential / documented scope required
eventId · path · requiredlimit · queryNumber of records returned.
cursor · queryOpaque next_cursor from this same application, mode, resource and filters. Keep filters unchanged; limit may change.
GET/api/v1/events/{eventId}/availability
Read advisory admission and package inventory
Requires availability:read. Event grants, ownership, active credential, issuer management permission and live mode are rechecked in the database. No CORS/browser secret-key use. Unknown/repeated query parameters are rejected.
Server credential / documented scope required
eventId · path · requiredPOST/api/v1/checkout-sessions
Create or replay a hosted checkout intent
Requires checkout:write and Idempotency-Key. No stock is held and no order/ticket/payment is created until the customer submits the hosted form. Inputs cannot include price, customer identity or attendee details. Max 400 admissions and per-tier sale/order restrictions apply. Session lifetime up to 30 minutes, bounded by issuing credential expiry.
Server credential / documented scope required
Idempotency-Key · header · requiredGET/api/v1/checkout-sessions/{sessionId}
Read minimal authoritative checkout status
Requires orders:read. Only this application/environment’s sessions with a current authorised event grant are readable. Historical status remains available after an event ends. No query parameters, purchaser information, QR codes, usable ticket/receipt links or checkout capability. Redirect nt_status is advisory: verify this API before updating a partner order.
Server credential / documented scope required
sessionId · path · requiredGET/embed/events/{eventId}
Render a public iframe for an assigned published event
See the downloadable schema for request and response fields.
No secret API key; route-specific origin/proof checks apply
eventId · path · requiredwidget · query · requiredenvironment · query · requiredparent_origin · query · requiredreturn_url · querychannel · query · requiredappearance · queryValidated optional snippet appearance; no arbitrary CSS.
accent · queryValidated optional snippet appearance; no arbitrary CSS.
button · queryValidated optional snippet appearance; no arbitrary CSS.
GET/api/integrations/widgets/{widgetId}/events/{eventId}
Read public widget configuration without secret credentials
See the downloadable schema for request and response fields.
No secret API key; route-specific origin/proof checks apply
widgetId · path · requiredeventId · path · requiredenvironment · query · requiredOrigin · header · requiredExact registered website origin in the selected environment. No Authorization header is accepted.
OPTIONS/api/integrations/widgets/{widgetId}/events/{eventId}
Validate a GET-only, header-free CORS preflight
See the downloadable schema for request and response fields.
No secret API key; route-specific origin/proof checks apply
widgetId · path · requiredeventId · path · requiredenvironment · query · requiredOrigin · header · requiredExact registered website origin in the selected environment. No Authorization header is accepted.
Access-Control-Request-Method · header · requiredPOST/integrations/widget-checkout
Submit a native user-activated form and navigate to existing hosted checkout
Not a cross-origin JSON API. Requires Naija frame Origin, no Authorization and, when present, Sec-Fetch-Dest=document. Five-minute signed proof; no prices, customer IDs or attendee details. Duplicate proof/intent replays the existing session. Max 16 KiB/five seconds, 20 selected tiers, 20 packages/tier and 400 admissions.
No secret API key; route-specific origin/proof checks apply
Origin · header · requiredTrusted Naija deployment origin, not the embedding partner origin.
GET/api/v1/orders
Read application-attributed order data
Requires orders:read. Current app/mode/creator/event ownership and event grants apply; never all marketplace customers. Contact fields require attendees:contact as well as attendees:read. Historical reads may include ended/unpublished granted events. See guide for sales/refund semantics.
Server credential / documented scope required
event_id · querylimit · querycursor · queryOpaque UUID-keyset cursor bound to application/mode/scopes/operation/filter. Lists order by resource UUID ascending.
GET/api/v1/orders/{orderId}
Read application-attributed order data
Requires orders:read. Current app/mode/creator/event ownership and event grants apply; never all marketplace customers. Contact fields require attendees:contact as well as attendees:read. Historical reads may include ended/unpublished granted events. See guide for sales/refund semantics.
Server credential / documented scope required
orderId · path · requiredGET/api/v1/orders/{orderId}/tickets
Read application-attributed ticket data
Requires tickets:status. Current app/mode/creator/event ownership and event grants apply; never all marketplace customers. Contact fields require attendees:contact as well as attendees:read. Historical reads may include ended/unpublished granted events. See guide for sales/refund semantics.
Server credential / documented scope required
orderId · path · requiredlimit · querycursor · queryOpaque UUID-keyset cursor bound to application/mode/scopes/operation/filter. Lists order by resource UUID ascending.
GET/api/v1/tickets/{ticketId}
Read application-attributed ticket data
Requires tickets:status. Current app/mode/creator/event ownership and event grants apply; never all marketplace customers. Contact fields require attendees:contact as well as attendees:read. Historical reads may include ended/unpublished granted events. See guide for sales/refund semantics.
Server credential / documented scope required
ticketId · path · requiredGET/api/v1/events/{eventId}/attendees
Read application-attributed attendee data
Requires attendees:read. Current app/mode/creator/event ownership and event grants apply; never all marketplace customers. Contact fields require attendees:contact as well as attendees:read. Historical reads may include ended/unpublished granted events. See guide for sales/refund semantics.
Server credential / documented scope required
eventId · path · requiredlimit · querycursor · queryOpaque UUID-keyset cursor bound to application/mode/scopes/operation/filter. Lists order by resource UUID ascending.
GET/api/v1/orders/{orderId}/groups
Read application-attributed group data
Requires groups:read. Current app/mode/creator/event ownership and event grants apply; never all marketplace customers. Contact fields require attendees:contact as well as attendees:read. Historical reads may include ended/unpublished granted events. See guide for sales/refund semantics.
Server credential / documented scope required
orderId · path · requiredlimit · querycursor · queryOpaque UUID-keyset cursor bound to application/mode/scopes/operation/filter. Lists order by resource UUID ascending.
GET/api/v1/orders/{orderId}/refunds
Read application-attributed refund data
Requires refunds:read. Current app/mode/creator/event ownership and event grants apply; never all marketplace customers. Contact fields require attendees:contact as well as attendees:read. Historical reads may include ended/unpublished granted events. See guide for sales/refund semantics.
Server credential / documented scope required
orderId · path · requiredlimit · querycursor · queryOpaque UUID-keyset cursor bound to application/mode/scopes/operation/filter. Lists order by resource UUID ascending.
GET/api/v1/sales-summary
Read application-attributed sales data
Requires sales:read. Current app/mode/creator/event ownership and event grants apply; never all marketplace customers. Contact fields require attendees:contact as well as attendees:read. Historical reads may include ended/unpublished granted events. See guide for sales/refund semantics.
Server credential / documented scope required
event_id · queryPOST/api/v1/events/{eventId}/check-ins
Verify or admit an attributed ticket as the current key creator
Requires entry:verify; admit also requires entry:check-in. Explicit deployment flags required. Only assigned published non-ended events and this application’s claimed tickets; actor cannot be supplied. Reuses existing locked venue engine and records key/creator audit. A replay is a historical operation result, not proof of current ticket validity. Thirty entry requests/key/min and 120/organiser/min, plus existing shared limits. Retained for seven days, cap 10,000 rows/application.
Server credential / documented scope required
eventId · path · requiredIdempotency-Key · header · requiredGET/api/v1/openapi.json
Download this public contract; no API key required
See the downloadable schema for request and response fields.
No secret API key; route-specific origin/proof checks apply
Responses and errors
{ "data": { … }, "meta": { "request_id": "…" } }
{ "error": { "code": "INSUFFICIENT_SCOPE", "message": "…", "request_id": "…" } }Secret-key lists include meta.next_cursor. Save request IDs for support; omit secrets, QR/contact data and private links. Widget configuration uses its documented data envelope and X-Request-ID header.
- 400
- Invalid fields, query, identifier or cursor
- 401
- Missing, revoked, expired or invalid key
- 403
- Missing permission or browser access denied
- 404
- Resource missing or not permitted
- 409
- Idempotency, reservation or state conflict
- 410
- Checkout/proof/replay expired
- 413 / 415
- Body too large or wrong content type
- 429
- Rate limited; honour Retry-After
- 503
- Disabled, isolated resources unavailable or configuration missing