REST reference.

Returns 201 with the user plus an accessToken / refreshToken pair.

Returns an accessToken / refreshToken pair. If the account has 2FA enabled it instead returns { requires2fa: true, challengeToken, email } complete the login with POST /auth/2fa-verify.

Step 2 of a 2FA login. Returns the same accessToken / refreshToken pair as /auth/login.

Returns the same JWT pair as /auth/login no password ever exists.

Mints a fresh accessToken (and a rotated refreshToken) when the access token expires no re-login needed.

Revokes the refresh token so it can no longer mint new access tokens.

Returns { organization, wallets }. organization carries id, publicId, name, slug, description, website, contactEmail, contactPhone, logoUrl, type, verified, status, socialLinks, pageTheme and createdAt. wallets is one entry per currency (USD/NGN/ZAR), each with currency, symbol, balance, pendingBalance, lifetimePayout and status the organization's live balances.

Returns published, public events as discovery cards. Every card carries the read-only productType facet alongside category. The same q / category / productType / course / city / date filters work on GET /search.

Carries category plus the read-only productType facet (event | reservation | digital), organizer info, schedule, gallery, highlightVideoUrl, returnPolicy and active ticket types (each with transferable / refundable flags and a digitalAccess boolean). branding is whitelisted to a public-safe subset courseType, certificateTemplate and requireIdCheck only plus, for online-course events, a public syllabus (per lesson: order, title, description, duration, skillLevel, format only). Paid lesson internals (video/PDF links, materials, writeups, PINs) and the exam are NEVER on this payload. Reservation events return a reservation config block (mode, slots, maxAdvanceDays) and null start/end dates; digital/course products may also have null endDate (always-available). Buyer-only delivery links (a ticket’s accessUrl, and onlineLink for digital-product / e-books / downloadable-files / online-course / online-service categories) are never returned here. Private events 404 to anonymous callers but stay visible to their own organization authenticate with an organizer JWT or the org’s API key.

Reservations category only. Per-date remaining counts, clamped to the bookable window [tomorrow, today+maxAdvanceDays] (hard cap 90 days) in the event timezone. Returns { mode, windowStart, windowEnd, days: [{ date, remaining, soldOut, slots?: [{ slotId, label, startTime, endTime, remaining }] }] } in date_time mode each day also lists per-slot remaining. Feeds the checkout calendar before the ticket-quantity step. 400 NOT_A_RESERVATION_EVENT for a non-reservation event.

The seat map for an event with interactive seating: the canvas size, every section (with its ticketTypeId + per-seat price), every seat (id, label, x/y coordinates, kind incl. wheelchair/companion) and decorative elements (stage, text labels). Render it as a clickable SVG and resolve a clicked seat to its section for the price + ticket type. Events without seating return 404 NO_SEATING. Venue maps are built by Zatabox staff and are not part of this API.

Live availability snapshot: { sold, blocked, held } arrays of seat ids. sold = purchased or held in a live order; blocked = withheld by the organizer; held = temporarily held by other buyers mid-selection. Any seat id not in these lists is available. For a continuous feed use the SSE stream below.

Server-Sent Events. On connect it emits a snapshot event with the full availability, then seat_update events as seats change ({ sold | held | released | blocked | unblocked: [seatId,…] }), plus a periodic snapshot refresh. Use the browser EventSource API; reconnection is automatic.

Places (or replaces) temporary holds while the buyer selects. Returns { held: [...], failed: [...] } a seat already sold/blocked/held by someone else is skipped into failed. Holds expire automatically (default 5 minutes). Holds are a UX convenience: the authoritative double-booking guard is at order creation, so always handle a 409 SEAT_TAKEN from POST /orders.

Releases a holder's seat holds. Returns { released: <count> }.

Browse the published, reusable venue seat maps you can attach to an event. Each venue lists its published map versions with seat counts. (Venue maps themselves are built by Zatabox staff and aren't part of this API.)

The event's seating setup: the attached map (sections, seats, elements), the section→ticket-type pricing, and the blocked + sold seat ids. Returns { enabled: false } when no map is attached.

Attaches a published venue map so buyers pick exact seats. Only PUBLISHED maps are accepted (409 MAP_NOT_PUBLISHED). Switching to a different map after any seat has sold is rejected (409 SEATS_SOLD). Then call the pricing endpoint to put sections on sale.

Removes interactive seating from the event and clears its pricing + blocks. Rejected once any seat has sold (409 SEATS_SOLD).

Maps each venue section to a ticket type. Mapped tiers are flagged seated and their inventory is sized to the seats they cover. Replaces the full pricing set for the event. 400 if a section or ticket type doesn't belong to this map/event; 409 NO_SEATING if no map is attached.

Blocks or unblocks seats. Sold seats can never be blocked (409 SEAT_SOLD). Changes broadcast instantly to buyers on the live seat map.

Lists the events your organization owns (any status), newest first. Use the public GET /events to browse published events.

Required: title, category, startDate, timezone and venueType. endDate is required only for event-bucket categories (digital/course omit it for always-available; reservations manage it). capacity is optional (null = unlimited). The event is created in draft status; add ticket types and publish it separately. online-course events additionally enforce course-completeness on publish (see “Courses authoring”).

Partial update accepts every field from create, all optional; omitted fields keep their value. Date or venue changes to a published event notify ticket holders.

No body. Fails if required fields are missing or the event has no ticket types yet.

No body. Removes a published event from public listings and discovery and returns it to draft tickets and data are preserved, and it can be re-published later. Does not cancel the event or make tickets refund-eligible.

Cancels the event. Drafts simply disappear; published events make issued tickets eligible for refunds.

Partial update accepts the same body fields as create, all optional. Quantity can't drop below the number already sold; price and type are immutable once a ticket has sold. accessUrl, accessNote, transferable and refundable can be changed anytime.

Returns each type with live availability available is null when quantityTotal is -1 (unlimited).

multipart/form-data, not JSON. Resizes the image into web/thumbnail/OG variants and returns { mediaId, primaryUrl, variants }. Use primaryUrl as coverImage, gallery entries, etc. Requires an authenticated organizer JWT or API key.

multipart/form-data, not JSON. Hosts a raw file on Zatabox and returns { mediaId, primaryUrl, filename, bytes, mime } mediaId is a numeric asset id (e.g. 501) and primaryUrl is the stable root-relative path /media/501. Drop primaryUrl into a ticket’s accessUrl, the event onlineLink, or a course lesson’s lessonPdf/lessonVideo/materials (see the media-URL callout below). 413 FILE_TOO_LARGE over the cap; 415 UNSUPPORTED_FILE_TYPE for a disallowed type; 400 EMPTY_FILE for a 0-byte file. Requires an authenticated organizer JWT or API key.

Returns { sessions: [...] } the event's running order (talks, sets, acts), each with its day, time, speaker and location, ordered by day then sortOrder.

Adds a session to the event's public running order. Returns the created session.

Partial update accepts every field from create, all optional; omitted fields keep their value.

No body. Removes the session from the running order. Returns { deleted: true }.

Returns { sections: [...] } the named capacity blocks for the venue (GA floor, VIP deck, Balcony), ordered by sortOrder. Ticket types map to a section via their sectionId.

Creates a seating section. Reference it from a ticket type's sectionId to sell into it. Returns the created section.

Partial update accepts every field from create, all optional; omitted fields keep their value.

No body. Fails with a 409 if any ticket type still references the section reassign those types first. Returns { deleted: true }.

Returns { customization, defaults }. customization.faqs is the “Good to know” list ([{ question, answer }]) shown on the public event page; the object also carries the page theme, colors, layout, feature toggles, social links and SEO. A row is created with defaults on first read.

Partial update every field is optional and only the keys you send change. Returns the full { customization }. This is the endpoint that powers the “Good to know” tab in the organizer portal.

Returns { promoCodes: [...] }, newest first. Scoped to your organization (an API key is pinned to its own org).

Returns 201 with the created code. 409 CODE_ALREADY_EXISTS if the value is taken for that event; 404 EVENT_NOT_FOUND if eventId isn’t in your org; 409 EVENT_CANCELLED for a cancelled event.

Partial update send only the fields you want to change. Returns the updated code.

Unused codes are deleted ({ deleted: true }). A code that has already been redeemed is disabled instead of deleted ({ disabled: true, promoCode }) so historical orders stay intact.

Read-only preview used at checkout does not consume a use. Returns { valid, discount, reason? }; reasons include CODE_NOT_FOUND, NOT_YET_ACTIVE, EXPIRED, MAX_USES_REACHED, BELOW_MIN_ORDER and NOT_APPLICABLE_TO_THESE_TICKETS. Pass the same code as promoCode when creating the order to apply it.

Returns 201 with the order plus a per-order accessToken for guest reads. Free orders complete instantly tickets are issued at creation. For seated events, pass items[].venueSeatIds (see the Venue seating section). Reservation lines require items[].reservationDate (and reservationSlotId in date_time mode). When a paid order settles, the buyer is emailed their tickets; digital-product and online-course purchases additionally receive an invoice email with the delivery/enrolment link a behavioral note, not a separate API call.

nowpayments returns the generated crypto deposit details (payAddress, payAmount, payCurrency, network, payinExtraId); the redirect providers return an authorizationUrl to open. 409s: ALREADY_PAID, ORDER_NOT_PAYABLE, and NOTHING_TO_PAY for free orders.

Confirms the charge with the provider server-side and issues tickets. Idempotent and poll-safe call it after the buyer returns from checkout, or on an interval until status is completed.

Returns the order status, total, currency and the list of payment attempts (provider, status, amount). Read-only use /payments/verify to actively confirm and issue tickets.

Returns the live list of crypto coins NOWPayments can generate a deposit for (ticker, label, symbol) the source for the payCurrency value on /orders/{id}/pay. Cached ~10 minutes.

Pending / processing orders only releases held inventory. Paid orders go through the refund flow instead.

Fee: a 3% platform fee on the ticket face value is deducted from your org wallet for every NON-FREE (paid) ticket free tickets (price 0) incur NO fee and never touch the wallet. This is the reduced developer rate; paid orders bought through Zatabox checkout pay 5%. Flow: you collected the payment yourself, so we mint the tickets and a completed (externally-paid) order, then debit the 3% in the ticket currency fund the wallet first (Wallet → Fund). The whole issuance fails atomically with 402 INSUFFICIENT_FUNDS if the wallet can't cover the fee (nothing is minted). Honours the Idempotency-Key header so a retry never double-issues. Returns 201 with the order, the minted tickets and the exact fee charged.

Admits a ticket by code without scanning a QR same validation and idempotency as /checkin/scan.

Live check-in stats (scanned, admitted, denied) for a single gate.

Denials are 200s, not errors: status comes back success or denied_duplicate, denied_cancelled, denied_expired, denied_wrong_event, with a deniedReason field.

Ticket hashes + statuses a gate device caches locally, so it keeps admitting with zero connectivity.

Totals, capacity %, entry rate and per-gate breakdown. Per-gate slice: GET /checkin/event/{id}/gate/{gate}.

Server-Sent Events a stats snapshot every 2 seconds, keep-alive comments every 30. Point an EventSource at it.

Posts the organizer's public reply to an attendee review.

Lists the waitlist entries for an event (organizer view).

Offers freed-up inventory to the next people on the waitlist each gets a time-limited claim link by email.

Only checked-in tickets can review the pair ticketCode + email is the proof, no login needed.

Re-subscribes a prior opt-out; every announcement email carries a one-click unsubscribe link.

Organizer auth (portal session or org-scoped API key). Lists the org's subscribers with id, email, name, status and createdAt.

Organizer auth, write-level access. Hard-deletes the subscriber the compliant response to a removal request: their email/name are purged (not just marked unsubscribed), and the slot frees so they may follow again later. Returns { removed: true }.

No payment at join time. When inventory frees up, the next entries get a time-limited purchase link.

Removes one tag from one attendee. Create/apply tags with POST /organizer/growth/tags.

Sales, revenue, check-in and conversion analytics for one event. Requires the analytics:read scope.

The attendee list (holder name/email, ticket type, check-in status) for an event. Requires the attendees:read scope.

Returns imported and skipped counts rows with invalid emails are skipped, not fatal.

Sends real email to every matching attendee; replies thread back to the organizer inbox.

Additive existing tags stay. Tags power broadcast tagFilter and CRM segments. DELETE the same path removes one.

Returns { customers: [...], pagination: { cursor, has_more }, meta: { total, scanned, truncated } }. Each customer carries key, email, name, orderCount, lifetimeSpend (per currency, net of refunds), productTypeCounts, first/lastPurchaseAt and tags. The aggregation windows the org's most recent revenue orders meta.truncated true means the tail may be omitted (raise the window by paging). 400 if orgId is missing; 403 if the caller may not access the org.

The customer summary plus full purchase history: orders[] (with items + tickets and a per-line productType), refunds[], ticketCount and private notes[]. 404 CUSTOMER_NOT_FOUND if the key has no completed purchases in the org.

Returns { notes: [...] } private, org-internal notes on the customer, newest first. Never shown to the buyer.

Creates a private note (201). Standard session write rate limit.

Edits a note. Scoped by org + customer key so it can never be re-pointed across orgs/customers. 404 NOTE_NOT_FOUND if absent.

Deletes a note. Returns { deleted: true }. 404 NOTE_NOT_FOUND if absent.

Applies the tag to ALL of the customer's active tickets in the org the same AttendeeTag namespace that segmented broadcasts filter on. 201. 409 NO_TICKETS if the customer has no active tickets to tag.

Removes the tag from every one of the customer's tickets in the org. Returns { tag, removed }.

Sends ONE real, white-label email to the customer, branded as the organizer (org header/footer + From name). Tight strict rate limit (30/min → 429). Returns { to, subject, sent, dev }; 502 EMAIL_SEND_FAILED if delivery fails.

Authorizes ONE download. Needs the buyer’s own JWT not an API key, not an order access token and re-checks ownership on every call, so call it per click instead of caching what it returns. Answers { url, note, kind }. kind: 'file' is a freshly-signed, short-lived URL to a file Zatabox hosts, served as an attachment; kind: 'external' is the organizer’s own off-platform link, handed back verbatim for you to open. note carries the access PIN (accessNote) or null. Every failure is a 404, deliberately indistinguishable from a wrong id: TICKET_NOT_FOUND (not yours, or cancelled / refunded), NOT_DOWNLOADABLE (not a digital product an event, a reservation, or a course ticket, which delivers through the learner API instead), NO_FILE (the seller has attached no deliverable yet).

Digital-flow subset of the create-event body see the “Events organizer → Create a draft” endpoint above for the full shared field set (tags ≤ 10, coverImage / coverVideo, gallery ≤ 20, visibility public|unlisted|private, subcategory, branding, seoData, highlightVideoUrl), all optional and documented once there. Creates the product in status: draft with productType: digital; add at least one ticket tier, then publish. Upload the deliverable first with POST /media/upload-file (below) using private=1, so onlineLink / a tier’s accessUrl can point at the returned /media/<id>.

Partial update accepts every field from create, all optional; omitted fields keep their value. Send endDate: null to turn a dated product into an always-available one; set onlineLink / onlineLinkNote to swap the default deliverable or its PIN. A published-product change to date or delivery notifies existing buyers.

The sellable licence for the product; at least one tier is required before you can publish. Delivery resolves per buyer as: tier accessUrl → else event onlineLink; tier accessNote → else (only when the default link was used) event onlineLinkNote. That resolution happens server-side inside the download endpoint you set the inputs, you never hand the resolved link to a buyer yourself. The public event API suppresses accessUrl / accessNote and exposes only a boolean digitalAccess per active tier. saleEnd after event end → 400 INVALID_SALE_WINDOW; refundDeadline after event start → 400 INVALID_REFUND_DEADLINE.

Cross-reference full field set, size caps and error codes live in the “Media upload & hosting” group above. multipart/form-data. Returns { mediaId, primaryUrl, filename, bytes, mime }; drop primaryUrl (the root-relative /media/<id>, numeric id) into the event onlineLink or a tier’s accessUrl exactly as returned both fields also accept an absolute URL, and both come back absolute on buyer-facing payloads.

Transitions the product’s status (the same publish gate as POST /organizer/events/{id}/publish above a draft with no ticket tier can’t go live). Once published the product appears on the public page and in discovery with instant-access framing: each active tier shows a “delivered on purchase” hint, and a completed purchase emails the buyer the delivery link and PIN.

Creates the course in status: draft. Every course field from the PUT card below is accepted here too this table is just the minimum that gets a syllabus course through. Completeness is checked up front: an incomplete body is 400 VALIDATION_ERROR with every problem in details.issues[]. A course carries NO price create at least one ticket tier with POST /organizer/events/{id}/tickets (that tier is the enrolment), then publish. Copy-pasteable example below.

The course fields ride on the normal event create/update body (the full set is listed here on PUT; POST takes exactly the same fields see the create card above). They are persisted in branding; the public event API exposes only the curriculum shell (title/description/duration/skillLevel/format per lesson) + courseType + certificateTemplate. Media URLs accept /media/<id> (numeric) or an absolute URL and are normalized to /media/<id> for storage. Partial update: omitted fields keep their value, but the completeness check runs against the MERGED result whenever the edit touches courseType, syllabus, unified*, exam or onlineLink 400 COURSE_INCOMPLETE (first problem only) if the merge is incomplete. An edit that touches no course field skips the check.

Returns { courses: [...] } every online-course the caller has purchased, each with course meta (id, title, courseType, certificateTemplate, …) and a progress summary (totalLessons, completedLessons[], percentComplete, isComplete, certificateId, and an exam status block). Started courses sort first. No lesson content here fetch a single course for that.

The full learner payload for one course (buyer-verified). Course meta + holderName + progress, plus the lessons. For a syllabus course, lessons[] carries each lesson with a completed flag and SIGNED, short-lived media links (lessonPdf / lessonVideo / materials) plus writeup and lessonPin these paid fields are delivered here to enrolled buyers only. For a unified course, lessons is [] and a unified block carries the signed pdf/video/materials + pin. 403 NOT_A_BUYER if the caller doesn't own a ticket.

Syllabus courses only (400 NOT_A_SYLLABUS_COURSE otherwise). Marks the lesson complete (idempotent) and returns the updated completion state: { completed, justCompleted, examRequired, certificate, progress }. When the last requirement is met the course completes and, if a certificateTemplate is set and any exam is passed, a certificate is issued. 400 INVALID_LESSON_INDEX for an out-of-range index.

Un-marks a lesson (syllabus courses). Returns the same completion-state shape. Does not revoke an already-issued certificate.

Unified courses only (400 NOT_A_UNIFIED_COURSE otherwise). Marks the single learning unit complete and returns { completed, justCompleted, examRequired, certificate, progress }.

Returns the exam to take: { eventId, passMarkPct, total, questions: [{ id, prompt, options }], status }. Correct answers and explanations are stripped never sent to the learner. status carries attemptsUsed, bestScorePct, passed (sticky), latestScorePct etc. 404 NO_EXAM when the course has no live exam.

Grades server-side and records the attempt. Returns { scorePct, passed, passMarkPct, correctCount, total, perQuestion, status, completed, justCompleted, certificate, progress }. scorePct/passed are THIS attempt; status.bestScorePct and status.passed are best-ever and STICKY (a later failed retake never revokes a prior pass). perQuestion lists { questionId, correct } only the correct option index is NEVER revealed; a per-question explanation is included only on a passing attempt. A pass drives completion + certificate issuance when material requirements are also met. 404 NO_EXAM if there's no exam.

Downloads the completion certificate as a PDF (Content-Type application/pdf, attachment). 404 CERTIFICATE_NOT_ISSUED until the course is completed (and, where an exam is required, passed).

Lists the signed-in buyer's refund requests and their statuses. Request a refund with POST /users/me/refunds.

Lists the signed-in buyer's message threads with organizers.

Transfers a ticket to another person; the recipient claims it via the emailed link. Fails on non-transferable ticket types. The initiator can revoke before it's claimed.

Every live ticket the caller owns, each with a productType discriminator (event | reservation | digital), its event and tier, and for reservations the booked date/slot. Digital delivery: downloadable: true means Zatabox hosts the file, and accessUrl is null on that row by design; fetch the file with the download endpoint below. An external link rides along in accessUrl (absolutized) with downloadable: false. accessNote is the PIN either way. Course tickets are never downloadable here they open from the learner API.

Cross-reference documented in full under “Digital products → delivery (buyer)”. Re-checks ownership per call and returns { url, note, kind } with a freshly-signed, short-lived url. 404 TICKET_NOT_FOUND / NOT_DOWNLOADABLE / NO_FILE.

No parameters. Returns one JSON download of everything on the account: profile, orders + items, tickets, refund requests, reports and message threads.

Eligibility = the ticket type’s refundable flag plus its deadline; the organizer approves or denies. 409 when not eligible.

harassment and fraud route straight to platform admins; the rest go to the organizer first.

Rate-limited to 10 messages per hour per organizer. Replies land in GET /users/me/messages.

Lists your organization's per-currency wallet balances (balance, pending, lifetime payout).

The per-currency wallet balances for one organization (org pinned in the path).

The response returns the full plaintext secret EXACTLY ONCE only its prefix is stored afterwards. Send it as a Bearer token (Authorization: Bearer vt_live_…). Requires an organizer JWT (owner / admin).

Returns each key’s prefix, masked display, scopes, environment, status, last-used and expiry never the secret.

No body. Returns a new plaintext secret exactly once and invalidates the old one immediately.

Revokes the key it stops authenticating immediately.

The response contains the full whsec_ signing secret exactly once it is masked on every later read. Store it immediately.

Deliveries stop immediately and the signing secret is invalidated recreating issues a new one.

No body fires a signed test event at the URL so you can verify your handler end to end.

No body. Issues a new whsec_ signing secret and returns it exactly once (the old one stops verifying immediately). Store it right away it is masked on every later read.

Each delivery shows event type, response status, latency, retry count and the error detail on failures.

No auth, no parameters every event type the platform can emit, for building subscription UIs.