Skip to main content

API v.1

1. Introduction

Note: API v.1 is one of our legacy APIs and we no longer support this version for new integrations.

Whilst we will not be adding new features into this version, we will maintain this API for the foreseeable future to support legacy integrations. We do not currently have any plans to switch off this API but will notify known users if this situation changes.

New integrations should use the current version of our API.

The Spektrix Api v1.0 is designed to allow 3rd party web applications to retrieve an events feed from the Spektrix system. The feed provides basic event information and the dates and times of the instances of each event. The information is thus quite ‘high level’ and does not include a lot of the intricate details that the Spektrix system itself deals with - the aim at v1.0 was to allow 3rd party websites to be able to filter and list events to provide event calendar and event list functionality.

To proceed to selling the event the 3rd party website should pass the customer into the Iframe booking path. We recommend this transition occurs at the chooseseats.aspx Iframe to create a smooth booking experience with the least number of steps. Details of how to integrate the Iframes can be found here.

The Spektrix API v1.0 supports two protocols, SOAP and REST. The following sections give an overview of the interfaces available on each protocol.

2. System Concepts

Note that the terms event and event instance used in this section refer to internal Spektrix system data, not the data available through the API. For more information on terms used in Spektrix, please refer to our glossary of system concepts

3. Polling

To improve the performance of your website it can be advantageous to poll the Spektrix API and cache the data locally. While this can be an effective way to increase performance polling too frequently can put unnecessary load on the Spektrix servers. To discourage abuse, the Spektrix API caches the data itself. If polling occurs at too high a frequency than the API will simply return the cached record, not the fresh version. If you do poll for data, please do not poll more than once every 30 minutes for data.

4. SOAP Events Interface

Figure 1 - UML Style Overview

The SOAP Events web service has a schema that maps onto the conceptual UML diagram shown in Figure 1. Data are represented as properties of dumb classes and the API functions are represented as methods of interfaces. Please refer to Section 6.1 for a detailed description of the data obtained from the interface.

The service can be accessed at

https://system.spektrix.com/clientname/api/v1/events.svc

and its WSDL can be obtained through

https://system.spektrix.com/clientname/api/v1/events.svc?wsdl

where clientname should be replaced with the appropriate client name, which can be obtained from either the venue or Spektrix support.

4.1. GetByDate

Returns an array of events that have instances between the given dates, or all events if no dates are given. The array of EventTime elements in the events returned will only include instances that occur between the dates given.

Parameters:
dateFromOptionalInclusive date/time. Only events with instances occurring on or after the value will be returned.
dateToOptionalInclusive date/time. Only events with instances occurring on or before the value will be returned.

4.2. GetByDateAllInstances

Returns an array of events that have instances between the given dates, or all events if no dates are given. This differs from GetByDate in that it returns all the instances associated with each event, rather than just those that meet the date requirement.

Parameters:
dateFromOptionalInclusive date/time. Only events with instances occurring on or after the value will be returned.
dateToOptionalInclusive date/time. Only events with instances occurring on or before the value will be returned.

4.3. GetNext

Returns an array of the next n events that have instances that start on or after the current date.

Parameters:
nRequiredAn integer specifying the number of events to return.

4.4. GetEvent

Returns a single event record given an identifier. Calls to this method will populate the Event.Html field.

Parameters:
eventIdRequiredAn integer specifying the event identifier of the event to return.

5. SOAP Authentication Interface

Figure 2 - UML Overview

The SOAP Authentication web service has a schema that maps onto the conceptual UML diagram shown in Figure 2 Figure 2 - UML Overview. Data are represented as properties of dumb classes and the API functions are represented as methods of interfaces. Please refer to Section 6.1 for a detailed description of the data obtained from the interface.

The service can be accessed at

https://system.spektrix.com/clientname/api/v1/authentication.svc

and its WSDL can be obtained through

https://system.spektrix.com/clientname/api/v1/authentication.svc?wsdl

where clientname should be replaced with the appropriate client name, which can be obtained from either the venue or Spektrix support.

5.1. Authenticate

Authenticates a customer, returning their basic details if authentication is successful. Nothing is returned if authentication is not successful.

Parameters:
emailRequiredString containing the email address of the Customer being authenticated.
passwordRequiredString containing the password of the Customer being authenticated.

6. RESTful Events Interface

Figure 3 - UML Overview

The RESTful Events interface can be conceptually viewed as the UML diagram shown in Figure 3.

XML Data is represented by the dumb classes and the RESTful API resources are represented as methods of interfaces. Please refer to Section 6.1 for a detailed description of the data obtained from the interface.

The base address of the Events interface is

https://system.spektrix.com/clientname/api/v1/eventsrestful.svc

where clientname should be replaced with the appropriate client name, which can be obtained from either the venue or Spektrix support.

6.1. GetAllInstancesFrom

https://system.spektrix.com/clientname/api/v1/eventsrestful.svc/alltimes/from?date=\{date}

Returns a set of events that have instances that start between the given dates, inclusive. This differs from GetFrom in that it returns all the instances associated with each event, rather than just those that meet the date requirement. Custom attributes are included in the returned data for events but not for instances.

Parameters:
{date}Date and time value, formatted as YYYY-MM-DDTHH:mm:ss

6.2. GetAllInstancesFromAllAttributes

https://system.spektrix.com/clientname/api/v1/eventsrestful.svc/alltimes/allattributes/from?date={from}

Returns a set of events that have instances that start between the given dates, inclusive. This differs from GetFrom in that it returns all the instances associated with each event, rather than just those that meet the date requirement. Custom attributes are included in the returned data for both events and instances.

Parameters:
{date}Date and time value, formatted as YYYY-MM-DDTHH:mm:ss

6.3. GetAllInstancesFromTo

https://system.spektrix.com/clientname/api/v1/eventsrestful.svc/alltimes/between?dateFrom=\{dateFrom}&dateTo=\{dateTo}

Returns a set of events that have instances that start between the given dates, inclusive. This differs from GetFrom in that it returns all the instances associated with each event, rather than just those that meet the date requirement. Custom attributes are included in the returned data for events but not for instances.

Parameters:
{dateFrom}Date and time value, formatted as YYYY-MM-DDTHH:mm:ss
{dateTo}Date and time value, formatted as YYYY-MM-DDTHH:mm:ss

6.4. GetAllInstancesFromToAllAttributes

https://system.spektrix.com/clientname/api/v1/eventsrestful.svc/alltimes/allattributes/between?dateFrom={from}&dateTo={to}

Returns a set of events that have instances that start between the given dates, inclusive. This differs from GetFrom in that it returns all the instances associated with each event, rather than just those that meet the date requirement. Custom attributes are included in the returned data for both events and instances.

Parameters:
{dateFrom}Date and time value, formatted as YYYY-MM-DDTHH:mm:ss
{dateTo}Date and time value, formatted as YYYY-MM-DDTHH:mm:ss

6.5. GetEvent

https://system.spektrix.com/clientname/api/v1/eventsrestful.svc/details/{eventId}

Returns the details of a specific event, including all it’s instances, attributes and wiki-text (rendered as HTML). Custom attributes are included in the returned data for events but not for instances.

Parameters:
{eventId}Integer value specifying the identifier of the Event

6.6. GetEventAllAttributes

https://system.spektrix.com/clientname/api/v1/eventsrestful.svc/details/allattributes/{eventId}

Returns the details of a specific event, including all it’s instances, attributes and wiki-text (rendered as HTML). Custom attributes are included in the returned data for both events and instances.

Parameters:
{eventId}Integer value specifying the identifier of the Event

6.7. GetFrom

https://system.spektrix.com/clientname/api/v1/eventsrestful.svc/from?date=\{date}

Returns a set of events that have instances that start between the given dates, inclusive. This differs from GetAllInstancesFrom in that the instances associated with each event are filtered by the date parameter. Custom attributes are included in the returned data for events but not for instances.

Parameters:
{date}Date and time value, formatted as YYYY-MM-DDTHH:mm:ss

6.8. GetFromAllAttributes

https://system.spektrix.com/clientname/api/v1/eventsrestful.svc/allattributes/from?date={from}

Returns a set of events that have instances that start between the given dates, inclusive. This differs from GetAllInstancesFrom in that the instances associated with each event are filtered by the date parameter. Custom attributes are included in the returned data for both events and instances.

Parameters:
{date}Date and time value, formatted as YYYY-MM-DDTHH:mm:ss

6.9. GetFromTo

https://system.spektrix.com/clientname/api/v1/eventsrestful.svc/between?dateFrom=\{dateFrom}&dateTo=\{dateTo}

Returns a set of events that have instances that start between the given dates, inclusive. This differs from GetAllInstancesFrom in that the instances associated with each event are filtered by the date parameters. Custom attributes are included in the returned data for events but not for instances.

Parameters:
{dateFrom}Date and time value, formatted as YYYY-MM-DDTHH:mm:ss
{dateTo}Date and time value, formatted as YYYY-MM-DDTHH:mm:ss

6.10. GetFromToAllAttributes

https://system.spektrix.com/clientname/api/v1/eventsrestful.svc/allattributes/between?dateFrom={from}&dateTo={to}

Returns a set of events that have instances that start between the given dates, inclusive. This differs from GetAllInstancesFrom in that the instances associated with each event are filtered by the date parameters. Custom attributes are included in the returned data for both events and instances.

Parameters:
{dateFrom}Date and time value, formatted as YYYY-MM-DDTHH:mm:ss
{dateTo}Date and time value, formatted as YYYY-MM-DDTHH:mm:ss

6.11. GetNext

https://system.spektrix.com/clientname/api/v1/eventsrestful.svc/next?n={n}

Returns a list of the next n events to occur. Custom attributes are included in the returned data for events but not for instances.

Parameters:
{n}Integer specifying the number of events to retrieve

6.12. GetNextAllAttributes

https://system.spektrix.com/clientname/api/v1/eventsrestful.svc/allattributes/next?n={n}

Returns a list of the next n events to occur. Custom attributes are included in the returned data for both events and instances.

Parameters:
{n}Integer specifying the number of events to retrieve

7. API Data Description

Note that the event data provided by APIv.1 is based mainly on the information stored in the internal system event data only. Detailed event instance information, including seating area and venue information are therefore not provided in this API. This data should be displayed using an Iframe pointing to the ChooseSeats.aspx page. More details on the Iframe integration can be found here.

The following section details the classes of data that the API provides.

NB: We do not guarantee the order in which XML elements will appear.

7.1. Event

Elements:
AttributesAn array of EventAttribute elements. These are custom attributes that the client has full control over. These are entered by the client when creating an Event in the Spektrix Admin Interface
DescriptionA ‘teaser summary’ of the Event. This is unlimited in length
DurationThe duration of the Event, in minutes
FirstInstanceThe date and time of the first instance of this event
HtmlThe html code generated from the wiki-text entered in the admin interface. This is unlimited in length and is not be returned unless specified in the service call documentation
ImageUrlThe fully qualified URL for the image associated with the event, if one has been uploaded
LastInstanceThe date and time of the last instance of this event
NameThe name/title of the Event. This is limited to 100 characters
OnSaleOnWebIndicates whether the event is on sale on the website values are ‘true’ or ‘false’
ThumbnailUrlThe fully qualified URL for the thumbnail image associated with the event, if one has been uploaded
TimesAn array of EventTime elements. These represent the Event Instances
WebEventIdA configurable, unique identifier entered by a system admin user in the Admin Interface. This allows linking with third part CMS systems

7.2. EventAttribute

Elements:
NameThe name of the attribute, as entered by the client when creating the event in the Spektrix Admin Interface. This is limited to 50 characters
ValueThe value of the attribute, as entered by the client when creating the event in the Spektrix Admin Interface. This is limited to 200 characters

7.3. EventTime

Elements:
AttributesAn array of EventAttribute elements. These are custom attributes that the client has full control over. These are entered by the client when creating an Event in the Spektrix Admin Interface
CapacityThe total capacity of the event instance
EventInstanceIdThe id of the Spektrix event instance referred to by this item. Event instances are an internal system item, this is just a reference identifier to be used when linking to pages hosted on the Spektrix system (via Iframes)
SeatsAvailableThe number of seats available
SeatsLockedThe number of seats that are locked
SeatsReservedThe number of seats that have been reserved
SeatsSelectedThe number of seats that are selected by users (i.e. in their basket)
SeatsSoldThe number of seats that have been sold
TimeThe start date/time of this event instance
WebInstanceIdA configurable, unique identifier entered by a system admin user in the Admin Interface. This allows linking with third part CMS systems