NAV Navbar
Logo
shell javascript

Introduction

Welcome to the Ticketteer API documentation. You can use the API to CRUD events, dates, venues, place orders and get information about the booking state in Ticketteer.

We currently don’t offer special libraries for any language. But it’s pretty straight forward to wrap the API calls in your favorite’s language request library.

Ticketteer is a quite fresh and young product. If you are trying to achieve something special, which is not covered in this documentation, don’t hesitate and get in touch with us directly:

hello@ticketteer.com

What can you do with the API / API-Keys

Note for the examples

In our examples we use authentication keys and ids. Please note, these keys are not valid. We are considering a way to provide you with examples replaced by your actual key.

Until this is working, you need to edit the statements and replace the keys with your key and values.

Getting Started

You might probably want to start by setting up an event through the event wizard in the Ticketteer Admin Dashboard and then try to fetch those events. We have prepared an example for you in the LineupEvent Section.

If you are after a recipe to create a customized booking wizard, try the Recipes Section.

Authentication

You need a login to Ticketteer (you can set up your developer account for free and switch to your client’s actual entity later on). You will find the API-keys in the Settings->Organization Tab. Click Create API Key if there isn’t already one.

Activating an API Key

Click to create API Key

You can copy the keys by clicking the clipboard icon next to the key.

Click to create API Key

Public/Private Keys

For different operations you are meant to use different keys.

Your public key can …

Your private key can …

LineupEvent

To list all LineupEvents with dates in future:

curl "curl -X GET --header 'Accept: application/json' --header \
'Authorization: $PUB_KEY' \
'https://app.ticketteer.com/api/v1/lineup_events/public'"

# example:

curl "curl -X GET --header 'Accept: application/json' --header \
'Authorization: 7e5cc068c4b2d7ea92495b43223d6625563239708023c05d69ed8aa91edd43e1' \
'https://app.ticketteer.com/api/v1/lineup_events/public'"
// this example uses jQuery, you can use plain javascript as well
var apiEndpoint = 'https://app.ticketteer.com/api/v1';
var publicKey = '7e5cc068c4b2d7ea92495b43223d6625563239708023c05d69ed8aa91edd43e1';
jQuery.ajax({
  url: baseUrl + '/lineup_events/public',
  type: 'GET',
  headers: {
    Authorization: '7e5cc068c4b2d7ea92495b43223d6625563239708023c05d69ed8aa91edd43e1',
  },
  dataType: 'json',
}).done(function (response) {
  // continue processing with `response.data.lineup_events`;
});

LineupEvent Response Object

{
   "lineup_events": [
      {
         "id":"58dbb8ca3a9d9c0001d7f191",
         "title":"Romeo and Juliet",
         "subtitle":"A classical play about two lovers",
         "is_public":true,
         "description": "Description about project",
         "short_description": "Shorter description",
         "recommended_age_from": 14,
         "duration_min": 75,
         "video_url": null,
         "video_type": null,
         "ext_project_url": null,
         "press_quotes": null,
         "seats":120,
         "label_names":[
           "Classic",
           "Schools"
         ],
         "org_name":"Beckett \u0026 Jacks",
         "organization_id":"58d380870428ea0001b82a12"
      }
   ],
   "lineup_dates": [
      {
         "id":"58dbb91c3a9d9c0001d7f197",
         "lineup_org_id":"58d380ad0428ea0001b82a17",
         "lineup_event_id":"58dbb8ca3a9d9c0001d7f191",
         "label_names":[
             "Classic",
             "Schools"
         ],
         "venue_name":"The Globe",
         "title":"Romeo and Juliet",
         "seats":120,
         "available_seats":35,
         "waiting_seats":0,
         "sold_seats":85,
         "note": "In case of rain, no umbrellas allowed",
         "starts_at":"2017-04-26T18:00:00.000Z",
         "duration":null,
         "is_premiere":false,
         "is_derniere":false,
         "cancelled":false,
         "tickets_info_email":null,
         "tickets_info_phone":null,
         "tickets_info_url":null
      }
   ]
}

Lineup Events describe a production, a concert tour, a performance, a sport event (with one or multiple dates). A LineupDate is a logical unit, a container for the actual dates.

HTTP Request

GET https://app.ticketteer.com/api/v1/lineup_events/public

Query Parameters

Parameter Default Description
future false If set to true, the result will only include upcoming events

Response

The response will include lineup_events and according lineup_dates. This decision was made for convenience processing the results. It is very seldom, a request really needs just the events without the dates. You will notice, there are a few more informational values, which are not discussed here.

Response Objects

Parameter JSON-Type Class
lineup_dates Array LineupDate
lineup_events Array LineupEvent

Selection of response values

Parameter Type Description
title String The main title of the event
seats Integer The amount of seats set up for this event. Seats can come from the connected venue or have been set up for this very event.

LineupDate

List LineupDates for a known LineupEvent (id) https://app.ticketteer.com/api/v1/lineup_events/59140beadcec460001ec6c95

curl "curl -X GET --header 'Accept: application/json' \
--header 'Authorization: $PUB_KEY' \
'https://app.ticketteer.com/api/v1/lineup_events/$LINEUP_EVENT_ID'"

# example ():

curl "curl -X GET --header 'Accept: application/json' \
--header 'Authorization: 7e5cc068c4b2d7ea92495b43223d6625563239708023c05d69ed8aa91edd43e1' \
'https://app.ticketteer.com/api/v1/lineup_events/59140beadcec460001ec6c95'"

// this example uses jQuery, you can use plain javascript as well
var apiEndpoint = 'https://app.ticketteer.com/api/v1';
var publicKey = '7e5cc068c4b2d7ea92495b43223d6625563239708023c05d69ed8aa91edd43e1';
jQuery.ajax({
  url: baseUrl + '/lineup_events/{$lineup_event_id}',
  type: 'GET',
  headers: {
    Authorization: '7e5cc068c4b2d7ea92495b43223d6625563239708023c05d69ed8aa91edd43e1'
  },
  dataType: 'json'
}).done(function (response) {
  // continue processing with `response.data.lineup_events`;
});

LineupDate Response Object

{
   "lineup_dates": [
      {
         "id":"58dbb91c3a9d9c0001d7f197",
         "lineup_org_id":"58d380ad0428ea0001b82a17",
         "lineup_event_id":"58dbb8ca3a9d9c0001d7f191",
         "label_names":[
             "Classic",
             "Schools"
         ],
         "venue_name":"The Globe",
         "title":"Romeo and Juliet",
         "seats":120,
         "available_seats":35,
         "waiting_seats":0,
         "sold_seats":85,
         "note": "In case of rain, no umbrellas allowed",
         "starts_at":"2017-04-26T18:00:00.000Z",
         "duration":null,
         "is_premiere":false,
         "is_derniere":false,
         "cancelled":false,
         "tickets_info_email":null,
         "tickets_info_phone":null,
         "tickets_info_url":null
      }
   ]
}

A LineupDate stores additional information like note about special conditions, seats (in order: venue, event, date) and gives information about the actual booking status.

HTTP Request

GET https://app.ticketteer.com/api/v1/lineup_dates

Query Parameters

none

Response

The response will include lineup_events and according lineup_dates. This decision was made for convenience processing the results. It is very seldom, a request really needs just the events without the dates. You will notice, there are a few more informational values, which are not discussed here.

Response Objects

Parameter JSON-Type Class
lineup_dates Array LineupDate
lineup_events Array LineupEvent
lineup_orgs Array LineupOrg

Selection of response values

Parameter Type Description
title String The main title of the event
seats Integer The amount of seats set up for this event. Seats can come from the connected venue or have been set up for this very event.

TicketPriceCategories

To list all ticket price categories, type:

A ticket price category defines a ticket price for a specific date. As pricing models can vary quite large, Ticketteer provides a very flexible way to define ticket prices:

Prices scope

| Level | Scope | Description | ——— | ———– | lineup_date | Date | The price sticks to the date object of the lineup event. It is only valid for this very date. | | lineup_event | All event dates | Defined inside the lineup event. | | lineup_org | All dates connected to this organization | Defined inside the lineup_org (venue) | | global | All dates | Defined in the global settings prices dialog |

Getting all prices for a specific lineup_date

curl "curl -X GET --header 'Accept: application/json' \
--header 'Authorization: $PUB_KEY' \
'https://app.ticketteer.com/api/v1/ticket_price_categories/public?lineup_date_id=$LINEUP_DATE_ID'"

# example ():

curl "curl -X GET --header 'Accept: application/json' \
--header 'Authorization: 7e5cc068c4b2d7ea92495b43223d6625563239708023c05d69ed8aa91edd43e1' \
'https://app.ticketteer.com/api/v1/ticket_price_categories/public?lineup_date_id=59140d9cdcec460001ec6c9d'"

// this example uses jQuery, you can use plain javascript as well
var apiEndpoint = 'https://app.ticketteer.com/api/v1';
var publicKey = '7e5cc068c4b2d7ea92495b43223d6625563239708023c05d69ed8aa91edd43e1';
var lineupEventId = 'YOUR_LINEUP_DATE_ID';
jQuery.ajax({
  url: baseUrl + /ticket_price_categories/public?lineup_date_id='+lineupEventId,
  type: 'GET',
  headers: {
    Authorization: '7e5cc068c4b2d7ea92495b43223d6625563239708023c05d69ed8aa91edd43e1'
  },
  dataType: 'json',
}).done(function (response) {
  // continue processing with `response.data.lineup_events`;
});

TicketPriceCategory Response Object

{
   "ticket_price_categories":[
      {
         "id":"59140bffdcec460001ec6c96",
         "name":"Default Price",
         "price":14.0,
         "contingent":-1,
         "is_public":true,
         "subscription":false,
         "lineup_event_id":"$LINEUP_EVENT_ID",
         "lineup_org_id":null,
         "lineup_date_id":null,
         "created_at":"2017-05-11T09:00:15.065+02:00",
         "updated_at":"2017-05-11T09:00:15.065+02:00"
      }
   ]
}

The most common use case is to have a lineup_date and you want to list all options for this date.

Lineup Events describe a production, a concert tour, a performance, a sport event (with one or multiple dates). A LineupDate is a logical unit, a container for the actual dates.

HTTP Request

GET https://app.ticketteer.com/api/v1/ticket_price_categories/public?lineup_date_id=$LINEUP_DATE_ID

Query Parameters

Parameter Default Description
lineup_date The lineup_date, you want to get prices for

Response Objects

Parameter JSON-Type Class
ticket_price_categories Array TicketPriceCategory

Selection of response values

Parameter Type Description
contingent Number The configured amount of tickets available for this category. This does Not give information on how many tickets have been sold for this cateogry!
is_public Boolean The Ticketteer Admin can define, if the price is publicly accessible or only for internal use (e.g.: free tickets, press tickets, …)
name String The name of this category which is usually shown to the visitor
price Float The price in the organization’s currency
subscription Boolean This price item should be marked as special. Usually the price for this item is 0, as the visitor is holder of a pre-paid subscription.

TicketOrders

A ticket order consists of LineupDate information and an array of tickets, the visitor has chosen.

Posting a TicketOrder

To post a ticket order

curl "curl -X POST --header 'Accept: application/json' \
--header 'Authorization: $PRIV_KEY' \
'https://app.ticketteer.com/api/v1/public_ticket_orders'"

# example ():

curl "curl -X POST --header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: 7e5cc068c4b2d7ea92495b43223d6625563239708023c05d69ed8aa91edd43e1' \
--data 'lineup_date_id=$LINEUP_DATE_ID&email=$EMAIL&\
firstname=$FIRSTNAME&lastname=$LASTNAME&items[amount]=$AMOUNT&\
items[ticket_price_category_id]=$TICKET_PRICE_CATEGORY_ID'
'https://app.ticketteer.com/api/v1/ticket_price_categories/public?lineup_date_id=59140d9cdcec460001ec6c9d'"

TicketOrder Response Object

{ "ticket_order_id": $TICKET_ORDER_ID }

Query Parameters

Parameter Required Description
lineup_date_id true The lineup_date_id, you want to post tickets to
email true The email address of the visitor
firstname true The firstname of the visitor
lastname true The lastname of the visitor
company false The company name if the booking should be saved under an organizational reference
items true A simple array consisting of an object with properties amount and ticket_price_category_id.

Response Objects

Parameter JSON-Type Class
ticket_order_id String

Errors

The Ticketteer API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your API key is wrong
403 Forbidden – The requested is hidden for administrators only
404 Not Found – The specified entity could not be found
405 Method Not Allowed – You tried to access an object with an invalid method
406 Not Acceptable – You requested a format that isn’t json
429 Too Many Requests – You’re requesting too many objects! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Recipes

Website - Creating a customized booking wizard

You need to create a link between the events in your website and the according IDs in Ticketteer. The easiest way is to make your editor copy and paste the entire public link for an event. This can be done in the Edit Event form with the external-link-icon (as shown in the screenshot below).

Simple way

Find the icon to open the public booking form in a new tab

That link could be filled in somewhere in your client’s CMS and referenced to the CMS-event object. Then, you extract the id from the object. Now you can perform your /lineup_events/public-request:

  1. GET /lineup_events/public
  2. calculate the available seats and provide feedback
  3. GET /ticket_price_categories/:lineup_date_id and provide them as a selection to the visitor
  4. create an array of order items in javascript.
  5. (optionally) check with GET /public_ticket_orders/check?lineup_date_id=:ID if the amount of tickets is still available
  6. place the order with POST /public_ticket_orders (see the according section of what parameters are required)

Website - Synchronise Events, Dates and Venues with Ticketteer

To sync a date with ticketteer:

curl "curl -X POST --header 'Accept: application/json' \
--header 'Authorization: $PRIV_KEY' \
'https://app.ticketteer.com/api/v1/lineup_dates/sync'"

# example ():

curl "curl -X POST --header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: 7e5cc068c4b2d7ea92495b43223d6625563239708023c05d69ed8aa91edd43e1' \
--data 'foreign_id=$YOUR_CMS_DATE_ID&\
lineup_event_foreign_id=$EVENT_TITLE&\
lineup_event_title=$EVENT_TITLE&\
lineup_event_description=$OPTIONAL_EVENT_DESCRIPTION&\
lineup_org_foreign_id=$YOUR_CMS_VENUE_ID&\
lineup_org_title=$VENUE_TITLE&\
starts_at=$DATE&\
'https://app.ticketteer.com/api/v1/lineup_dates/sync'"

Syncing from a CMS provides the box office team with much more comfort, as they enter and update events, venues and dates only in their very own CMS.

We highly encourage you doing this, as there is no other way to get two systems like a CMS and Ticketteer in sync.

To sync any kind of data, be it a venue, an event description or the date itself, you can always use: lineup_dates/sync to sync it.

Seats and prices still have to be configured inside the Ticketteer Application.

HTTP Request

POST https://app.ticketteer.com/api/v1/lineup_dates/sync

Post Parameters

Parameter Type Required Description
lineup_event_foreign_id String required Id in your CMS. This allows us to UPDATE existing fields
lineup_event_title String required The title of the event
lineup_event_description String optinoal An optional string short description (useful for facebook integration)
lineup_org_foreign_id String required Id in your CMS. This allows us to UPDATE existing fields
lineup_org_title String required The name of the venue (might have changed, might be new, depends, if we find lineup_org_foreign_id)
starts_at ISODate required An ISO8601 Date String, e.g: 2017-09-22T14:01:54.9571247Z

Alternatives