Tixly Admin API

Tixly provides an administration API to enable external planning or venue management software to create events and productions in Tixly and retrieve sales data for these events.

The admin API was initially built to the specifications of Yesplan, and additional endpoints were added later. This is why the authorisation differs from the CRM API (basic vs Bearer token), and some names are not purely Tixly, such as "Production" instead of "Event Group."

 Access to the admin API is configured in the Venue Management module of Tixly and includes a number of configuration options:

1. Organisation

   1. Selects an organisation that will be the owner of the created events/groups.

2. Filter by Organisation

   1. If set to yes, restricts access to retrieve information only for events of this organisation.

3. Manual Connection

   1. If set to yes, a back-office user can add/edit/remove the external ID on events from the Tixly interface.

4. Disabled Values

   1. Allows you to make some event properties read-only in the Tixly interface. This means they can only be changed from the management software, ensuring data consistency on both ends. Examples include Event Name, start and end dates.

Outline of working with the API

Event groups and events are initially created in the venue management software. When they need to be made available in Tixly, the management software can push them using this API.

If there are changes or updates to event information in the venue management system, these events can be pushed again to be updated in Tixly. Upon the creation of event groups and events in Tixly, the ID of the generated entities is returned and can be stored in the venue management system.

In Tixly, events are then prepared for sale, including setting prices, quotas, and specifying ticket layouts.

When the events are sold, there are several routes available to fetch sales data.

The api uses basic HTTP authentication: all requests should include a header Authorisation with the scheme “Basic”.

All data is exchanged in json format. The date-time values are exchanged as JSON strings based on the ISO 8601 standard.

https://adminapi.{country url}/v1/swagger/ui/index

Get mappings

The first step it to request the available mappings to get a list of HallConfigurations, Promoters, Seasons and EventCategories that can be used when creating events. A user of the planning system might be shown this as a list of options to choose from when configuring the events.

Use  GET /admin/mappings

Create a production

Push the production details from the planning system to Tixly.

POST /admin/productions

{
"production-id": "P-S-1", 
"name": "The first production from this system", 
"sub-title": "SKG2023",
"description": "The best show in Iceland... ",
"available-online": true,
"big-image": "https://cdn.myexamplevenue.com/media//16922-10.jpg",
"small-image": "https://cdn.myexamplevenue.com/media//16922-10-b.jpg"
}

The production-id is the planning systems ID that you then later can use in calls as {externalID}.

To get the production details: GET /admin/productions/{externalID} or to update the production details with PUT /admin/productions/{externalID}.

Tixly downloads the images from the URLs you add to Tixly's own system and uses them as-is in the buying flow.

Create  events

Now you can create the events for this production.

Use your own event-id  and reference your production, as you see in the first two properties.

The seasons, hallconfigurations and eventcategory expect a single value each from the mapping list.

POST /admin/event

{
"event-id": "2d35c887-fa87-4ff5-9edb-8eac42348f87",
"production-id": "P-S-1",
"name": "Margôt Ros",
"starttime": "2024-09-22T17:00:00",
"endtime": "2024-09-22T18:30:00",
"onlinesalestart": "2024-01-01T09:30:00",
"seasons": "1",
"hallconfigurations": "47",
"eventcategory": "25",
"note-1": "Example note",
"note-2": "More notes"
}

It is also possible to send images with this /admin/events, those will replace the images at the primary event group of this event.

Your own event-id can be used as {externalId} to get, update or delete an event.

Only events that have no tickets on them can be deleted!

Retrieving sales information

You can retrieve event sales statistics per event with: GET /admin/events/{externalID}.

And for all events in a month use: GET /admin/events.

The above methods return only events that have an external ID set and use the following output format.

Example output:

{
"tix-event-id": "55177",
"event-id": "EX-0002",
"production-id": null,
"name": "Amélie de musical",
"admin-name": "",
"location": "",
"starttime": "2023-08-19T19:35:00+02:00",
"endtime": "2023-08-19T22:30:00+02:00",
"in-sale": true,
"closed": true,
"salestatus": 0,
"salestatustext": "None",
"ticketscapacity": 2208,
"ticketssold": 34,
"ticketsfree": 0,
"ticketsreserved": 9,
"ticketsallocated": 0,
"ticketsblocked": 7,
"ticketsavailable": 2158,
"ticketstotal": 43,
"ticketstemporarilyreserved": 0,
"ticketsheldforsubscribers": 0,
"ticketsrevenue": 3025,
"ticketsrevenue-excluding-vat": 2775.23,
"productiononline": "1",
"eventonline": "1"
}

The next two routes return all events, including those without an external ID. Optionally, the output can be restricted by a setting in Tixly to only return those connected to the organisation set up in the credentials. What you use depends on your situation.

If you need to get details on events that took place, eg. all yesterdays events. Or need to have a status on all events in a certain week, use GET /admin/GetEventsByEventDates.

If you are interested in all events, and want to get new data on those that had sales activity in e.g. the last day, you can use GET /admin/GetEventsBySalesDates.

The output of these two routes are arrays grouped by EventId, Ticket Type, Price zone, and Section, giving you rather detailed sales information. eg. sales in 3 price zones, each 5 ticket types wil return 15 objects like this example;

{
"ExternalId": "EX-0002",
"EventId": 55177,
"AdminName": "",
"Name": "Amélie de musical",
"StartDate": "08/19/2023 19:35:00",
"Venue": "Example Venue",
"Hall": "Big Hall",
"TicketTypeId": 749,
"TicketType": "Normaal",
"PriceZoneId": 1,
"PriceZone": "1",
"SectionId": 721,
"Section": "Balcony B",
"SoldTickets": 0,
"SoldRevenue": 0,
"ReservedTickets": 1,
"ReservedRevenue": 135,
"Capacity": 2201
},

The above capacity is about the whole event, the sold and reserved numbers are for this combination of EventId, Ticket Type, Pricezone and Section.

Only such combinations that have sales or reservations on it are in the output.

Retrieve sales data over a period of time.

This retrieves all tickets with seat details and customer information that were sold over a specified period.  You can use this for example get sales every hour to keep your external system up to date with the latest sales.

Route to use is:  GET /admin/GetTicketsBySalesDates.

The output is an array with tickets like this Example output;

{
"CustomerId": 1620265,
"CustomerName": "Kim Howick",
"FirstName": "Kim",
"LastName": "Howick",
"CustomerEmail": "[email protected]",
"Mobile": "615525685",
"AddressOne": "Blaine 1",
"AddressTwo": "",
"City": "Sneek",
"ZipCode": "8604",
"Country": "Nederland",
"TicketId": 30322525,
"TicketTypeId": 749,
"TicketType": "Normaal",
"PriceZoneId": 1,
"PriceZone": "A",
"Price": 30,
"Created": "04/04/2023 15:58:55",
"TransactionType": 1,
"ExternalId": "E-55-772b",
"EventId": 71845,
"Section": "Zaal",
"RowName": "12",
"SeatName": "6"
},