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.1

The 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

200401403429503
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 · query

Number of records returned.

cursor · query

Opaque next_cursor from this same application, mode, resource and filters. Keep filters unchanged; limit may change.

city · query

Exact city name, case insensitive.

category · query

Exact category slug, such as concert.

starts_from · query

Inclusive event start lower bound. ISO timezone required; at most three fractional second digits.

starts_before · query

Exclusive event start upper bound. ISO timezone required; at most three fractional second digits.

200400401403405429503
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 · required
200400401403404405429503
GET/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 · required
limit · query

Number of records returned.

cursor · query

Opaque next_cursor from this same application, mode, resource and filters. Keep filters unchanged; limit may change.

200400401403404405429503
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 · required
200400401403404405429503
POST/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 · required
200400401403404405409413415429503
GET/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 · required
200400401403404405429503
GET/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 · required
widget · query · required
environment · query · required
parent_origin · query · required
return_url · query
channel · query · required
appearance · query

Validated optional snippet appearance; no arbitrary CSS.

accent · query

Validated optional snippet appearance; no arbitrary CSS.

button · query

Validated optional snippet appearance; no arbitrary CSS.

200400403404405409429503
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 · required
eventId · path · required
environment · query · required
Origin · header · required

Exact registered website origin in the selected environment. No Authorization header is accepted.

200400403404405409429503
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 · required
eventId · path · required
environment · query · required
Origin · header · required

Exact registered website origin in the selected environment. No Authorization header is accepted.

Access-Control-Request-Method · header · required
204400403404405409429503
POST/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 · required

Trusted Naija deployment origin, not the embedding partner origin.

303400403404405409410413415429503
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 · query
limit · query
cursor · query

Opaque UUID-keyset cursor bound to application/mode/scopes/operation/filter. Lists order by resource UUID ascending.

200400401403404405429503
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 · required
200400401403404405429503
GET/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 · required
limit · query
cursor · query

Opaque UUID-keyset cursor bound to application/mode/scopes/operation/filter. Lists order by resource UUID ascending.

200400401403404405429503
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 · required
200400401403404405429503
GET/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 · required
limit · query
cursor · query

Opaque UUID-keyset cursor bound to application/mode/scopes/operation/filter. Lists order by resource UUID ascending.

200400401403404405429503
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 · required
limit · query
cursor · query

Opaque UUID-keyset cursor bound to application/mode/scopes/operation/filter. Lists order by resource UUID ascending.

200400401403404405429503
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 · required
limit · query
cursor · query

Opaque UUID-keyset cursor bound to application/mode/scopes/operation/filter. Lists order by resource UUID ascending.

200400401403404405429503
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 · query
200400401403404405429503
POST/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 · required
Idempotency-Key · header · required
200400401403404405409410413415429503
GET/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

200

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