Skip to main content

Overview

The current API is our third public version. It is a RESTful, JSON-based API. It exposes a far greater range of functionality than either of our legacy APIs, while also being more user-friendly and with more comprehensive documentation. Newer integration options such as our Web Components are also built on top of our API.

Use the menu options to the left for detailed guidance and examples on many aspects of the API, such as looking up Event information, adding items to a users basket and adding customer data.

Terms of use

Our terms of use can be found here.

Modes​

An important point to note is that the API is available with three different modes, outlined below.

Web User / Public​

  • This is designed to expose similar information to that found via Spektrix Iframes, e.g. event listings, prices, merchandise and so on.
  • As this information is all public, there is no need for authentication when using Web User mode.
  • It can also enable you to build baskets and create orders in the same way as you could via an Iframe - i.e. one customer at a time - via client-side site integrations.
  • It’s possible to share sessions between the API and the Iframe purchase path, allowing you to build bespoke booking paths that incorporate both elements.
  • It’s not currently possible to build a full end-to-end purchase path, as there are elements of payment processing that are not exposed by the API.

Agent​

  • This is specifically for access by third party agents who will be buying tickets from the system owner through a credit agreement.
  • This mode requires authentication for all calls as information may change on a per-agent basis.
  • The system owner will provide access credentials for agents, who can each be set up with multiple customer records, each with different sales commission agreements, seat access and discounting where necessary.
  • Agents will need a separate e-mail address for each record held on a single system, and will be asked to provide a mobile phone number for 2 factor authentication purposes.
  • The Agent mode allows the creation, management and confirmation of multiple concurrent baskets, and provides full end-to-end purchase, with all transactions recorded against system credit logged against the specific API user’s account.

System Owner​

  • This enables full access to the entire system, including objects not available via the Iframes.
  • As this mode can expose sensitive customer data, it requires authentication.
  • It’s intended for use in server-side integrations created and managed by system owners and their appointed developers.
  • It’s not currently possible to build a full end-to-end purchase path, as there are elements of payment processing that are not exposed by the API.

Full Endpoint List​

A full list of all available endpoints can be found at;

https://system.spektrix.com/apitesting/api/v3/Help

The above help page provides information for all available endpoints including examples of available request parameters and responses.

Methods​

The API supports GET, POST, PATCH, PUT and DELETE methods. This section provides an overview of their behaviour.

note

Not all resources in the API support all methods. The documentation for each resource will detail which methods are supported.

GET​

The GET method is used to retrieve resources.

POST​

The POST method is used for creating resources and for invoking other actions that don't fit naturally in the RESTful paradigm. When a resource is successfully created the response to the POST request will contain the new resource and its identifier. For efficiency the API allows related sub-resources to be created at the same time by including them in the request.

PATCH​

The PATCH method is used to change resources. Only the fields that are specified will be updated and updates will be atomic. However, only first level properties of the resource can be modified. To modify related sub-resources (customer addresses, for example) a separate request is required. A PATCH to multiple items sets the provided properties to the provided value on all specified items.

PUT​

A PUT method replaces all the items in a collection with what you provide. For example, a PUT to v3/basket/tickets will replace all the tickets with what you supply.

DELETE​

The DELETE method deletes resources.

Client side vs Server side calls​

Server side​

Making a large number of API requests at once can negatively impact the performance of your website. We strongly recommend making cached server side calls when responses don't change often. For example, but not limited to, events, instances, funds, memberships, plans, price lists etc. This will avoid browser slow-down and rate limiting. Depending on the needs and system set up of the client, you can choose the frequency of refreshing these calls.

Client side​

To seamlessly combine our tools during the website purchase path, we recommend making client side calls when the response is dynamic and changes based on the current session or logged in customer. Examples of such calls are basket and customer. To ensure that the session is carried over between sending and retrieving information related to the basket of current session and logged in customer, you'll need to explicitly include cookies as part of your call. For client side calls you need to ensure:

  • You have a custom domain setup for use with your client.
  • API calls relating to the current session use Web/Public Mode
  • You explicitly include cookies as part of your call, by setting XMLHttpRequest’s withCredentials property to true such as xhr.withCredentials = true.

Resources​

API version 3 follows the RESTful paradigm and exposes data via resources that are identified by URLs. The API uses three forms of URL:

  1. .../api/v3/{resource}
  2. .../api/v3/{resource}/{id}
  3. .../api/v3/{resource}?param1=value1&param2=value2&...

In the above, 1 specifies all resources of type {resource}, 2 specifies the resource identified by {id}, and 3 specifies a query over the resources, returning only those resources that match the parameters.

Sub-resources and $expand​

There are some resources that are not exposed by the API by default. Additionally, many resources have related sub-resources, which are not returned by default either. Sub-resources and resources that are not exposed by default can be requested using the special parameter $expand. There are two forms of $expand:

  1. ...?$expand=path/of/resource/to/expand
  2. ...?$expand={depth}

In the above, 1 will expand all resources on the path provided. You can expand multiple resources by listing them one after the other separated by a comma. 2 will expand all resources to the specified depth integer. In most cases, it will be faster to only expand the required subresources, as the payload will be smaller.


Last updated on by Nina Primeraki