The current API is our third public version. 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 API v.3.
Full documentation for API v.3 can be found at the following page
The above help page provides information for all available endpoints, as well as high-level information about authentication, supported call methods, and querying resources and sub-resources.
An important point to note is that API v.3 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 and customer account management functionality that are yet to be exposed via the API.
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, including GET calls used to retrieve e.g. event, pricing and availability information, which 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.
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.
Authentication is only needed for API v.3 calls that give access to customer information. Most website itegrations only require event information so therefore will not need to authenticate.
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 the Data Protection Act. 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. We use industry standard SSL encryption to protect data in transit and access to sensitive data or functionality required authentication.
Signing and Authenticating Requests
API requests that require authentication must contain your API Login Name must be signed with your API Secret Key. These can be obtained from a Spektrix user who has Settings access to the system in question.
Please note that the API Secret Key is base-64 encoded, and must be decoded before use in the HMAC step of the Authentication process.
GET api/v3/customers/123 Host: system.spektrix.com Date: Mon, 26 Mar 2007 19:37:58 +0000 Authorization: SpektrixAPI3 TestLogin:frJIUN8DYpKDtOLCwo//yllqDzg=
Constructing the Authorization Header
Authorization = "SpektrixAPI3 " + LoginName + ":" + Signature; Signature = BASE-64-ENCODE( HMAC-SHA1( BASE-64-DECODE(SecretKey), UTF-8( StringToSign ) ) ); StringToSign = HTTP-Method + "\n" + HTTP-Uri + "\n" + HTTP-Date + [ "\n" , BodyStringToSign ]; BodyStringToSign = BASE-64( MD5( UTF-8( body ) ) )
- If the request has a body, construct BodyStringToSign as follows:
- UTF-8 encode the contents of the request body;
- MD5 sum the result;
- then base-64 encode the MD5 sum.
- Construct StringToSign by appending:
- the HTTP method (in upper case);
- a newline ("\n");
- the uri;
- a newline ("\n");
- the contents of the Date header;
- and, if there is a body, a newline then BodyStringToSign.
- Construct Signature as follows:
- UTF-8 encode StringToSign;
- base-64 decode the Secret Key;
- calculate the SHA1 HMAC of the utf-8 encoded string using the base64-decoded Secret Key;
- base-64 encode the SHA1 HMAC result.
- Finally, form the Authorization header value by appending
- a space;
- your API login name;
- a colon (" : ");
- and the Signature string calculated as above.