Build on TicketBooth

What TicketBooth is

TicketBooth is a corporate event-ticketing platform. A company sources seats to events (music, sports, art, family and VIP) and its employees claim them through an approval process rather than a checkout. This API is the same surface the TicketBooth web app calls; there is no separate integration API behind it.

The central object is a claim on seats rather than a purchase. An employee requests tickets, a manager decides, and Ticketnology sources and fulfills what was approved. Unused seats can be re-listed for resale, and every movement is recorded on the company’s balance ledger.

That describes one of three account types. It is the TicketBooth type, and it is the one the rest of the guide follows. A Ticket Pass company spends a prepaid balance through a different flow with different statuses, and a Consignment company supplies the tickets rather than claiming them. A company’s type determines which half of this API applies. Start at Account types.

Every resource you can reach is scoped to your company and offices, derived from your token. See Authentication. TicketBooth is not a public marketplace: apart from the exempt routes listed under Authentication, every route requires an authenticated user.

Account types

The three account types are three different products. A company’s type determines which endpoints apply to it, who approves what, and which set of statuses is used. The claim lifecycle in Requesting tickets applies to the TicketBooth type specifically.

Ticket Pass has a role of its own, and it is not confined to /ticket-pass: it appears on 50 of the 225 operations, including the customer, transaction, event and reservation reads a Ticket Pass user needs. It does not include approve and deny; those require Client Manager. Consignment has no role of its own; its client-facing routes are open to the ordinary client roles.

The company funds an account, and purchases draw it down. GET /ticket-pass/account is the balance, GET /ticket-pass/transactions the ledger behind it, and POST /ticket-pass/add-funds starts a deposit (POST /ticket-pass/verify-session confirms it once the payment returns). Auto-renewal replenishes the balance on a schedule. Enable it, disable it, and read its state and history under /ticket-pass/auto-renewal. A purchase settles from the balance or from a credit card; the card route is POST /ticket-pass/purchase/cc/start then POST /ticket-pass/purchase/cc/verify, and POST /ticket-pass/checkout/preview prices a proposed purchase before POST /ticket-pass/checkout/confirm commits it.

Ticket Pass requests do not use the reservation statuses. They have their own, and the two sets share names without sharing meanings:

Ordered is not terminal, and it is not a synonym for Fulfilled. The balance has been debited but the seller has not yet accepted. The transition to Fulfilled is driven by the marketplace webhook rather than by any call the client makes, and if that callback never arrives nothing else moves the request on, so Ordered is where a stalled Ticket Pass request sits indefinitely.

Failed is recovered by submitting a new request. The balance is refunded automatically, and there is no retry endpoint on the original request.

Fulfillment carries a shipping address, because Ticket Pass delivers physical tickets rather than allocating seats on an event the company owns. It is taken from the request, and on a company with tax quoting switched on an incomplete address fails the fulfillment. That is also why nothing in /ticket-pass refers to an event id.

Consignment inverts that flow. Start from GET /consignment/known-events, which returns the event names you have consigned before so a recurring show does not have to be retyped. It returns your 25 most recent, not the full history, so treat it as a shortcut rather than a lookup, then submit with POST /consignment/quotes/list-tickets.

Submitting is not listing, but the quote exists straight away. The submission is written as a consignment quote immediately, at the incoming stage, and your account manager is emailed. That email does not gate anything: nothing is waiting on an approval. The account manager later moves the quote to listed, once the tickets have physically arrived.

Requesting tickets back works the opposite way. POST /consignment/quotes/{sourceQuoteId}/request-back creates nothing and changes nothing on the original quote; it records a pending request and waits for an account manager to approve it. GET /consignment/pending-request-backs returns the requests still outstanding, which is how a client portal prevents a duplicate request.

Neither flow exposes an approve endpoint to the client. Your account manager acts in Ticketnology’s internal tooling, so the API returns only the outcome: a quote that now exists, or a request-back that has left the pending list.

The remaining routes in the area are supporting reads: GET /consignment/dashboard-summary, GET /consignment/activity-feed with POST /consignment/activity-feed/{entryId}/read, and GET and PUT /consignment/email-preferences, which control how much of that activity is emailed.

Reminder cadence also follows the account type, so an absence of email means something different for each: Consignment reminds the contact while tickets remain listed, TicketBooth reminds the contact when a quote is ready to purchase, and Ticket Pass notifies Ticketnology when an order has not been sent. See Notifications & email.

Core concepts

These nine objects make up the TicketBooth half of the API: reservations and events. Most of them share one status set, the reservation statuses. Ticket Pass and Consignment do not appear here at all: they have their own objects and their own statuses, in Account types.

Order status and seat status are tracked separately. A Listed (17) order can already contain Sold (10) seats, because a resale settles one seat at a time and the order rolls up to Sold only once every seat has. An availability check must therefore filter at the seat level; filtering at the order level returns seats that are already sold.

Parking passes, VIP and other add-ons are not a ticket type. Each is a seat option with its own section and price, so they are claimed, approved and resold exactly like a seat, with no special handling in the reservation routes.

Requesting tickets

A claim enters the system in one of three ways. Which one applies depends on whether the seats already exist.

A direct book starts at Approved (2) rather than Pending (3) when your company’s auto-approval rules cover it, so Approved is not proof that a person approved it. See Approvals & lottery.

Approving a request does not fulfill it. The request becomes Approved (2) and a follow-up order is written at NeedsResearched (14), which remains there until Ticketnology has established price and availability. The item awaiting action is that new order, not the approved request.

For a requestor’s own view call GET /reservation/employee/dashboard; for the approver queue, GET /reservation/approvals. Once an order is approved it is either fulfilled or re-listed with POST /reservation/sell, which moves it through Resell (9), Listed (17) and Sold (10).

Approvals & lottery

Reservations have two approval tracks and they are not interchangeable. A request and an order represent different commitments, so they have separate endpoints and take different payloads.

Both tracks below are the TicketBooth account type. Ticket Pass approvals are a separate flow on separate endpoints with their own status set, and Consignment submissions are approved by your account manager rather than by anyone in your company. See Account types. Nothing in this section applies to either of them.

Both tracks support the same three decisions (approve, deny and escalate), each on its own endpoint under the track above. Denial releases the seat hold and leaves the item visible to the requestor, with the approver’s notes attached. Escalation routes the item to the managers named in the request.

Approving an order is not all-or-nothing. The request names the seats being approved, and any seat omitted is denied. Escalation behaves the same way: it can target individual seats, and the remainder of the order is treated as denied. A client reading back an order must therefore read its seats, not only the order’s own status.

An order can arrive already approved. A sales quote is the agreement your account manager prepares, listed under Quotes in the reference below. When one reaches purchase, the order it creates is written directly to Approved (2): no approver sees it and no notification is sent. There is also no time-based expiry on a pending approval, and no process closes one automatically.

When demand exceeds supply, the lottery ranks the pending orders for one event, so allocation is not decided by hand. Requests do not go through it.

A lottery run does not approve anything on its own. POST /lottery/run/{eventId} produces a list of selected orders for review, PUT /lottery/run/{runId}/results lets the manager remove entries, and POST /lottery/run/{runId}/confirm then approves each remaining selection through the ordinary order-approval path, including escalation rules and notifications.

Selection runs in three phases. Filter drops orders outside the ticket-quantity bounds, over the per-user spend cap, past the per-user event cap, or failing any custom rule. Weight gives every survivor a base of 1.0 plus the additive boosts below, so an order at 2.0 is twice as likely as one at 1.0. Select then draws by weighted random until the seats are exhausted.

Weights therefore run from 1.0 with no boosts to 2.5 with all of them. Every run records the configuration and rules that were active when it ran, so changing the configuration later does not rewrite an earlier draw. Read a run back with GET /lottery/run/{runId}, or set the defaults with PUT /lottery/config.

Managing events

Every claim names an event, so the event must exist and have seats before anyone can request one. POST /events saves both new and edited events.

Once the event exists, its visibility is controlled separately. POST /events/availability/{id} toggles it on and off, the /release-schedule routes stage it so it opens to different roles at different times, and POST /events/shared issues a share link for recipients without an account. An unreleased event still appears in the list, flagged unavailable rather than hidden. GET /events/availableSeats/{id} is the seat-level availability read, and is the correct call before booking, for the reason given in Core concepts.

A route’s role list is not always the final check. Some endpoints re-check the caller in the business layer, and that check can be narrower than the route’s allow-list: DELETE /events/delete/{id} is refused for every role in this document, despite what its own role list says. A refusal of that kind is a bodiless 401, identical to a token or role failure, so a 401 on a route your role appears on indicates a business-rule refusal, not an invalid token.

A refusal is not always an error status. That same endpoint declines to delete an event that has any claims against it, and reports the refusal by returning false with a 200 rather than a 400. Inspect the body on a write, not only the status.

Canceling with POST /events/cancel/{id} is the counterpart available to managers, and it leaves the event and its claim history in place.

Offices & scoping

An office determines what a user sees and who approves it. Every user belongs to a company and to one or more offices, and a claim is bound to an office through the person who made it. That binding determines which approvers are notified and which dashboards it appears in. The balance ledger itself is company-wide, so an office does not get a separate running total.

A user assigned to more than one office has one active office, and queries are narrowed to it. The same token therefore returns different data depending on which office is active. A shorter-than-expected list is often the active office rather than the query filters.

An empty event list is usually a venue mapping, not an empty calendar. When an office’s venues and the user’s allowed venues have nothing in common the intersection is empty, and the read returns no rows: a 200 with an empty set, not an error. The response does not indicate that the office mapping was the cause.

An unassigned employee falls through to a company address, then to nothing. The scheduled approval reminder resolves the requestor’s assigned managers, falls back to the single legacy manager on their user record, and pools whatever it still cannot route into an (Unassigned) digest sent to the company’s configured manager address. If that address is blank the digest is not sent at all, and the only trace is a log warning. The orders themselves are unaffected: they remain at Pending (3) in GET /reservation/approvals. Only the reminder is lost.

All 20 routes in this area are client-callable; none is reserved for Ticketnology. Creating or editing an office, and making any of the assignments above, requires Client Manager or Client Super Admin. The six reads that also admit Client Employee are those an employee needs to determine their own scope.

Notifications & email

The platform notifies people about claims through two independent channels, which overlap less than the endpoint names suggest. Email covers the whole TicketBooth claim lifecycle. The in-app feed at /notifications shows feature-request activity and nothing else.

Approvals never appear in GET /notifications. The only writer to that feed is the feedback area: a comment on a request you follow, a status change, or an official update. An approver’s outstanding work is at GET /reservation/approvals, not in the notification feed.

All four are scoped to the calling user by the token alone. There is no user id in any of them, and no role on any of them. For feedback activity the notification row is written even when its email fails, so the feed is the more reliable record of feedback activity, and only of that, since nothing else writes to it.

Nothing in the claim lifecycle sends email inline. Each event places a message on its own queue and a background worker sends it, so a 200 from an approve or a book confirms that the decision was recorded, not that a message was delivered. When testing a flow, do not treat the response as evidence that email was sent.

The requestor is emailed either way. Who else is notified depends on the company’s configuration, and the two settings interact:

On a company with bypass enabled and reporting structure disabled, an approval sends no manager email at the moment of the decision. That is the configured behavior, not a fault. Multi-office companies filter recipients by the event’s office in addition to all of the above, and a company can have custom routing arranged separately.

Every email above is triggered by an action. A second kind runs on a schedule instead: a daily job follows up on a quote that has stalled at a stage. These reminders are driven by how many days remain before the event, not by how long the quote has been stalled. A stalled quote for an event a year out generates nothing, while the same quote generates reminders in its final month.

Each interval is sent at most once, and a window that passed before the quote reached the stage is closed rather than sent late. A quote that reaches its stage 10 days out receives the 14-day reminder on the next run; the 30-day window is already behind it, so it is recorded as done rather than sent, and the 7-day reminder still arrives a week before the event. That collapse is what prevents a first run from sending every window at once, and it is also why a reminder never repeats: nothing re-opens an interval once it is logged.

Consignment has a second, separate reminder that does count elapsed time. It follows up with an account that has had no consignment activity at 30, 60 and 90 days, then stops until activity resumes, at which point the sequence starts over. It goes to the company’s own address rather than to a contact on a quote, and each one is also recorded in GET /consignment/activity-feed, so the feed shows that it was sent.

Four points in the lifecycle can use copy written for one specific event, replacing the default wording for that event only.

Read one with GET /emailTemplates/{eventId}/{templateType}, save one with POST /emailTemplates, and upload inline images with POST /emailTemplates/{eventId}/images/upload. Templates are per event, so a new event uses the default copy until one is saved for it. These four numbers are template-type ids and have nothing to do with the reservation statuses. Denied is 3 here, while 3 is Pending there.

Reports

Reports is the largest area in this document, and the most regular. Almost every report is a pair: a JSON read you can drive a dashboard from, and a matching export route that returns the same data as a CSV file. Nothing here creates or changes anything, so the whole area is safe to poll.

A date window is required, not optional. startDate and endDate are required on every report except the contract report and the guest list, and omitting either returns 400 rather than defaulting to a range.

officeId narrows, it does not widen. Leave it off and you get everything your own scope already allows, which is the usual case. Pass it to restrict the report to a single office. It cannot reach an office you could not otherwise see (see Offices & scoping).

An export is a file, and five of them need a dataset. Every route whose path ends in /export returns text/csv as an attachment with a Content-Disposition filename, not JSON. On the usage, people, planning, cost and consignment-inventory exports, dataset selects which slice of that report to render and is required: omit it and the call returns 400, not a default sheet.

POST /reports/custom is the one endpoint in this area that is not a fixed report. You send a prompt of up to 600 characters describing what you want, and it answers against your own data. Because each call runs a language model, it is capped at 5 requests per minute and returns 429 above that. See Rate limits & reliability.

A prompt worth reusing can be kept: POST /reports/custom/saved stores one, GET /reports/custom/saved lists what you have stored, and DELETE /reports/custom/saved/{id} removes one. Saved reports hold the question, not a snapshot of the answer, so re-running one reflects the data as it stands now.

Getting started

Integrating with TicketBooth takes three things: credentials, a base URL, and one call to prove all of it works. This section covers each in order. If you are evaluating rather than building, What TicketBooth is is the better starting point.

There is no self-service registration. Ticketnology provisions an Auth0 client for your integration and sends you its id, its secret and the audience to request. Ask your account manager, or write to tech@ticketnology.com, and say which environment you need and roughly what the integration will do. The roles attached to your client decide which of the endpoints in this document you can reach at all, so that shapes the provisioning.

Once you hold those, a token is a standard OAuth 2.0 client-credentials exchange against the Auth0 tenant named in your onboarding pack. Your pack carries the tenant domain and the audience value; this page does not publish them, because they differ per environment and a stale copy here is worse than none.

curl -X POST 'https://<your-tenant>/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
  "grant_type": "client_credentials",
  "client_id": "<from your onboarding pack>",
  "client_secret": "<from your onboarding pack>",
  "audience": "<from your onboarding pack>"
}'

Every sample on this page is already written against the environment you are reading it on, shown at the top and repeated in each snippet. A staging and a production environment are separate hosts with separate credentials; a token issued for one is rejected by the other.

Call GET /events with a startDate. It is the shortest request that exercises the whole chain at once: the token is validated, your company scope is resolved from your user record, and your role is checked against the route. A 200 with a JSON array means the integration is live.

A 401 here is worth reading carefully rather than retrying. It means the token was rejected, the account is inactive, or your role is not on this route. Responses & errors tells the three apart. An empty array with a 200 is not an error and usually means office scoping, covered in Offices & scoping.

Authentication

Authorization: Bearer <your-jwt-token>
Content-Type:  application/json

Responses & errors

Errors are HTTP status codes. Bad input returns a JSON message; authorization failures return no body.

Rate limits & reliability

Most endpoints carry no application-level rate limit today. Two in this document do, and both answer 429 when you cross them:

Treat the absence of a published limit elsewhere as "not yet", not as a guarantee. The platform runs on Azure Functions and will shed load under pressure regardless of what this page says, so a client that paces itself and backs off on failure keeps working. A sensible integration retries a failed read two or three times with exponential backoff and gives up rather than looping.

No endpoint accepts an idempotency key. Sending the same POST /reservation/book twice creates two orders; there is no request id that collapses them. So the safe retry rule is asymmetric:

Email is queued rather than sent inline, so a write that succeeds has not necessarily notified anybody yet. That is normal and is covered in Notifications & email.

Versioning & stability

This is version 1. The version does not appear in your requests: there is no version segment in the path and no version header. A future incompatible version would be introduced alongside this one rather than replacing it in place.

Write your client to tolerate the right-hand column. Ignore response fields you do not recognize rather than rejecting the payload, and treat an unknown enum value as unhandled rather than as an error. New statuses have been added to this API before and will be again.

This API is the same surface the TicketBooth web application calls. That is deliberate: there is no thinner, separately-maintained integration API that lags behind the product, so anything the product can do, your integration can do on the same day. The trade is that the surface moves as the product moves, and the commitment below is what makes that safe to build on.

Breaking changes, as defined above, are announced to integration clients at least 90 days before they ship, in writing, to the technical contact on your account. Non-breaking changes ship continuously and are not announced individually. If an integration of yours depends on behavior this document does not describe, tell us. Undocumented behavior is the part we cannot promise to preserve, and naming it is how it gets covered.

This document is generated from the running service on every deploy, so it describes the environment serving it rather than a release note written by hand. The endpoint count at the top of the page is read from that same source.

Reservation lifecycle

TicketBooth queues a booking at Pending (3) for an approver to review. Send the integer value in reservationStatus.

Approval is a fork, not a step. An approved reservation is either fulfilled or listed for resale; it does not pass through one on the way to the other. Resale also goes through Listed (17): nothing moves straight from Resell to Sold.

Pending also branches to Denied (11), Escalated (13) and NeedsResearched (14), and every terminal state is eventually moved to Archived (16). The full state machine is in Documentation/Architecture/20-reservations.md §3, which is the source for this section.

Who can call what

Each route has its own role allow-list; a role that is not on it receives 401. This matrix is computed from the spec, so it follows the [RoleAuthorize] attributes instead of being maintained by hand. The reference below shows the exact roles per endpoint.