API Reference

The Entrello API is a RESTful API that provides public read access to event data. All responses are returned in JSON format. These endpoints are publicly accessible and do not require authentication.

All API requests should be made to the base URL. Dates are returned in RFC 3339 format. Monetary values are in cents.

Base URL

https://entrello.app/api/events

Content Type

All responses use application/json.

Authentication

These public endpoints require no authentication. Access is scoped by the organization slug in the URL.

Example Request
curl https://entrello.app/api/events/?slug=my-org

List events

Returns a list of events for the organization. Events that share the same sync_id are grouped together, with additional dates returned in the dates array. This is the primary endpoint for building event listing pages.

GET /events
Query parameters
slug string optional
Organization slug. Identifies which organization's events to return.
sync_id string optional
Filter events by sync ID. Returns only events sharing this identifier.
archived string optional
Filter by archived status. Accepts "true" or "false".
product_orders_enabled string optional
Filter events that have product orders enabled. Accepts "true" or "false".
lang string optional
Language code (e.g. "en", "de") to apply translations to event title, description, and location.
label string optional
Filter events by label name (case-insensitive match).
Response body — array of Event
idstring
Unique event identifier.
org_idstring
Organization ID the event belongs to.
titlestring
Event title.
descriptionstring
Event description (may contain HTML).
featuresinteger
Bitmask of enabled features.
subtitlestring
Event subtitle.
artiststring
Artist or performer name.
on_saleboolean
Whether the event is open for sale on the webshop. See Status Codes & Flags for details.
soon_on_saleboolean
Whether the event will be on sale soon. See Status Codes & Flags for details.
on_holdboolean
Whether the event is on hold.
cancelledboolean
Whether the event is cancelled. See Status Codes & Flags for details.
hiddenboolean
Whether the event is hidden from public listing.
sold_outnumber
Sold out indicator. Special values: 0 = available, 0.9 = nearly sold out, 1.0 = completely sold out. See Status Codes & Flags for details.
starts_atstring
Event start time in RFC 3339 format.
ends_atstring | null
Event end time in RFC 3339 format, or null.
media_urlsarray of object
Event media (images, videos). Show child attributes
urlstring
Media URL.
typestring
Media type identifier.
datesarray of EventDate
Additional dates for synced events (grouped by sync_id). Each entry represents another date/occurrence. Show child attributes
idstring
Event date ID.
titlestring
Title for this date.
subtitlestring
Subtitle for this date.
starts_atstring
Start time in RFC 3339 format.
ends_atstring | null
End time in RFC 3339 format, or null.
on_saleboolean
Whether this date is on sale.
on_holdboolean
Whether this date is on hold.
cancelledboolean
Whether this date is cancelled.
featuresinteger
Bitmask of enabled features for this date.
sold_outnumber
Sold out percentage for this date.
locationobject | null
Location for this specific date. Show child attributes
namestring
Venue name.
descriptionstring
Venue description.
public_transportarray of string
Public transport options.
has_wheelchair_accessboolean
Wheelchair accessible.
has_bar_on_siteboolean
Bar available on site.
has_restaurant_on_siteboolean
Restaurant available on site.
addressobject | null
Venue address. Show child attributes
emailstring
Contact email.
phonestring
Contact phone number.
firstnamestring
Contact first name.
lastnamestring
Contact last name.
citystring
City.
countrystring
Country.
postcodestring
Postal code.
streetstring
Street address line 1.
street2string
Street address line 2.
coordsobject | null
GPS coordinates. Show child attributes
latnumber
Latitude.
lngnumber
Longitude.
zoom_levelinteger | null
Map zoom level.
company_namestring
Company name.
vat_idstring
VAT identification number.
labelsarray of object
Labels assigned to the event. Show child attributes
idstring
Label ID.
namestring
Label name.
colorstring
Label color hex code.
locationobject | null
Event venue location. Show child attributes
namestring
Venue name.
descriptionstring
Venue description.
public_transportarray of string
Public transport options.
has_wheelchair_accessboolean
Whether the venue is wheelchair accessible.
has_bar_on_siteboolean
Whether a bar is available on site.
has_restaurant_on_siteboolean
Whether a restaurant is available on site.
addressobject | null
Venue address. Show child attributes
emailstring
Contact email.
phonestring
Contact phone number.
firstnamestring
Contact first name.
lastnamestring
Contact last name.
citystring
City.
countrystring
Country.
postcodestring
Postal code.
streetstring
Street address line 1.
street2string
Street address line 2.
coordsobject | null
GPS coordinates. Show child attributes
latnumber
Latitude.
lngnumber
Longitude.
zoom_levelinteger | null
Map zoom level.
company_namestring
Company name.
vat_idstring
VAT identification number.
settingsobject | null
Event and webshop configuration settings. Show child attributes
basic_settingsobject | null
Basic event settings. Show child attributes
max_qty_per_orderinteger
Maximum number of tickets per order.
close_sale_after_percnumber
Percentage of capacity at which to close sales (0.0 to 1.0).
qty_preselected_ticketsinteger
Number of preselected tickets in the webshop.
close_sale_min_before_startinteger
Minutes before event start to close ticket sales.
close_products_sale_min_before_startinteger
Minutes before event start to close product sales.
require_ticket_holder_nameboolean
Whether ticket holder name is required at checkout.
available_concessionsarray of string
List of available promo/concession codes.
webshop_settingsobject | null
Webshop display and behavior settings. Show child attributes
postponedboolean
Display flag indicating the event has been postponed. Does not affect behavior. See Status Codes & Flags.
restagingboolean
Display flag indicating this is a restaging of a previous production. Does not affect behavior. See Status Codes & Flags.
premiereboolean
Display flag indicating this is a premiere performance. Does not affect behavior. See Status Codes & Flags.
lastboolean
Display flag indicating this is the last performance. Does not affect behavior. See Status Codes & Flags.
specialboolean
Display flag indicating this is a special event. Does not affect behavior. See Status Codes & Flags.
is_visibleboolean
Controls whether the event is visible in the webshop. If false, the event is hidden from the public listing. See Status Codes & Flags.
waiting_listboolean
Enables the waiting list feature. When combined with a sold-out event (sold_out = 1.0), customers can join a waiting list. See Status Codes & Flags.
reservationsboolean
Whether reservations are enabled.
reservations_onlyboolean
Whether the event only accepts reservations (no direct purchase).
waiting_room_limitinteger
Maximum number of concurrent users in the waiting room.
seating_plan_enabledboolean
Whether the seating plan is displayed in the webshop.
force_sold_out_messageboolean
Whether to force showing a sold-out message.
seating_plan_suggestions_enabledboolean
Whether seat suggestions are enabled.
link_product_ordersboolean
Whether product orders are linked to ticket orders.
seating_planobject | null
Seating plan configuration. Show child attributes
idstring
Seating plan ID.
widthinteger
Seating plan width in pixels.
heightinteger
Seating plan height in pixels.
svgstring
SVG markup of the seating plan.
available_languagesarray of string
List of available translation language codes.
pre_sale_codeobject | null
Pre-sale code validation status. Show child attributes
requiredboolean
Whether a pre-sale code is currently required. Based on the pre-sale end date.
approvedboolean
Whether the provided psc query parameter matches the event's pre-sale code (case-insensitive).
Request
curl https://entrello.app/api/events/?slug=my-org&lang=en
Response
[
  {
    "id": "evt_abc123",
    "org_id": "org_xyz",
    "title": "Hamlet",
    "description": "A Shakespeare classic...",
    "subtitle": "by William Shakespeare",
    "artist": "Royal Theatre Company",
    "on_sale": true,
    "soon_on_sale": false,
    "on_hold": false,
    "cancelled": false,
    "hidden": false,
    "sold_out": 0.45,
    "starts_at": "2026-04-15T19:30:00Z",
    "ends_at": "2026-04-15T22:00:00Z",
    "features": 0,
    "media_urls": [
      {
        "url": "https://cdn.entrello.com/img/hamlet.jpg",
        "type": "cover"
      }
    ],
    "dates": [
      {
        "id": "evt_abc124",
        "title": "Hamlet",
        "subtitle": "",
        "starts_at": "2026-04-16T19:30:00Z",
        "ends_at": null,
        "on_sale": true,
        "soon_on_sale": false,
        "on_hold": false,
        "cancelled": false,
        "sold_out": 0.2,
        "location": null
      }
    ],
    "labels": [
      {
        "id": "lbl_001",
        "name": "Theatre",
        "color": "#e25950"
      }
    ],
    "location": {
      "name": "Grand Theatre",
      "description": "",
      "address": {
        "city": "Vienna",
        "country": "Austria",
        "street": "Ringstrasse 1",
        "postcode": "1010"
      }
    },
    "settings": { ... },
    "seating_plan": null,
    "available_languages": ["en", "de"],
    "pre_sale_code": null
  }
]

List events (flat)

Returns a flat list of events without grouping by sync_id. Each event is returned as an individual record. Unlike /events, synced events are not grouped together and the dates array will be empty.

Use this endpoint when you need individual event records without date grouping, for example when building calendar views.

GET /events/flat
Query parameters
slug string optional
Organization slug. Identifies which organization's events to return.
archived string optional
Filter by archived status. Accepts "true" or "false".
product_orders_enabled string optional
Filter events that have product orders enabled. Accepts "true" or "false".
lang string optional
Language code for translations.
Response

Returns an array of Event objects with the same structure as List events, except that the dates array is always empty. Each synced event appears as its own entry.

Request
curl https://entrello.app/api/events/flat?slug=my-org
Response
[
  {
    "id": "evt_abc123",
    "org_id": "org_xyz",
    "title": "Hamlet",
    "description": "A Shakespeare classic...",
    "subtitle": "by William Shakespeare",
    "artist": "Royal Theatre Company",
    "on_sale": true,
    "soon_on_sale": false,
    "cancelled": false,
    "sold_out": 0.45,
    "starts_at": "2026-04-15T19:30:00Z",
    "ends_at": "2026-04-15T22:00:00Z",
    "dates": [],
    "labels": [...],
    "location": {...},
    "settings": {...},
    ...
  },
  {
    "id": "evt_abc124",
    "title": "Hamlet",
    "starts_at": "2026-04-16T19:30:00Z",
    "dates": [],
    ...
  }
]

Retrieve an event

Retrieves a single event by its ID with full details. If the event belongs to a sync group, all other dates in the group are included in the dates array.

GET /events/{id}
Path parameters
id string required
The ID of the event to retrieve.
Query parameters
lang string optional
Language code for translations.
psc string optional
Pre-sale code. If the event has a pre-sale code configured, pass the code here to unlock access. The pre_sale_code.approved field in the response indicates whether the code was accepted.
limit integer optional
Maximum number of synced event dates to return in the dates array. Default: 100.
Response

Returns a single Event object with the same structure as described in List events. The dates array contains all other events sharing the same sync_id.

If the event has a pre-sale code, the pre_sale_code object will be present:

pre_sale_code.requiredboolean
Whether a pre-sale code is currently required to view this event. Based on the pre-sale end date.
pre_sale_code.approvedboolean
Whether the provided psc query parameter matches the event's pre-sale code (case-insensitive).
Request
curl https://entrello.app/api/events/evt_abc123?lang=en
Request with pre-sale code
curl https://entrello.app/api/events/evt_abc123?psc=EARLY2026
Response
{
  "id": "evt_abc123",
  "org_id": "org_xyz",
  "title": "Hamlet",
  "description": "A Shakespeare classic...",
  "subtitle": "by William Shakespeare",
  "artist": "Royal Theatre Company",
  "on_sale": true,
  "soon_on_sale": false,
  "on_hold": false,
  "cancelled": false,
  "hidden": false,
  "sold_out": 0.45,
  "starts_at": "2026-04-15T19:30:00Z",
  "ends_at": "2026-04-15T22:00:00Z",
  "features": 0,
  "media_urls": [
    {
      "url": "https://cdn.entrello.com/img/hamlet.jpg",
      "type": "cover"
    }
  ],
  "dates": [
    {
      "id": "evt_abc124",
      "title": "Hamlet",
      "subtitle": "",
      "starts_at": "2026-04-16T19:30:00Z",
      "ends_at": null,
      "on_sale": true,
      "soon_on_sale": false,
      "on_hold": false,
      "cancelled": false,
      "sold_out": 0.2,
      "location": null
    }
  ],
  "labels": [
    { "id": "lbl_001", "name": "Theatre", "color": "#e25950" }
  ],
  "location": {
    "name": "Grand Theatre",
    "description": "",
    "public_transport": ["U1 Karlsplatz"],
    "has_wheelchair_access": true,
    "has_bar_on_site": true,
    "has_restaurant_on_site": false,
    "address": {
      "city": "Vienna",
      "country": "Austria",
      "street": "Ringstrasse 1",
      "postcode": "1010"
    }
  },
  "settings": {
    "basic_settings": {
      "max_qty_per_order": 10,
      "close_sale_after_perc": 1.0,
      "require_ticket_holder_name": false,
      "available_concessions": []
    },
    "webshop_settings": {
      "is_visible": true,
      "waiting_list": false,
      "reservations": false,
      "seating_plan_enabled": true
    }
  },
  "seating_plan": null,
  "available_languages": ["en", "de"],
  "pre_sale_code": {
    "required": true,
    "approved": true
  }
}

Event Object

The Event object is the core data structure returned by all event endpoints. It contains comprehensive information about an event including scheduling, availability, settings, location, and media.

Attributes

idstring
Unique event identifier.
org_idstring
Organization ID the event belongs to.
titlestring
Event title.
descriptionstring
Event description (may contain HTML).
subtitlestring
Event subtitle.
artiststring
Artist or performer name.
on_saleboolean
Whether the event is open for sale on the webshop.
soon_on_saleboolean
Whether the event will be on sale soon.
on_holdboolean
Whether the event is on hold.
cancelledboolean
Whether the event is cancelled.
hiddenboolean
Whether the event is hidden from public listing.
sold_outnumber
Sold out indicator (0.0 to 1.0). Special values indicate availability status.
starts_atstring
Event start time in RFC 3339 format.
ends_atstring | null
Event end time in RFC 3339 format, or null.
media_urlsarray of object
Event media (images, videos) with url and type fields.
datesarray of EventDate
Additional dates for synced events (grouped by sync_id).
labelsarray of object
Labels assigned to the event with id, name, and color.
locationobject | null
Event venue location with address, coordinates, and amenities.
settingsobject | null
Event and webshop configuration settings including basic_settings and webshop_settings.
seating_planobject | null
Seating plan configuration with SVG markup.
available_languagesarray of string
List of available translation language codes.
pre_sale_codeobject | null
Pre-sale code validation status with required and approved fields.
Example Event Object
{
  "id": "evt_abc123",
  "org_id": "org_xyz",
  "title": "Hamlet",
  "description": "A Shakespeare classic...",
  "on_sale": true,
  "soon_on_sale": false,
  "cancelled": false,
  "sold_out": 0.0,
  "starts_at": "2026-04-15T19:30:00Z",
  "settings": {
    "webshop_settings": {
      "is_visible": true,
      "premiere": true,
      "waiting_list": false
    }
  }
}

Status Codes & Flags

Events have various status indicators that control their behavior in the webshop and provide information about their availability and special characteristics.

Availability Status

These fields control whether an event can be purchased.

on_sale

Type: boolean
Description: When true, the event is open for sale on the webshop. Customers can browse and purchase tickets. This is the primary indicator that an event is currently available for purchase.

soon_on_sale

Type: boolean
Description: When true, the event will be available for purchase soon. This typically indicates that the sale period has not yet started, but customers can see the event in listings and prepare to purchase when it becomes available.

cancelled

Type: boolean
Description: When true, the event has been cancelled. Cancelled events are typically not available for purchase and may be hidden from the webshop or displayed with a cancellation notice.

sold_out

Type: number (0.0 to 1.0)
Description: Indicates the sold-out status of the event. This field has special meaning for certain values:

  • 0 or 0.0 - Tickets are available for purchase
  • 0.9 - Nearly sold out (typically 90% or more tickets sold). This triggers a "Nearly Sold Out" or similar message in the webshop to create urgency
  • 1.0 - Completely sold out. No tickets are available. If waiting_list is enabled in webshop_settings, customers can join a waiting list
  • Other values between 0 and 1 represent the percentage of tickets sold

Visibility Control

is_visible

Type: boolean (in settings.webshop_settings)
Description: Controls whether the event appears in the public webshop. When false, the event is hidden from listings and cannot be accessed by customers. This is useful for draft events or events that should only be available through direct links.

Waiting List

waiting_list

Type: boolean (in settings.webshop_settings)
Description: Enables the waiting list feature for the event. When combined with a sold-out event (sold_out = 1.0), customers can join a waiting list to be notified if tickets become available. This feature is particularly useful for high-demand events or to capture interest for additional showtimes.

Display Flags

These flags in settings.webshop_settings indicate special occasions or characteristics of the event. They are purely for display purposes and do not affect the event's behavior or availability. Use these to highlight special performances in your UI.

premiere

Type: boolean
Description: Indicates this is a premiere performance - the first public showing of a new production. This flag can be used to display a "Premiere" badge or special styling.

last

Type: boolean
Description: Indicates this is the last performance of a production. Use this to display a "Last Performance" or "Final Show" badge to create urgency.

special

Type: boolean
Description: Indicates this is a special event - such as a gala, charity performance, or other unique showing. Use this to highlight the event with special styling or badges.

postponed

Type: boolean
Description: Indicates the event has been postponed from a previous date. Display this information to inform customers that the event date has changed.

restaging

Type: boolean
Description: Indicates this is a restaging of a previous production. This helps customers identify productions that have been performed before.

Status Examples
// Available event
{
  "on_sale": true,
  "sold_out": 0,
  "cancelled": false
}

// Nearly sold out event
{
  "on_sale": true,
  "sold_out": 0.9,
  "cancelled": false
}

// Sold out with waiting list
{
  "on_sale": false,
  "sold_out": 1.0,
  "cancelled": false,
  "settings": {
    "webshop_settings": {
      "waiting_list": true
    }
  }
}

// Premiere event
{
  "on_sale": true,
  "settings": {
    "webshop_settings": {
      "premiere": true,
      "is_visible": true
    }
  }
}