Seat Status and Availability

The Spektrix API can retrieve availability status for event instances. For details on making queries for Events and Instances you can look through our guide to Filtering Events.

Availability is linked to instances and not whole events, so in order to determine the status of the event you will need to make individual calls to all instances first. Note that the resource isOnSale which is revealed from GET api/v3/events does not represent availability.

note

Making a large number of client-side API requests at once can negatively impact the performance of your website. Calls related to overall Event and Instance availability should generally be cached and made server-side to avoid browser slow-down and rate limiting.

Locks

This guide on status and availability refers to ‘locks’. Spektrix allows clients to ‘lock’ certain seats on a seating plan in order to provide additional information about a given seat or to hold them back from general sale online.

Potential use cases for locks include:

• Seats for a personal assistant for a customer who requires 1-1 support, with no customer eligibility criteria. The seats are available to anyone, but hold additional information.
• Exclusive seats held back, with a customer eligibility criteria specific to members, while the seats remain unavailable to the general public.
• ‘House seats’ which are held back and sold at the discretion of the Box Office Manager or released last minute (no longer locked) if not needed.

What this potentially results in is two separate sets of locked seats:

• Locked seats that are accessible for the general public that will not change customer-to-customer. Generally, cached server-side calls should be used to access this information.
• Locked seats that will change based on whether or not a customer has logged into their account. These locks are customer-specific and can be viewed by making client-side API calls using the custom domain instead of spektrix.system.com. In order to view the set of locked seats that are available to the specific customer requires successful authentication. Customers can log in via the loginlogout.aspx iframe or a client-side API call to v3/customer/authenticate, using the custom domain instead of system.spektrix.com in order to share the session.

Unreserved Instance Status / Reserved Instance Status Summary

These calls will retrieve the latest seat availability status for instances which can be used for unreserved instances or as a summary of reserved instances when you don't need the status information for each individual seat.

Information returned in the properties specialAvailable and lockInfoSpecialAvailable may differ depending on the logged in customer.

Summary Calls

• {id}/status
• {id}/status/areas/{areaId}

Request

GET

https://system.spektrix.com/{{clientname}}/api/v3/instances/{instanceid}/status?includeLockInformation=true&includeChildPlans=true

Response

{
	"name": "Unreserved Example",
	"available": 175,
	"wheelchairAvailable": 0, // indicates locked wheelchair seats where lock name is exactly ‘wheelchair’
	"specialAvailable": 0, // indicates locked seats available for logged in customer, appears with or without parameter includeLockInformation
	"capacity": 200,
	"inBasket": 0,
	"unavailable": 25,
	"lockInfoAvailable": [ // content appears only with parameter includeLockInformation=true. Indicates locked seats that are available without eligibility criteria
		{
			"quantity": 3,
			"lockType": {
			"name": "Personal Assistant",
			"id": "601APNNMRMBJQQPBSCNQGQHGKKCRPSSGN"
			}
		}
	],
	"lockInfoSpecialAvailable": [// content appears only with parameter includeLockInformation=true. Indicates locked seats available to logged in customer if they meet the eligibility criteria
		{
			"quantity": 2,
			"lockType": {
			"name": "Members Exclusive Seats",
			"id": "1401AHPQBSMRKMCGHQKGHVQVKCQNVNBKN"
			}
		}
	]

}

Parameter	Notes
includeLockInformation	Default value is false where lockInfoAvailable and lockInfoSpecialAvailable will return as null. When true, the response includes information on locked seats without eligibility criteria under lockInfoAvailable and information on locked seats with eligibility criteria under lockInfoSpecialAvailable. Both properties will return an empty array if no seats are available in the property.
includeChildPlans	Default value is false. For events built with multi-area seating plans, it will be necessary to append the query to see details for all areas of the plan. It is generally advisable to include this parameter.

Use cases:

• The information on availability can be used to build conditional booking links to instances that show 'limited availability' and 'sold out' messages, dynamic calendar listings, and other similar use cases. Generally, cached server-side calls should be used to access this information.
• The information on locked seats can be used:
  • by venues that use locks without eligibility criteria, so instances don’t appear sold out if 'locked' seats (available for purchase) are the only ones available. Generally, cached server-side calls should be used to access this information.
  • to display different messaging to logged in customers based on their individual eligibility criteria, for example to indicate additional availability to a logged in Member. In order to view this information in the API, these calls would need to be made client-side and only after the customer has logged in. For optimal performance, you can combine cached server-side calls to display availability for the general public, and client-side calls to display the specific availability for the logged in customer.

Detailed Reserved Seat Status

For reserved seating plans it is possible to get the status of each seat.

Detail Calls

• {id}/status/detail
• {id}/status/areas/{areaId}/detail

Since venues can contain many seats, reserved seating plan status data for instances could be very large. So, the Spektrix API defines its own, efficient format for availability data as follows:

Request

GET

https://system.spektrix.com/{{clientname}}/api/v3/instances/\{\{id}}/status/detail?includeLockInformation=true&includeChildPlans=true

Response

A:12345ABCDEF:33,34,35,36,37,38
A:12345ABCDEF::{56789ASDFGH:"Personal Assistant"}:32
A:31234ABCDEF:39,40,41,42,43,44,45
U:12345ABCDEFL:23,24,25,26,27,28,29,30
W:12345ABCDEFL:31
X:31234ABCDEF:{345678POIUYTR:"Members Exclusive Seats"}:46,47,48
I:Restricted+view:33;34

tip

The content format is in EBNF

Response Breakdown

The response will return data in the below structure, line by line;

seatstatus:pricebandid:seatid,seatid,seatid ...

When parameter includeLockInformation=true is included, the response will return data in the below structure, including information on locks;

seatstatus:pricebandid:{lockid:“name of lock”}:seatid,seatid,seatid ...

Similarly to the status calls above, seat availability will differ based upon the authenticated customer account (or lack thereof) if locks with customer eligibility have been assigned to any seats in the Instance’s seating plan.

Depending on the method of authentication, the response seatstatus characters will return as follows:

A = Available (Web, Owner, Agent)
B = In basket (Web, Owner, Agent)
U = Unavailable (Web, Owner, Agent)
W = Wheelchair locked, available for purchase (Web, Agent)
X = Locked, available for purchase (Web, Agent)
E = Unavailable (in another basket) (Owner)
SC = Scanned (Owner)
SO = Sold (Owner)
R = Reserved (Owner)
L = Locked (Owner)
M = Masked (Owner)
I = Seat information

Use cases: The detail on seat availability will be needed if you are building a reserved seat selector.

Custom reserved seat selector

Please note that Info overlay, locks, and seat masking (as applied to seats) are available in the API but their customer facing visibility must be considered and likely recreated depending on organization’s needs. If you are planning on building your own seat selector, please contact support first.