Show events and tables¶

This guide uses the API routes to show a venue's events and tables on your own site or app, and to send guests to book. Call these routes from your server, because your key must stay secret.

1. Find your venues¶

curl "https://production.speakeasygo.com/external/v1/venues?take=50" \
  -H "token: $SPEAKEASY_TOKEN"

Keep each venue's id and timezone. See the API reference for every field.

GET /external/v1/venues/:id reads one venue with the same fields, plus its currency. With the field group venues:profile it also answers the opening hours, in the venue's time zone, and the policies a guest sees. A day whose to is earlier than its from runs past midnight.

2. List events¶

curl "https://production.speakeasygo.com/external/v1/events?venueIds=11111111-1111-4111-8111-111111111111&take=50" \
  -H "token: $SPEAKEASY_TOKEN"

You get events that are published, approved and not over yet. An event stays on the list until it ends. Members-only and discounted events are left out.

Sort by date yourself. Events come back ordered by id, not by date.
startDateTime and endDateTime are in UTC. Show them in the venue's timezone.
locationOverride is set when the event is held somewhere else than the venue.
url is the event's public page.

GET /external/v1/events/:id reads one event with the same fields. An event stays readable after it ends, because an order keeps pointing at it.

Ticket types¶

curl "https://production.speakeasygo.com/external/v1/events/22222222-2222-4222-8222-222222222222/ticket-types" \
  -H "token: $SPEAKEASY_TOKEN"

{
  "list": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "eventId": "22222222-2222-4222-8222-222222222222",
      "name": "General Admission",
      "description": "Doors at nine",
      "groupName": null,
      "addOn": false,
      "currency": "USD",
      "price": 4000,
      "customFee": 300,
      "status": "ON_SALE",
      "unlocksWith": null,
      "saleStartsAt": "2026-11-01T00:00:00.000Z",
      "saleEndsAt": "2026-12-31T04:00:00.000Z",
      "available": 58,
      "minPerOrder": 1,
      "maxPerOrder": 20,
      "sellInMultiples": false,
      "waitlist": false
    }
  ],
  "count": 1
}

This route needs the permission ticket-types:read. Good to know:

Use status to decide what to offer. ON_SALE can be bought now. NOT_ON_SALE_YET, SALE_ENDED, SOLD_OUT and PAUSED say why not. LOCKED means it opens when the ticket type in unlocksWith sells out or ends. Do not work it out from the dates yourself.
Read it again before you show a buy button. Tickets sell while you cache, so keep this for a minute at most. There is no way to hold tickets through the API yet.
price and customFee are for one ticket, in minor units. Processing fees and tax are not in them, because they depend on the whole order. See Time and money.
available is null when the venue chose not to show how many are left. status still tells you when it sells out.
Password protected and members only ticket types are not on this list, and neither is a ticket type that stays hidden until another one sells out.
maxPerOrder on a free ticket is the limit per person. A guest who already has some can claim fewer.

3. Find tables¶

curl -G "https://production.speakeasygo.com/external/v1/search/seating-areas" \
  -H "token: $SPEAKEASY_TOKEN" \
  --data-urlencode "eventIds=22222222-2222-4222-8222-222222222222" \
  --data-urlencode "guestCount=6" \
  --data-urlencode "sortBy=price" \
  --data-urlencode "sortDirection=asc"

Each result is one seating area for one event. To search by date instead, send startDateTime and endDateTime with a UTC offset. The range picks events that overlap it.

Read availability first:

`canBookOnline`	`canSubmitInquiry`	What to show
`true`	any	Show the price and a book button
`false`	`true`	Show "request a table". Prices and stock are `null` or empty.

A search does not hold anything. Price and stock can change before the guest books, and we check them again at checkout.

Seating areas with time slots¶

If requiresTimeSlotSelection is true, the area is sold by time. Its own price and stock fields are null, and each entry in timeSlots has its own startTime, price and availableInventory. calculatedMinimumSpend on the area is the lowest among its slots, and calculatedMinimumSpendTimeSlotIds tells you which slots have it.

Party size¶

guestCount leaves out areas that do not fit the party, and fills in calculatedMinimumSpendForGuestCount, which includes the charge for extra guests. Search again when the party size changes.

Budget¶

maxSpend is the highest minimum spend to return, before fees and tax. It leaves out areas that only take requests.

Prices¶

With the field group seating-areas:pricing, you get:

{
  "pricing": { "minimumSpend": 1000, "deposit": 20, "depositType": "PERCENTAGE" },
  "guestPricing": { "includedGuestCount": 4, "maxGuestCount": 8, "extraGuestAmountPerPerson": 100 }
}

deposit is an amount when depositType is FLAT, and a percentage when it is PERCENTAGE.

With the field group seating-areas:price-breakdown, you also get the final numbers in priceBreakdown: deposit is what the guest pays online, and spendAgreement shows the full minimum with fees and tax, and what is left to pay at the venue in balanceDueAtVenue. Use these numbers as they are. Do not work out fees yourself.

Amounts are in the venue's currency. See Time and money.

Links to booking¶

Send the guest to Speakeasy to book and pay. Use the links exactly as we return them.

Field	Where it goes	Needs the field group
`url` on a venue or event	The public page	none
`consumerUrl` on a seating area or time slot	The event page, with that table open	`seating-areas:consumer-booking-links`
`checkoutUrl` on a seating area or time slot	Straight to checkout for that table	`seating-areas:direct-checkout-links`

A time slot's link picks that slot. If you sent guestCount, the link carries the party size, so get fresh links when it changes. checkoutUrl is null for an area that only takes requests.

Keep calls low¶

Cache venues and events for a while, because they do not change often. Search seating areas when a guest asks. You have 60 calls a minute by default. See Rate limits.