This article gives a brief explanation of key concepts relating to the Spektrix API and touches on some of what you can achieve with an API integration. We’ll also link out to guides on our Integration Portal which you can supply to your web developer.
Before getting started, make sure you’ve already read:
If you just need to supply your web developer with information about the API, you can head straight to the Integration Portal.
REMINDER: If you’re looking to set up an API connection for working with Agents or for a partner product take a look at the Introduction to Selling Tickets through Agents or How to set up an API User, respectively.
How to set up an API Integration
To integrate your website with Spektrix using the API, you’ll need the support of a web developer.
All of the documentation your web developer will need to be able to create an API integration with Spektrix can be found on our Integration Portal.
When setting up an API integration, you can choose to present the information from your Spektrix system on your website in almost any way that you can imagine. However, before creating something using the API, it’s worth considering if similar functionality can be achieved by using or editing existing tools such as Web Components.
The information in this article is intended to support you to have informed conversations with your web developer about what is possible to achieve with an API integration. This knowledge can also help with troubleshooting and setting up elements of your website integration which you may be required to be involved with.
The examples we’ve included in this article are just a snapshot of what you can achieve with an API integration. We’re always happy to discuss ideas or provide examples. You can also ask your web developer to get in touch with us directly.
API Requests
You can think of an API request (sometimes referred to as an API call) like a conversation or exchange of information.
Your web developer will use an API request to exchange information between your Spektrix system and your website.
Requests are written in a certain way similar to a web address.
Here’s an example of a Spektrix API request:
- The first part is the URL of your Custom Domain.
- Next, is your Spektrix Client Name.
- Third is the reference to our API.
- And the final part is the specific end point being made in the request.
If you have read over the What is the API? article, you might remember that our list of end points is the ‘menu’ in our restaurant analogy. In other words, it’s a list of what information is available to request from the Spektrix system.
Your web developer can access the full list of Spektrix endpoints on our Spektrix API Help Page.
Making an API call
You can make a test API call by taking the URL below, replacing the word clientname with your client name and entering this into your browser.
system.spektrix.com/clientname/api/v3/events
This method of API call is called a GET.
GET calls are the simplest to understand as they literally ‘get’ the data that is requested and retrieve it.
What you’ll see returned is the raw data response from your Spektrix system.
When the information is returned by the API, it’s up to your web developer to take that data and choose how to present it back to the customer on your website.
Web/Public mode
When setting up your website integration, your web developer will use the Web/Public mode of our API.
- The information you can get from the Web/Public API mode is the same level of information you can get on iframes. For example, Event listings, pricing, Merchandise, account and cart/basket information.
- Because the information you can find in Web/Public mode is publicly available, it doesn’t require any authentication. This means anyone with access to our endpoints, can make API calls (like we just did with the GET call earlier).
- You can retrieve lots of information using the API, but the information you can send back into the system is limited to Customer and Basket/Cart information. Actions such as setting up Events, creating new Memberships and running reports are not possible through the API.
- It’s also possible to share sessions between the API and the iframe purchase path. This means your web developer can build bespoke booking paths that incorporate both elements.
-
Sharing sessions means that the Customer interaction with the website is tracked and information is carried across when moving from interacting with the API to interacting with the iframe.
For example, when a customer adds a ticket to a Basket/Cart from the chooseseats.aspx iframe, views the content of their Basket/Cart in an API custom basket and then moves to the checkout iframe, the information about what is in the Basket/Cart is shared.
- It is not currently possible to process payments through the API. This means that an API website integration will always need to incorporate the checkout iframe.
There’s more documentation for web developers on the different modes which can be found on our Integrate Portal. Next, we’ll go over some common use cases for an API integration.
System Owner mode
In some cases your web developer will need more access than what is available in the Web/Public mode. An example would be accessing Customer Records in order to update Contact Preferences via the API.
For these cases, they will need access to the System Owner mode. To do so, you will need to set them up as an API user. If they don’t need this additional access, you do not need to set them up as an API user.
If you’re unsure whether you need to set them up as an API user, get in touch with the Support Team.
Filtering Events using the API
The API can be configured to filter Events in a similar way to how you can use Attributes to filter iframes.
However, unlike when filtering iframes, you can allow Customers to interact with and apply a range of filters on your Events page.
For example, if you want to filter by a custom Attribute, such as genre or Events which you have grouped as part of a festival, you’ll need to set up these Attributes and apply them to the Events/Instances.
In this example, you can see that the user could filter based on a dropdown, by checking specific Attribute boxes or by date range all on the same page.
Specific guidance for your web developer can be found on our Integration Portal: Filtering Events from the API.
Adding Event information using Attributes
As well as filtering Events, it’s also possible to use Attributes to add extra information to Instances and display this via the API.
You can use this approach to automatically update Instance availability or list out Attributes which add more information about specific Instances. For example, you might use this to indicate different types of Instances such as access performances or twilight gallery viewings.
Specific guidance for your web developer can be found on our Integration Portal: Instances.
Custom Basket/Cart
Creating a Custom Basket/Cart page using an API integration gives you full control over what is displayed on your Basket/Cart page.
One example of why you might create a custom Basket/Cart page is to upsell items (such as Memberships or Merchandise) based on the contents of the customers Basket/Cart.
You can also dynamically add information based on the Customer’s eligibility or value of their Basket/Cart.
For example, you can set a range which adjusts dynamically based on the value in the Basket/Cart. For smaller values in the Basket/Cart, you can make a small Donation ask, but for Basket/Carts over a certain value you can offer a Membership upsell instead.
In the example below, you can see that the value of potential savings by becoming a Member has been calculated from the value of the Basket/Cart and that there’s also the opportunity to add Merchandise which is related to the Event or Instance. Because there are two tickets in the Basket/Cart, two items of Merchandise have been suggested.
It’s also possible to group multiple items and display them as one bundle. For example, you might want to offer a bundle of Merchandise items which will let the customer add multiple items to the Basket/Cart in one click. The Basket/Cart can then display them as a single item, even if it consists of two different items.
-
You can group Merchandise items you want to display as a bundle using a Merchandise Attribute. This means you can group the items using the same Merchandise ID, and in a custom Basket page you could display these as a single bundle. Customers can then edit the whole bundle in the Basket/Cart, but the items will still display individually in confirmation emails.
WARNING: Choosing to create a custom Basket/Cart page might not be for you if you are selling Ticket Subscriptions as it’s not currently possible to sell them online using a custom Basket/Cart.
If you use Fixed Series Subscriptions, Ticket Donations, Gift Memberships or Facilitated Booking, the custom Basket/Cart won’t be able to show information about the relationship between these items. Contact support if you’d like to discuss this further.
Custom Basket/Cart configuration
There are two steps which you may be required to assist with if you are working on creating a custom Basket/Cart page.
- Before your web developer can create a Custom Basket/Cart page, you’ll need to have a Custom Domain. You may already have this set up, if that’s the case you won’t need to create another for the purposes of creating a custom Basket/Cart page.
- Once your page has been completed, you’ll need to add the URL to the Domain Specific Config section of your website.
To do this, follow the steps below:
- Go to the Website Admin Interface > Domain Specific Config > Custom Basket Link and click Edit.
TIP: You’ll need the Web Integration Administrator to access the Website Admin Interface.
- Enter the URL of your custom Basket/Cart page into the text box and click Save.
Specific guidance for your web developer can be found on our Integration Portal: Custom Baskets.
API sign up form
You can capture contact data with a simple HTML sign up form that automatically links to Dotdigital.
This can be used to capture fields including: First Name, Last Name and Email.
If you would like to capture additional information such as Attributes, Tags or Contact Preferences not linked to Dotdigital, your web developer can implement an API sign up form.
- Tags which you intend to use in an API sign up form must be marked as Available on Web
- Attributes which you intend to use in an API sign up form must be marked as Visible in the API
An API sign up form is one of the few occasions that your web developer needs access to the System Owner mode of the API, as they will need to update existing Customer Records.
All of the documentation to supply to your web developer can be found on our Integration Portal: API Sign up forms.
Further Reading
You can continue learning about web integrations in the Integrate your Website with Spektrix section of the Support Centre
To learn more about the other integration tools available, take a look at: