API v.2

Note - Read before continuing

API v.2 is one of our legacy APIs and we no longer support this version for new integrations. We are not adding new features into this version.

customer objects

We will be deprecating the customer objects of the API by the end of 2024.

We are planning to continue maintaining the other endpoints of this API for the foreseeable future to support legacy integrations. We do not currently have any plans to completely switch off this API but will notify known users if this situation changes.

New integrations should use the current version of our API.

API Overview

The Spektrix Api v2 is designed to allow 3rd party web applications to retrieve events and instance feeds from the Spektrix system, as well as create basic customer records.

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 Iframe can be found here.

We have tried to design the api from a user's perspective. The main idea being to keep all the data structures as flat as possible, returning simple lists of data structures that can be cached in associative arrays or dictionaries. More advanced integrations may want to either keep associative arrays of data in RAM on each web server, put the data straight into memcached or insert the data into a database of some sort.

Base Address

The Spektrix API v2 can be accessed at

https://api.system.spektrix.com/clientname/api/v2

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

For the rest of this guide it should be assumed that https://api.system.spektrix.com/client_name is prepended to the quoted API uris.

Endpoints and Schema

For detailed information about the actions available and the data structures the API uses please go to

https://api.system.spektrix.com/apitesting/api/v2/help

Note You may need to dust off your copy of IE to access the API v2 schema. The modern browsers no longer support the tech used to generate this schema and since this version of the API is now deprecated we have not been able to update it.

Paging

By default some GET requests will return a maximum of 10 items. To specify exactly which items you want you can use the parameter limit to determine how many items you want and offset to determine which item should be first. If you want all items please specify all=true.

Attributes and Identifiers

Attributes

Many objects in Spektrix can have user defined attributes attached to them. For relevant items these are accessible via the API. Note that certain attributes can be required when modifying or creating objects and you will receive a validation error if this is the case.

Attributes are set up by the venue in the Spektrix Settings Interface and therefore can vary from venue to venue. If you need additional attributes set-up for filtering or to pull through extra information please contact the venue you are working with.

Identifiers

Most data objects retrieved from the Spektrix system have an identifier. This identifier uniquely identifies the object in the Spektrix system. However, please note that if you are working on a run or staging system, the ids for the objects you’re working with will change when you migrate to the live system.

Verbs: PATCH and X-HTTP-Method-Override**

Updating objects via the Spektrix API requires using the PATCH verb. Unfortunately, however, a lot of clients don’t yet support the PATCH verb. If the client you are using has this problem it can be overcome by issuing a POST request instead and specifying the header ‘X-HTTP-Method-Override’ and setting its value to ‘PATCH’.

Sessions & Basket (deprecated)

Note: The basket functionality in API v.2 is deprecated and we cannot guarantee continued operation. To create baskets, please use the current version of our API.

As a customer navigates your site they will be building up a basket full of items that they want to buy. A basket is linked to a customer’s session on Spektrix and only one basket per session may exist. It can be accessed at the uri /api/v2/basket.

When you first add an item or make a change to the basket a session cookie will be returned with the response from Spektrix. You must store this cookie and submit it with future requests – it is this that identifies the basket and links it to Spektrix’ session handling. Note that a GET request with no session cookie (or a session that has timed out) will return a 404 because you have not identified a session.

A session on Spektrix lasts for a rolling 10 minutes. Every change to the basket resets the session timeout counter. If you want to keep the session alive without making a change to the basket just post the session cookie to /api/v2/keep-alive.

Payment

For payment the customer should be directed to an IFRAME that should point to api/v2/basket/payment. This will take payment details, confirm the order and redirect the customer to a confirmation page that you specify. The IFRAME can by styled by uploading a css style sheet to Spektrix.

The payment process is relatively complex due to PCI requirements and 3D secure and can involve ‘bouncing’ the user’s browser between various sites. In order for this to work correctly you must put the url of the page hosting the payment IFRAME in the Checkout Link parameter in the Website Admin interface. The system uses this parameter to perform redirect between the payment system and Spektrix and the process will not work if the checkout link is not set correctly.

Security

The Spektrix system allows our clients to collect and report on the booking habits of their customers. In doing so a lot of sensitive data about our clients’ customers are stored on our servers and this data is governed by UK data protection regulations. Spektrix has been authorized by our clients to process and manage their data in an appropriate and secure manner. By gaining access to our API you will have access to this data and are therefore also responsible for using it appropriately and securely.

The Spektrix API has been designed with security in mind from the beginning. We use industry standard encryption to protect the data in transit and we require you to authenticate using a client certificate and API key. This mechanism is, in theory, very secure if used correctly. However, if used incorrectly all the security is compromised and you may be liable for prosecution under UK data protection legislation. It is therefore very important that none of the authentication information is ever allowed to be disclosed to un-authorised third parties.

API key

The API key identifies you to Spektrix and allows you to access a specific Spektrix system. It must not be disclosed to anyone and must not be placed in emails or basecamp or any other information sharing system.

If Spektrix become aware that an API key has been sent via email or made public in any way, your key will be regenerated and your API requests will become unauthorized until your integration is updated to use the new key. If you think your API key has been compromised please alert Spektrix support immediately.

To find your API key log in to Spektrix and go to Control Panel -> WebsiteAdmin -> Config.

Client Certificate

It’s important to be aware that the client certificate needs to be renewed on a yearly basis. If the certificate is not renewed before its expiry date, access to the data will be lost as soon as the certificate expires potentially meaning that your website will display information incorrectly.

We therefore recommend that you renew your certificate well within the last month of its validity.

The client certificate proves your identity to us and consists of 3 parts:

Private key (.key file)
Certificate signing request (CSR)
Certificate (.crt file)

Of these three parts, you need to generate two of them yourselves – the private key and the CSR. We need you to send the CSR across to us so that we can use it to generate your certificate, which our engineers will then sign and email back to you, ready to be installed locally.

The private key is extremely sensitive - it should not be disclosed to anybody and it should be kept in a folder on your server that is only accessible to the processes that need to access it. It should never be publicly accessible on the internet so should never be placed in any of your website directories. It should never be transferred using an insecure transport (email, sms, basecamp, ftp etc.).

If Spektrix become aware that a private key has been sent via email or made public in any way, your certificate will be revoked and your API requests will become unauthorized until a new certificate is signed. If you think your private key has been compromised please alert Spektrix support immediately.

The CSR is not sensitive - you can email that to us safely.

Generating your CSR

CSR stands for Certificate Signing Request. Spektrix uses CSRs to confirm the identity of a server or computer trying to access the Spektrix API, a little bit like a digital Passport.

There are many ways to generate CSRs. We'll cover two of the most popular methods.

Using OpenSSL

We recommend this approach if your website will be running on a Linux-based web server, for example Apache.

If you have OpenSSL installed, you can run a command to generate a private key and CSR at the same time. Just replace all the <placeholders> (removing the angled brackets as well) with the suitable values. If there is no agency involved then you can skip those values. The command is run on one line.

openssl req -nodes -newkey rsa:2048 -keyout <client-name>-<agency-name>-<year>.key -out <client-name>-<agency-name>-<year>.csr -subj "/O=<organisation-name>/CN=<client-name>/emailAddress=<webmaster-email-address>"

<client-name> is the client name that you see in the Spektrix URL after system.spektrix.com/. <organisation-name> refers to the client's organisation name which may or may not match the client name.

You can then send Spektrix the CSR file for signing. The CSR file should have a name client-agency-2022.csr if an agency is involved, or client-2022.csr if not.

Using the Windows Certificate Snap-In

We recommend using the Windows Certificate Snap-In if your website will be running on a Windows-based web server, for example IIS. This guide will produce a PFX file containing your private key, which can be stored in the Windows Certificate Store.

If you need the key in a PEM format like that generated by OpenSSL, you will need to use need to use OpenSSH or a similar tool to convert the PFX file generated using this guide. All of the sample code we provide assumes that keys and certificates are in the PEM format.

Firstly, open MMC, which can be done via Run > mmc.exe
Go to File > Add/Remove Snap-in
Add the Certificates snap-in and click OK

Select the appropriate user account and click finish. This is the user which will need access to the private key (e.g. the user your web server will run as). If you are going to export the private key later, you can use My user account here.

Back in the main MMC window, drill down to the Certificates folder and right click in the middle pane, selecting All Tasks > Advanced Operation > Create Custom Request...

Select _Proceed without enrollment policy
Continue through the next screen with the default values of (No template) CNG key and PKCS #10.
On the next screen expand the Details section and click the Properties button.
On the General tab, give your certificate a name (this is for your own reference).

On the Subject tab, add the following subjects:

Organisation: your organisation name
Common Name: your Spektrix client name (this must match the Spektrix system, please check with your project manager/Spektrix Support if unsure)
Email: your webmaster email address

These are for our reference - failing to add these correctly will result in the request not being signed.

On the Private Key tab set the Key size to 2048 and check Make private key exportable. If you do not make the private key exportable the signed certificate will only be usable by the user selected earlier in the process, on the machine you are working on.

Once this is done, continue to the next screen and enter a location for the CSR file using a sensible name, such as [your Spektrix client name]-[web agency name]-[year of request].csr.

Click Finish and send your CSR to the Spektrix Support team.

Once Spektrix return your signed certificate (which will be as a CRT file), copy it to the machine where the request was generated, then double click on it and click _Install Certificate…

Continue through with the default options. You will now be able to see the certificate in MMC.

Checking if your signed certificate has the private key associated

Once you have installed your signed certificate you need to check that the private key you used to generate the CSR is associated with the certificate.

Open the Certificates snap in and double click on your signed certificate. At the bottom of the General tab it should tell you if you have the corresponding client key, as per the below:

If you see this, you can start using the certificate on that machine or export it with its key for use on other machines.

If you do not see this message you will need to perform the following to match the key with the certificate:

Click on the Details tab of the certificate information dialogue box and locate the entry called Thumbprint

Copy this value using CTRL + C and then open a command prompt and enter the following command:

Certutil -repairstore my “<pasted value from above>”

When it has completed you will see the message:

CertUtil: -repairstore command completed successfully.

If you go back and refresh the certificate store the certificate will now have the private key associated with it.

Exporting Your Certificate with the Private Key on Windows

Open MMC, right click on the installed certificate and select All Tasks > Export...

When prompted, select Yes, export the private key.

Export the certificate and private key as a PFX file.

Always, as a minimum, use a strong password to protect the exported key.

Select a location to save the key file to and complete the wizard.

General secure coding practices

We recommend that everyone who works on web applications that talk to the Spektrix API be familiar with industry standard secure coding practices. A good resource is OWASP in particular their top 10.

Publicly accessible test systems

If any test system is accessible on the public internet it should not be possible to execute arbitrary API calls through that system. It is very important that if you use the test php script described later in this guide that that is never accessible over the internet as it allows any api call to be made.

Important note If you are behind an http proxy that decrypts and re-encrypts the traffic between you and Spektrix you will find that the API authentication will not work. Fiddler, in particular, works in this way!

Data Objects

Event and Instance Objects

Event objects can be used to get information on events that are currently bookable online. Typically these objects might be used to generate event pages or event lists/calendars.

Object	Description
Band	Banding is used in price lists to assign different prices for a particular ticket type to particular seats.
Attribute	Most objects can have attributes associated with them. The attributes which are allowed are user definable and allow custom data to be stored against objects in the system.
Event	An event in Spektrix can be thought of as a ‘show’. It encapsulates the descriptive data about an event, such as its Name and Description. It is a container for instances.
Instance	An instance represents an occurrence of an event and contains the Start time, Duration and status of that occurrence of the event. It references the price list and plan that are being used at that time.
Plan	A plan determines what seats available for a particular instance. Plans can be recursive, containing sub plans. Tickets can only be bought for plans where IsBookable is true. A plan with sub plans will never be bookable. Plans also reference a list of the bands that the seats in the plan reference. API v2 only supports unreserved seating so each plan will only ever have one band, which will determine the prices of the seats in that plan.
Price list	A price list gives a price for combinations of ticket type and band. Unreserved plans reference a band. An instance’s price list then dictates which ticket types, and which prices, are available in that area.
Ticket type	A ticket type defines the concession level of a ticket, i.e. ‘Adult’, ‘Student’ etc. These are referenced by price lists and tickets.

Customer Objects - to be deprecated

Note: The Customer objects in API v.2 will be deprecated by the end of 2024. To use customer related endpoints, for example to create custom sign up forms, please use the current version of our API.

Customer Objects can be used to create new customers in the system or get information about existing customers.

Object	Description
Address (to be deprecated by end of 2024)	An address object encapsulates everything related to an address format. These are are used in deliveries in the basket.
Attribute (to be deprecated by end of 2024)	Most objects can have attributes associated with them. The attributes which are allowed are user definable and allow custom data to be stored against objects in the system.
Customer (to be deprecated by end of 2024)	A customer object represents a customer record in Spektrix.
Customer address (to be deprecated by end of 2024)	This is the same as an address, but also contains a Name references a customer. It is used to associate address data with a particular customer.
Statement (to be deprecated by end of 2024)	A statement object represents a Contact Preference. A customer can agree to any, all or none of the statements in the system.
Tag (to be deprecated by end of 2024)	Tags are user defined and customers can be tagged with them. This can be useful for storing yes/no type information against a customer record.
Tag group (to be deprecated by end of 2024)	Tags are organised in groups, each of which has a name.

Deprecated Objects

These objects are now deprecated. To access these objects you should instead use API v3.

Object	Description
Basket (deprecated)	A basket contains all the items a customer wants to buy. Items can be tickets or merchandise items. An offer can be applied to a basket under certain conditions which results in certain items having a discount. A basket also has delivery items, one for tickets and one for merchandise items. Not all delivery types can be used depending on the system setup and the items in the basket. MerchandiseDeliveryOptions and TicketDeliveryOptions specify which delivery types are allowed and their respective fess (given the items in the basket). Please note that if you have set the deliveries in the basket and then modify the contents of the basket, the deliveries you have set may be removed and/or their fee recalculated.
Basket related data (deprecated)	A collection of objects that are referenced by a basket. This is for convenience.
Delivery (deprecated)	A delivery object encapsulates the data required for delivering certain types of items in a basket. There are 3 delivery types: Postal, Cobo (care of box office) and PrintAtHome.
Delivery option (deprecated)	These form part of the basket and define a delivery Type and Fee.
Offer (deprecated)	An offer gives a discount to customers who are eligible for the offer. The discount and eligibility are calculated automatically by Spektrix as items are added to a basket. An offer can contain a collection of PromoCodes which ‘unlock’ the offer. Apart from that the logic for how and when an offer is applied is extremely complex so it must be left up to Spektrix to determine this. It is possible, however, to determine which offers might get applied to a certain customer for a certain event or instance by calling api/v2/offers and passing the appropriate parameters.
Order (deprecated)	An order is created when a basket is paid for. The data for an order are very similar to the data for a basket. An order can contain and number of Payments and a number of Refunds. Although it is not possible to create an order with more than one payment and more than zero refunds through the API, it is possible for an order to be edited on the Spektrix Sales Interface. At that point additional payments or refunds may get added to the order.
Order related data (deprecated)	This is for convenience and is very similar to basket related data and is for convenience. Please note that it may contain objects which are inaccessible via the rest of the API - for example, an old order might reference an event which has been made inactive in the system. Inactive events are not accessible via /api/v2/events. Therefore, please do not rely on cached information when displaying orders.
Merchandise Item (deprecated)	A merchandise item entitles the customer to a single stock item. It can be discounted as part of an offer, in which case it will have an OfferGroup which describes to which ‘application’ of the offer it belongs.
Payment (deprecated)	Encapsulates the data related to a payment. CardNumber will only ever contain the truncated card number and will only be present if the payment was made by card.
Print at home link (deprecated)	Represents a link to a set of tickets for a particular instance for a particular customer. If TicketsReady is true then the customer may download their tickets from the specified url. If false Spektrix is still generating the ticket pdf for the instance.
Stock Item (deprecated)	A stock item represents an item of merchandise that can be bought. Its StockLevel represents how many items are left in stock. A merchandise item referencing a stock item with StockLevel = 0 cannot be added to a basket.
Ticket	A ticket entitles the customer to a seat at an instance. It references a plan, a band and a ticket type. It can be discounted as part of an offer, in which case it will have an OfferGroup which describes to which ‘application’ of the offer it belongs.

Reference

Getting Data

Verb: GET

Resource URI	Paging	URI Parameters	Required	Notes
api/v2/events api/v2/instances api/v2/instance-status api/v2/price-lists api/v2/plans	Yes	event_id instance_id instance_start_from instance_start_to	No No No No
api/v2/offers	Yes	instance_id	No	Ignores customer eligibility
api/v2/offers2	Yes	event_id instance_id customer_id	No	Only 1 of event_id & instance_id
api/v2/customers	No	customer_id email	At least 1
api/v2/customers/addresses api/v2/customers/print-at-home-documents	No	customer_id	Yes
api/v2/customers/print-at-home-download	No	customer_id document_id	Yes
api/v2/orders api/v2/orders/related-data	No	order_id customer_id	Yes	At least 1
api/v2/postcode-lookup	No	postcode	Yes
api/v2/postcode-lookup/address	No	postcode_lookup_id	Yes
api/v2/tags api/v2/tag-groups api/v2/statements api/v2/bands api/v2/ticket-types api/v2/stock-items	Yes
api/v2/basket api/v2/basket/related-data
api/v2/transactions	No	transaction_id order_id	Yes	At least 1

Creating Objects

Verb: POST

Body content type: XML

Resource URI	URI Parameters	Notes
api/v2/customers		Creates customers, returning the customer ids. Email and LastName are required.
api/v2/customers/addresses		Creates addresses for customers, returning the address ids. Name , Line1 , Town , Postcode and Country are required.
api/v2/basket/items		Adds items to the basket. Instance and Plan are required for tickets and StockItem is required for merchandise. Price is required if OverridePrice is true.

Modifying Objects

When updating objects you only need to send the data which you want to be updated.

Verb: PATCH (or PROPPATCH if your client doesn’t support PATCH)

Body content type: XML

Resource URI	Notes
api/v2/customers	Updates the specified customers. CustomerId is required.
api/v2/customers/addresses	Updates the specified customer addresses. CustomerId and CustomerAddressId are required.
api/v2/basket	Updates the basket. Address is required if the Type of a delivery is Postal.
api/v2/basket/items	Updates the specified items. TicketId / MerchandiseId is required. Price is required if the OverridePrice is true.

Deleting Objects

Verb: DELETE

Resource URI	URI Parameters	Notes
api/v2/basket	item_id	Removes and item from the basket.
api/v2/addresses	customer_id address_id	Removes the specified customer address.

Payment

Target: Payment IFRAME

Resource URI	URI Parameters	Notes
api/v2/basket/payment	sesssion name address_line1 address_line2 address_line3 address_line4 address_line5 address_town address_county address_postcode address_country confirmation_url	Provides UI for the customer to pay for their basket. Parameters session , name , address_line1 , address_town ,address_postcode , address_country and confirmation_url are required. Parameter session should contain the contents of the Spektrix session cookie. Parameter confirmation_url must have the same host name as the checkout link that is configured in the Website Admin interface

Other Actions

Verb: POST

Resource URI	URI Parameters	Notes
api/v2/customers/reset-password	customer_id	Resets a customer’s password and emails them the new one.
api/v2/customers/authenticate		Authenticates a customer given Email and Password (both required). Optionally adds the customer to the basket, creating a session linked to that customer.
api/v2/orders/send-confirmation	order_id	Sends a confirmation email to the customer attached to the specified order. NB a confirmation will be sent automatically when the customer pays for the order, so use this only to re- send a confirmation if required.

Examples

Test of getting data from the Spektrix Api (in PHP)

<?php
$curl = curl_init();
$options = array(
CURLOPT_URL =>
"https://api.system.spektrix.com/<client_name>/api/v2/offers?all=true&api_key=<api_key>",
CURLOPT_RETURNTRANSFER => 1,
CURLOPT_SSLCERT => "/path-to/cert.crt",
CURLOPT_SSLKEY => "/path-to/cert.key",
CURLOPT_HEADER => 1
);
curl_setopt_array($curl, $options);
?>
<html>
<head>
</head>
<body>
<h1>Response:</h1>
<verbatim>
<?= htmlspecialchars(curl_exec($curl)); ?>
<verbatim>
<h2>Errors:</h2>
<verbatim>
<?= curl_error($curl); ?>
<verbatim>
</body>
</html>

This is missing the client name and API key, which must be supplied instead of <client_name> and <api_key> above.

Your API Key is a security feature that identifies you to Spektrix and allows you to securely access a specific Spektrix system. It must not be disclosed publicly.

Example of a WebClient customised to work with the Spektrix API (in C#)

public sealed class SpektrixApi : WebClient
{
private const string ApiUrl = "https://api.system.spektrix.com/<clientname>/v2/";
private const string ApiKey = "...";
private readonly string _certFile;
public SpektrixApi(string certFile)
{
_certFile = !string.IsNullOrWhiteSpace(_certFile)
? Path.GetFullPath(certFile)
: @"<yourcertificate>.crt";
}
public static string Get(string apiUrlSegment, string certFile = null)
{
return new SpektrixApi(certFile).DownloadString(Url(apiUrlSegment));
}
public string Post(string apiUrlSegment, string body, string certFile = null)
{
return new SpektrixApi(certFile).UploadString(Url(apiUrlSegment), body);
}

protected override WebRequest GetWebRequest(Uri address)
{
var cert = new X509Certificate2(_certFile, "");
var request = (HttpWebRequest) base.GetWebRequest(address);
Debug.Assert(request != null);
request.ClientCertificates.Add(cert);
return request;
}

private static string Url(string apiUrlSegment)
{
return
ApiUrl
+ apiUrlSegment
+ ArugmentSeparator(apiUrlSegment)
+ "api_key=" + ApiKey;
}

private static string ArugmentSeparator(string urlSegment)
{
return urlSegment.Contains("?")? "&" : "?";
}
}

To use this in C# code:

var results = SpektrixApi.Get(“offers?all=true”);

A complete API test framework (in PHP)

<?php
// Specify SSL client certificate key and certificate file names / paths
// These files should not be in your website directories and should be protected
// so that no-one can read them.
$sslKeyFile = "/path/to/apitest.key";
$sslCertFile = "/path/to/apitest.crt";
// Specify the base URL we are using
$baseURL = "https://api.system.spektrix.com/";
// Make CURL verbose
$curlVerbose = false;

// Magic quotes breaks submitted XML
if (get_magic_quotes_gpc()) {
$process = array(&$_GET, &$_POST, &$_COOKIE, &$_REQUEST);
while (list($key, $val) = each($process)) {
foreach ($val as $k => $v) {
unset($process[$key][$k]);
if (is_array($v)) {
$process[$key][stripslashes($k)] = $v;
$process[] = &$process[$key][stripslashes($k)];
} else {
$process[$key][stripslashes($k)] = stripslashes($v);
}
}
}
unset($process);
}
?>
<html>
<head>
<title>Spektrix API Tester</title>
</head>
<body>
<h1>Spektrix API Tester</h1>
<form method="POST" action="">
<select name="Verb">
<option value="GET">GET</option>
<option value="POST">POST</option>
<option value="PATCH">PATCH</option>
<option value="DELETE">DELETE</option>
<select> :
<select name="Client">
<option value="{client_name}">{client_name}</option>
</select> /api/v2/
<select name="Method">
<option value="customers">customers</option>
<option value="customers/addresses">customers/addresses</option>
<option value="customers/authenticate">customers/authenticate</option>
<option value="customers/print-at-home-documents">customers/print-at-home-
documents</option>
<option value="customers/reset-password">customers/reset-password</option>
<option value="bands">bands</option>
<option value="basket">basket</option>
<option value="basket/items">basket/items</option>
<option value="basket/related-data">basket/related-data</option>
<option value="events" selected>events</option>
<option value="instances">instances</option>
<option value="instance-status">instance-status</option>
<option value="keep-alive">keep-alive</option>
<option value="offers">offers</option>
<option value="orders">orders</option>
<option value="orders/related-data">orders/related-data</option>


<option value="orders/send-confirmation">orders/send-confirmation</option>
<option value="plans">plans</option>
<option value="postcode-lookup">postcode-lookup</option>
<option value="postcode-lookup/address">postcode-lookup/address</option>
<option value="price-lists">price-lists</option>
<option value="statements">statements</option>
<option value="stock-items">stock-items</option>
<option value="tag-groups">tag-groups</option>
<option value="tags">tags</option>
<option value="ticket-types">ticket-types</option>
</select><br />
API Key: <input type="text" name="apikey" value="<?php print $_POST['apikey'] ?>"/><br
/>
Session cookie: <input type="text" name="session" /><br />
Request parameters: <input type="text" name="reqparams" /><br />
Request body: <textarea name="reqbody"></textarea><br />
<input type="submit" name="submit" value="Send" />
</form>
<?php

if(isset($_POST['submit']))
{
// Check we've got the parameters we require
if (!isset($_POST['Verb']))
die("No Verb specified");
if (!isset($_POST['Client']))
die("No Client specified");
if (!isset($_POST['Method']))
die("No Method specified");
if (!isset($_POST['apikey']))
die("No API key specified or wrong length");

// Check we haven't been given a body with a GET or DELETE
if (($_POST['Verb'] == "GET" || $_POST['Verb'] == "DELETE") &&
(isset($_POST['reqbody']) && strlen($_POST['reqbody']) > 0))
die("You must not specify a request body with a GET or DELETE operation");

// Check we have got a body for a POST or PATCH
if (($_POST['Verb'] == "POST" || $_POST['Verb'] == "PATCH") &&
(!isset($_POST['reqbody']) || strlen($_POST['reqbody']) == 0))
die("You must specify a request body with a POST or PATCH operation");

// Build the base URL we will be sending our request to
$url = $baseURL.$_POST['Client']."/api/v2/".$_POST['Method'];

// Build the reqest URL
$getParams = "?api_key=".$_POST['apikey'];
if (isset($_POST['reqparams']) && strlen($_POST['reqparams']) > 0)
$getParams .= "&".$_POST['reqparams'];
$url .= $getParams;

print "URL in use: ".$url."<br />";

// Send the request via CURL
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_SSLCERT, $sslCertFile);
curl_setopt($ch, CURLOPT_SSLKEY, $sslKeyFile);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_VERBOSE, $curlVerbose);
curl_setopt($ch, CURLOPT_STDERR, fopen('php://output', 'w'));

// CURLs handling of headers is less than idea
$headers = "";


function handleHeader($curlObj, $headerLine)
{
global $headers;
$headers .= $headerLine;
return strlen($headerLine);
}
curl_setopt($ch, CURLOPT_HEADERFUNCTION, 'handleHeader');

// Tell CURL if we're doing anything other than GET
if ($_POST['Verb'] == "POST")
curl_setopt($ch, CURLOPT_POST, true);
else if ($_POST['Verb'] != "GET")
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $_POST['Verb']);

$requestHeaders = array();
if (isset($_POST['session']) && strlen($_POST['session']) > 0)
$requestHeaders[] = "Cookie: SessionId=".$_POST['session'];

// Send the body if we're doing a POST or PATCH
if ($_POST['Verb'] == "POST" || $_POST['Verb'] == "PATCH")
{
$requestHeaders[] = "Content-Type: application/xml";
curl_setopt($ch, CURLOPT_POSTFIELDS, $_POST['reqbody']);
}

curl_setopt($ch, CURLOPT_HTTPHEADER, $requestHeaders);

// Perform the request
$result = curl_exec($ch);

// Check for response code 0 (this normally means that CURL couldn't find the SSL
client certificate)
$curlInfo = curl_getinfo($ch);
if ($curlInfo['http_code'] == 0)
print "<p><strong>CURL returned http_code 0 - have you correctly specified the
client certificate?</strong></p>";

// Display the results
print "<p>Response Headers:<br />";
print nl2br($headers);
print "</p>";

print "<p>Response Information:<br />";
print nl2br(print_r(curl_getinfo($ch), true));
print "</p>";

print "<p>Response Body:<br />";
// We display it in a textarea as it most likely contains XML
print "<textarea cols=\"100\" rows=\"10\"
readonly>".htmlentities($result)."</textarea>";
print "</p>";
}
?>
<p>&nbsp;</p>
</body>
</html>

Call Schemas

Dates in parameters such as &instance_start_from= should be formatted as YYY-MM-DD.

AddBasketItems


UriTemplate	http://system.spektrix.com/apitesting/api/v2/basket/items
Method	POST
Request Format	xml or json
Request Schema	http://system.spektrix.com/apitesting/api/v2/help/AddBasketItems/request/schema
Request Example	http://system.spektrix.com/apitesting/api/v2/help/AddBasketItems/request/example
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/AddBasketItems/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/AddBasketItems/response/example

AddCustomerAddresses


UriTemplate	http://system.spektrix.com/apitesting/api/v2/customers/addresses
Method	POST
Request Format	xml or json
Request Schema	http://system.spektrix.com/apitesting/api/v2/help/AddCustomerAddresses/request/schema
Request Example	http://system.spektrix.com/apitesting/api/v2/help/AddCustomerAddresses/request/example
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/AddCustomerAddresses/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/AddCustomerAddresses/response/example

AddCustomers


UriTemplate	http://system.spektrix.com/apitesting/api/v2/customers
Method	POST
Request Format	xml or json
Request Schema	http://system.spektrix.com/apitesting/api/v2/help/AddCustomers/request/schema
Request Example	http://system.spektrix.com/apitesting/api/v2/help/AddCustomers/request/example
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/AddCustomers/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/AddCustomers/response/example

AuthenticateCustomer


UriTemplate	http://system.spektrix.com/apitesting/api/v2/customers/authenticate
Method	POST
Request Format	xml or json
Request Schema	http://system.spektrix.com/apitesting/api/v2/help/AuthenticateCustomer/request/schema
Request Example	http://system.spektrix.com/apitesting/api/v2/help/AuthenticateCustomer/request/example
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/AuthenticateCustomer/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/AuthenticateCustomer/response/example

ConfirmOrder


UriTemplate	http://system.spektrix.com/apitesting/api/v2/basket/confirm-order
Method	POST
Request Format	xml or json
Request Schema	http://system.spektrix.com/apitesting/api/v2/help/ConfirmOrder/request/schema
Request Example	http://system.spektrix.com/apitesting/api/v2/help/ConfirmOrder/request/example
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/ConfirmOrder/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/ConfirmOrder/response/example

DeleteBasketItem


UriTemplate	http://system.spektrix.com/apitesting/api/v2/basket?item_id={itemId}
Method	DELETE
Request Format	xml or json
Request Schema	http://system.spektrix.com/apitesting/api/v2/help/DeleteBasketItem/request/schema
Request Example	http://system.spektrix.com/apitesting/api/v2/help/DeleteBasketItem/request/example
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/DeleteBasketItem/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/DeleteBasketItem/response/example

DeleteCustomerAddress


UriTemplate	http://system.spektrix.com/apitesting/api/v2/customers/addresses?customer_id={customerId}&address_id={addressId}
Method	DELETE
Request Format	xml or json
Request Schema	http://system.spektrix.com/apitesting/api/v2/help/DeleteCustomerAddress/request/schema
Request Example	http://system.spektrix.com/apitesting/api/v2/help/DeleteCustomerAddress/request/example
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/DeleteCustomerAddress/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/DeleteCustomerAddress/response/example

GetAddress


UriTemplate	http://system.spektrix.com/apitesting/api/v2/postcode-lookup/address?postcode_lookup_id={postcodeLookupId}
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/GetAddress/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/GetAddress/response/example

GetBands


UriTemplate	http://system.spektrix.com/apitesting/api/v2/bands?offset={offset}&limit={limit}&all={all}
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/GetBands/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/GetBands/response/example

GetBasket


UriTemplate	http://system.spektrix.com/apitesting/api/v2/basket
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/GetBasket/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/GetBasket/response/example

GetBasketRelatedData


UriTemplate	http://system.spektrix.com/apitesting/api/v2/basket/related-data
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/GetBasketRelatedData/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/GetBasketRelatedData/response/example

GetCustomerAddresses


UriTemplate	http://system.spektrix.com/apitesting/api/v2/customers/addresses?customer_id={customerId}
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/GetCustomerAddresses/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/GetCustomerAddresses/response/example

GetCustomers


UriTemplate	http://system.spektrix.com/apitesting/api/v2/customers?customer_id={customerId}&email={email}&friendly_id={friendlyId}
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/GetCustomers/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/GetCustomers/response/example

GetEvents


UriTemplate	http://system.spektrix.com/apitesting/api/v2/events?offset={offset}&limit={limit}&all={all}&event_id={eventId}&instance_id={instanceId}&instance_start_from={instanceStartFrom}&instance_start_to={instanceStartTo}
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/GetEvents/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/GetEvents/response/example

GetFixedSeries


UriTemplate	http://system.spektrix.com/apitesting/api/v2/fixed-series?fixed_series_id={fixedSeriesId}
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/GetFixedSeries/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/GetFixedSeries/response/example

GetInstanceStatus


UriTemplate	http://system.spektrix.com/apitesting/api/v2/instance-status?offset={offset}&limit={limit}&all={all}&event_id={eventId}&instance_id={instanceId}&instance_start_from={instanceStartFrom}&instance_start_to={instanceStartTo}
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/GetInstanceStatus/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/GetInstanceStatus/response/example

GetInstances


UriTemplate	http://system.spektrix.com/apitesting/api/v2/instances?offset={offset}&limit={limit}&all={all}&event_id={eventId}&instance_id={instanceId}&instance_start_from={instanceStartFrom}&instance_start_to={instanceStartTo}
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/GetInstances/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/GetInstances/response/example

GetMemberships


UriTemplate	http://system.spektrix.com/apitesting/api/v2/memberships?offset={offset}&limit={limit}&all={all}
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/GetMemberships/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/GetMemberships/response/example

GetOffers


UriTemplate	http://system.spektrix.com/apitesting/api/v2/offers?offset={offset}&limit={limit}&all={all}&instance_id={instanceId}
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/GetOffers/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/GetOffers/response/example

GetOffers2


UriTemplate	http://system.spektrix.com/apitesting/api/v2/offers2?offset={offset}&limit={limit}&all={all}&instance_id={instanceId}&event_id={eventId}&customer_id={customerId}
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/GetOffers2/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/GetOffers2/response/example

GetOrderRelatedData


UriTemplate	http://system.spektrix.com/apitesting/api/v2/orders/related-data?order_id={orderId}&customer_id={customerId}&friendly_id={friendlyId}
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/GetOrderRelatedData/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/GetOrderRelatedData/response/example

GetOrders


UriTemplate	http://system.spektrix.com/apitesting/api/v2/orders?order_id={orderId}&customer_id={customerId}&friendly_id={friendlyId}
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/GetOrders/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/GetOrders/response/example

GetTransactions


UriTemplate	http://system.spektrix.com/apitesting/api/v2/transactions?transaction_id={transactionId}&order_id={orderId}
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/GetTransactions/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/GetTransactions/response/example

GetPlans


UriTemplate	http://system.spektrix.com/apitesting/api/v2/plans?offset={offset}&limit={limit}&all={all}&event_id={eventId}&instance_id={instanceId}&instance_start_from={instanceStartFrom}&instance_start_to={instanceStartTo}
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/GetPlans/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/GetPlans/response/example

GetPriceLists


UriTemplate	http://system.spektrix.com/apitesting/api/v2/price-lists?offset={offset}&limit={limit}&all={all}&event_id={eventId}&instance_id={instanceId}&instance_start_from={instanceStartFrom}&instance_start_to={instanceStartTo}
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/GetPriceLists/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/GetPriceLists/response/example

GetPrintAtHomeDocuments


UriTemplate	http://system.spektrix.com/apitesting/api/v2/customers/print-at-home-documents?customer_id={customerId}
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/GetPrintAtHomeDocuments/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/GetPrintAtHomeDocuments/response/example

GetStatements


UriTemplate	http://system.spektrix.com/apitesting/api/v2/statements?offset={offset}&limit={limit}&all={all}
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/GetStatements/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/GetStatements/response/example

GetStockItems


UriTemplate	http://system.spektrix.com/apitesting/api/v2/stock-items?offset={offset}&limit={limit}&all={all}
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/GetStockItems/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/GetStockItems/response/example

GetTagGroups


UriTemplate	http://system.spektrix.com/apitesting/api/v2/tag-groups?offset={offset}&limit={limit}&all={all}
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/GetTagGroups/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/GetTagGroups/response/example

GetTags


UriTemplate	http://system.spektrix.com/apitesting/api/v2/tags?offset={offset}&limit={limit}&all={all}
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/GetTags/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/GetTags/response/example

GetTicketTypes


UriTemplate	http://system.spektrix.com/apitesting/api/v2/ticket-types?offset={offset}&limit={limit}&all={all}
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/GetTicketTypes/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/GetTicketTypes/response/example

KeepAlive


UriTemplate	http://system.spektrix.com/apitesting/api/v2/keep-alive
Method	POST
Request Format	xml or json
Request Schema	http://system.spektrix.com/apitesting/api/v2/help/KeepAlive/request/schema
Request Example	http://system.spektrix.com/apitesting/api/v2/help/KeepAlive/request/example
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/KeepAlive/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/KeepAlive/response/example

PostcodeLookup


UriTemplate	http://system.spektrix.com/apitesting/api/v2/postcode-lookup?postcode={postcode}
Method	GET
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/PostcodeLookup/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/PostcodeLookup/response/example

ResetCustomerPassword


UriTemplate	http://system.spektrix.com/apitesting/api/v2/customers/reset-password?customer_id={customerId}
Method	POST
Request Format	xml or json
Request Schema	http://system.spektrix.com/apitesting/api/v2/help/ResetCustomerPassword/request/schema
Request Example	http://system.spektrix.com/apitesting/api/v2/help/ResetCustomerPassword/request/example
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/ResetCustomerPassword/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/ResetCustomerPassword/response/example

SendConfirmationEmail


UriTemplate	http://system.spektrix.com/apitesting/api/v2/orders/send-confirmation?order_id={orderId}
Method	POST
Request Format	xml or json
Request Schema	http://system.spektrix.com/apitesting/api/v2/help/SendConfirmationEmail/request/schema
Request Example	http://system.spektrix.com/apitesting/api/v2/help/SendConfirmationEmail/request/example
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/SendConfirmationEmail/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/SendConfirmationEmail/response/example

UpdateBasket


UriTemplate	http://system.spektrix.com/apitesting/api/v2/basket
Method	PATCH
Request Format	xml or json
Request Schema	http://system.spektrix.com/apitesting/api/v2/help/UpdateBasket/request/schema
Request Example	http://system.spektrix.com/apitesting/api/v2/help/UpdateBasket/request/example
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/UpdateBasket/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/UpdateBasket/response/example

UpdateBasketItems


UriTemplate	http://system.spektrix.com/apitesting/api/v2/basket/items
Method	PATCH
Request Format	xml or json
Request Schema	http://system.spektrix.com/apitesting/api/v2/help/UpdateBasketItems/request/schema
Request Example	http://system.spektrix.com/apitesting/api/v2/help/UpdateBasketItems/request/example
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/UpdateBasketItems/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/UpdateBasketItems/response/example

UpdateCustomerAddresses


UriTemplate	http://system.spektrix.com/apitesting/api/v2/customers/addresses
Method	PATCH
Request Format	xml or json
Request Schema	http://system.spektrix.com/apitesting/api/v2/help/UpdateCustomerAddresses/request/schema
Request Example	http://system.spektrix.com/apitesting/api/v2/help/UpdateCustomerAddresses/request/example
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/UpdateCustomerAddresses/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/UpdateCustomerAddresses/response/example

UpdateCustomers


UriTemplate	http://system.spektrix.com/apitesting/api/v2/customers
Method	PATCH
Request Format	xml or json
Request Schema	http://system.spektrix.com/apitesting/api/v2/help/UpdateCustomers/request/schema
Request Example	http://system.spektrix.com/apitesting/api/v2/help/UpdateCustomers/request/example
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/UpdateCustomers/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/UpdateCustomers/response/example

Echo


UriTemplate	http://system.spektrix.com/apitesting/api/v2/echo?message={message}
Method	GET
Request Format	xml or json
Request Schema	http://system.spektrix.com/apitesting/api/v2/help/Echo/request/schema
Request Example	http://system.spektrix.com/apitesting/api/v2/help/Echo/request/example
Response Format	Xml
Response Schema	http://system.spektrix.com/apitesting/api/v2/help/Echo/response/schema
Response Example	http://system.spektrix.com/apitesting/api/v2/help/Echo/response/example

Note - Read before continuing​

API Overview​

Base Address​

Endpoints and Schema​

Attributes and Identifiers​

Verbs: PATCH and X-HTTP-Method-Override**​

Sessions & Basket (deprecated)​

Security​

API key​

Client Certificate​

Generating your CSR​

Using OpenSSL​

Using the Windows Certificate Snap-In​

Checking if your signed certificate has the private key associated​

Exporting Your Certificate with the Private Key on Windows​

General secure coding practices​

Data Objects​

Event and Instance Objects​

Customer Objects - to be deprecated​

Deprecated Objects​

Reference​

Getting Data​

Creating Objects​

Modifying Objects​

Deleting Objects​

Payment​

Other Actions​

Examples​

Test of getting data from the Spektrix Api (in PHP)​

To use this in C# code:​

A complete API test framework (in PHP)​

Call Schemas​

AddBasketItems​

AddCustomerAddresses​

AddCustomers​

AuthenticateCustomer​

ConfirmOrder​

DeleteBasketItem​

DeleteCustomerAddress​

GetAddress​

GetBands​

GetBasket​

GetBasketRelatedData​

GetCustomerAddresses​

GetCustomers​

GetEvents​

GetFixedSeries​

GetInstanceStatus​

GetInstances​

GetMemberships​

GetOffers​

GetOffers2​

GetOrderRelatedData​

GetOrders​

GetTransactions​

GetPlans​

GetPriceLists​

GetPrintAtHomeDocuments​

GetStatements​

GetStockItems​

GetTagGroups​

GetTags​

GetTicketTypes​

KeepAlive​

PostcodeLookup​

ResetCustomerPassword​

SendConfirmationEmail​

UpdateBasket​

UpdateBasketItems​

UpdateCustomerAddresses​

UpdateCustomers​

Echo​