What your key can reach¶

This page is about API keys, on the /external/v1 routes. A venue key reaches all the venue routes for its one venue.

We set up your integration with you. Four things decide what a call can do.

Routes¶

Each route needs its own permission.

Route	Permission
`GET /external/v1/venues`, `GET /external/v1/venues/:id`	`venues:read`
`GET /external/v1/events`, `GET /external/v1/events/:id`	`events:read`
`GET /external/v1/events/:id/ticket-types`	`ticket-types:read`
`GET /external/v1/search/seating-areas`	`seating-areas:read`
`GET /external/v1/orders`, `GET /external/v1/orders/:id`	`orders:read`
`GET /external/v1/reservations`, `GET /external/v1/reservations/:id`	`reservations:read`
`GET /external/v1/guests`, `GET /external/v1/guests/:id`	`guests:read`
The `webhook-endpoints` and `webhook-events` routes	`webhooks:manage`
`POST /external/v1/guest-list-import`	`guest-lists:write`
`POST /external/v1/concierge-entry-import`	`concierge-entries:write`

Without it you get a 403 that names what is missing, such as Missing venues:read capability.

Venues and events¶

Your integration can have all venues, or only the ones we list for you. The same goes for events. A list simply leaves out what your key cannot read. A route that names one venue answers 404 for a venue your key cannot reach.

A filter can only narrow what you can read. It can never widen it.

Filters and sorts¶

Each filter and sort is also turned on per route. If yours is off, the call gets a 403, such as seating-areas:filter:guest-count is not provisioned.

Route	Filters and sorts
Venues	`venueIds`
Events	`venueIds`, `eventIds`
Seating areas	`venueIds`, `eventIds`, `seatingAreaIds`, `guestCount`, `maxSpend`, sort by `price`

The time range on seating areas (startDateTime, endDateTime) is always on.

Field groups¶

Some fields only come back when a field group is on for your integration.

Field group	Adds
`venues:profile`	`description`, `dressCode`, `address` on a venue, and `hours`, `policies` when you read one venue
`venues:ai-guidance`	`aiGuidance` on a venue
`events:profile`	`description`, `bannerImage`, `artists`, `locationOverride` on an event
`seating-areas:pricing`	`pricing`, `guestPricing`
`seating-areas:price-breakdown`	`priceBreakdown`
`seating-areas:inventory-details`	`inventory`
`seating-areas:consumer-booking-links`	`consumerUrl`
`seating-areas:direct-checkout-links`	`checkoutUrl`
`seating-areas:ai-guidance`	`preferred`
`orders:payments`	`refunds`, `disputes` on an order
`reservations:payments`	`refunds`, `disputes` on a reservation
`reservations:staff`	`bookedBy.name` on a reservation
`guests:contact`	`email`, `phone`, `birthDate` on a guest
`guests:tags`	`tags` on a guest

A field that is off is left out of the answer. A field that is on can still be null when there is no value. Treat the two cases differently.

Team member credit¶

We can set up your integration to credit a team member of the venue. Then guest list entries you import are credited to that person, and the links you get carry their booking credit. You do not send this in your requests.

If the team member is no longer active at the venue, links fall back to plain links, and guest list imports are refused with a 403.