Skip to main content

Guide for Ticket Agents

Intro​

The Agency API allows Spektrix clients to give Agents live access to sell for events.

High level information on what to expect working with a Spektrix client:

  • The Client will set up a Customer record that acts as an Agent.
  • This provides access credentials for Agents. As an Agent you can 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 email address and mobile number will need to be sent to the Spektrix client so they can complete the setup.
  • The Agent mode allows the creation, management and confirmation of multiple concurrent baskets, and provides full end-to-end purchase. Note that it does not include payment processing.
  • Each transaction will be recorded as sales against the 'Agency API' payment method and logged against the specific Agent Customer’s account. The agent has the ability to write back the customer name, first line of address and reference number of the end customer, which are all recorded as additional information against each transaction.
  • The Agency API does not provide access to the rest of the Database, for example there is no access to Customer data.
  • As Agents buy tickets through a credit agreement, the client can use Spektrix reports in order to have an overview of sales and invoice Agents accordingly.

Further information on client set up here.

This guide aims to give a general overview of the approach that you are likely to take as an agent to sell tickets for one or more Spektrix clients.

For a full breakdown of all our Agent API endpoints, click here

We have created a glossary of terms to assist with the Spektrix system terminology below. However, please do contact us directly if you have any questions regarding the below or your specific integration plans.

If you would like to build your integration on a Spektrix testing environment, you can reach out to request your access to the Spektrix Sandbox (SDK) Environment.

Sample approach:​

An agent integration with Spektrix is likely to consist of four parts:

  1. Obtaining Agent API credentials from the client you wish to integrate with.
  2. Retrieving event data (including pricing, seating plan information), storing this in your own database and updating it on a regular basis, for example overnight or at a manual trigger.
  3. Adding tickets to the basket.
    • Depending on your agreement with the client, you may have agreed to sell any seat available, or from an allocation of seats that is locked off and available for you. If you have agreed to sell from an allocation, you can follow the relevant steps as outlined below to allow you to view availability of your allocation.
  4. Processing sales of tickets to end customers.

1. Obtaining Access​

Spektrix clients are able to give you access as an Agent on their system by setting you up as an Agent Customer. You need to provide the client with an email address and mobile phone number ir order to receive credentials via text and email consisting of a username and key. These can be used following the instructions here to construct your request header.

2. Retrieving Event Data​

tip

For more details on optional queries for Event and Instances call please look through our guide to Filtering Events

There are various approaches to retrieving event data using a combination of GET requests. A potential approach is to retrieve:

  • all Events
  • future Instances
  • pricing
  • plan information

The section below outlines the API calls required for this approach.

authentication

Though the below Event calls will return a response without authentication, using authentication will ensure that only the Events you have been authorised to sell for will display.

Retrieve all Events​

Retrieve all Events that have Instances on in the future using today's date

GET
https://system.spektrix.com/{{clientname}}/api/v3/events?instanceStart_from={{date in yyyy-mm-dd}}

Retrieve future Instances​

For each Event, retrieve all future Instances.

GET
https://system.spektrix.com/{{clientname}}/api/v3/events/{id}/instances?start_from={date in yyyy-mm-dd}
warning

When pulling Instances we advise only pulling the data required, and recommend running calls in small date batches using the available parameters starting from "today" unless historic instance data is required.

Retrieve Pricing​

For each Instance, retrieve the current ticket types and pricing.

GET
https://system.spektrix.com/{{clientname}}/api/v3/instances/{{instanceID}}/price-list

This request will show the details of all available Ticket Types and their prices, along with the Price Band details, for the Event Instance specified.

The “id” of the desired Ticket Type is the final piece of information required in order to POST tickets to the basket for an Event Instance created with an unreserved, single area seating plan.

Ticket Commission

It is possible that the client you are working with is using ticket commissions as part of their pricing structure.

To retrieve information on ticket commissions, you can use the special query parameter $expand and expose the sub-resource of customItems. These will only display if the system is set up in a way that itemises commissions to end-customers - more information here on how to display commissions as itemised. Note that changing this setting will not only affect this api endpoint but also iframes on the client website and confirmation emails sent by the client.

GET
https://system.spektrix.com/{{clientname}}/api/v3/instances/{{instanceID}}/price-list?$expand=prices/customItems

If the client prefers working with non-itemised ticket commission, then it is not possible to view the ticket commission in this API call, though the ticket price will be calculated correctly in the basket. In this case you can:

  • ask the client to set up the ticket commission as an 'event attribute', which will display in the response of api/v3/events. You can use this information to add the ticket commission to the price of the ticket.
  • manually display the information of the total ticket price when you show the price list to the end customer, using the api/v3/basket response as an indication of the total price.

Retrieve Plan Information​

Each Instance will return the id of the Plan it uses. The below will return full details about the plan including all child areas and seats.

GET
https://system.spektrix.com/{{clientname}}/api/v3/plans/{planid}
  • type indicates whether this is a reserved or unreserved Plan. This is important information as it determines your approach on how to add tickets to the basket - see next section.
  • For reserved plans, you can use the coordinates to create a visual and functioning seating plan. Please note that for new clients or new seating plans you may need to set aside some additional time in order to build the visuals for the seating plan.

3. Adding tickets to basket​

In order to add tickets to the basket, an approach would be:

  • create a new basket, with a unique ID
  • get instance status
  • add tickets to the basket
  • give the end customer the option to clear the basket

Getting the instance status and adding tickets to the basket requires different API calls depending on whether you are adding tickets for:

  • unreserved instances
  • reserved instances where the customer selects the specific seats
  • reserved instances where the customer gets the best available tickets

The section below outlines the API calls required for this approach.

authentication

The following Calls all require authentication.

Create a new Basket​

The response will include a "basketId". Store this for use when subsequently making changes to the basket.

POST
https://system.spektrix.com/{{clientname}}/api/v3/baskets

The error

{ "errorCode" : 12,
"message" : "Basket Requires Customer" }

likely indicates that:

  • You are not making an authenticated call, or
  • The client has not set you up correctly as Agent Customer

Unreserved Seating Plans​

Here are a set of API calls to build and confirm a simple basket from an unreserved event. The "seats" for an unreserved event are not allocated an id.

Get Instance Status​

Retrieve the latest seat availability status

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

Selling from an allocation​

If you have been given an allocation, the total number of locked seats available for you only will appear as specialAvailable.

Add Tickets to Basket (unreserved)​

Add tickets to the basket using the Basket Id in the call and the Instance Id, Seating Plan Id and Ticket Type Id in the Body.

POST
https://system.spektrix.com/{{clientname}}/api/v3/baskets/{{basketid}}/tickets

Selling from an allocation​

To ensure that you sell from the allocation first, rather than the general allocation, then the client needs to enable this for you in the Spektrix Admin Interface > Lock Types > Limits, ticking ‘In unreserved areas, sell eligible customers these seats before the general allocation’.

Once you sell the total of the specialAvailable tickets, technically POSTing further tickets to the Basket will allow you to sell from the general allocation. If you have an agreement to only sell up to the limit of specialAvailable, then you should set up a validation that limits you to selling up to the total allocation.

If you have been given multiple allocations, for example a number of tickets are sold as Day Tickets, and a number of tickets sold anytime, it is not possible to control which set of locked seats to sell from. In this case, you may want to be set up with different Agent Customer records for each allocation.

Reserved Seating Plans​

To purchase seats on a reserved plan, the steps are similar to the above.

Get Instance Seat Status​

Note that this call will provide seat status for all areas.

This call provides with up to date information to the availability of seats. Seats are shown by ID, in the Price Band given to them and by a specific status identifier.

For more information please see Detailed Reserved Seat Status.

These are;

  • A = Available
  • B = In basket
  • U = Unavailable
  • W = Wheelchair locked, available for purchase for Agent Customer
  • X = Locked, available for purchase for Agent Customer
  • I = Seat information
GET
https://system.spektrix.com/{{clientname}}/api/v3/instances/{{instanceid}}/status/detail?includeChildPlans=true

Selling from an allocation​

If you have been given an allocation, the response seatstatus character X will return the locked seats available for the authorised Agent to sell from.

If you are selling from multiple allocations, for example a set of seats for Day Tickets, and a set of seats to sell at any time, then it is possible to view the different allocations with the parameter includeLockInformation=true.

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

Add Tickets to Basket (reserved)​

Add tickets to the basket, specifying the desired seat ID.

POST
https://system.spektrix.com/{{clientname}}/api/v3/baskets/{{basketid}}/tickets

Best Available for Reserved Seating Plans​

To purchase seats on a reserved plan, you may also use a best available option.

The client you integrate with will be able to tell you if an instance can be sold via best available. Alternatively, you can find out by making a GET call to instances against the instance ID, as the response returns a boolean on hasBestAvailableOverlay. If this returns false then best available is disabled for that instance.

The client can set up the instance to have a best available overlay if needed. If the client would like to offer Best Available, they can follow our guidance on Creating a Best Available Overlay to help them get that in place.

note

Adding tickets via best available will adhere to the auto-distancing rules set against the instance by the client you are working with.

Get Instance Status Summary​

Retrieve the latest seat availability status summary

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

Add Tickets to Basket (reserved & best available)​

Provide the quantity of tickets required. You can also provide a list of the bands and/or areas that you want to select the seats from. See the help page for further info:

POST
https://system.spektrix.com/{{clientname}}/api/v3/baskets/{id}/tickets/best-available

If you attempt to POST tickets to basket using Best Available for an instance that is not set up to allow Best Available, you will encounter an error

{
	"problems": [
			"Best Available Seats not possible for this event instance"
	],
	"errorCode":1,
	"message":"Validation Failed"
}

Please contact the client so that they allow Best Available.

Clear Basket​

If needed, you can clear the basket contents at any time.

POST
https://system.spektrix.com/{{clientname}}/api/v3/baskets/{{basketid}}/clear

4. Set Delivery and Details and Confirm Basket​

Set Delivery and Details​

Set the delivery method for the order and add customer details.

There are two Delivery methods for agents to use:

  • COBO (Type 1)
  • Care of Agent (Type 3)

You can add First Name, Last Name, Customer Address and a Reference number which the client can search for inside of Spektrix.

PATCH
https://system.spektrix.com/{{clientname}}/api/v3/baskets/{{basketid}}

Confirm the basket​

POST
https://system.spektrix.com/{{clientname}}/api/v3/baskets/{{basketid}}/confirm
barcode

When confirming the order, the response will also include a barcode string. If the client you are integrating with uses Barcode Scanners, this can be printed onto a ticket and will be accepted by the Spektrix scanning interface.

Agent Priority Booking​

Our Priority Booking feature allows the client to specify a group of customers (including agents) who can book online for Events Instances before their Start Selling Date.

However, our API doesn’t have native functionality to query whether an instance is open for priority booking for any customer or the logged in customer, though tickets can still be booked via the API during Priority Booking.

Clients can give agents access to events before they go on sale by making their Customer Record eligible for priority booking.

Client Set-up​

  • Ensure all instances in question have a valid 'Web > Start Selling Date' set. This date does not need to be related to any agent onsale date, but cannot be left blank.
  • Set an 'Agent > Start Selling Date' corresponding to when the instances will go on general sale for ALL agents.
  • Create a priority booking period with however many days' early access you're granting to specific agencies. This needs to be set to be the number of days priority an agent has ahead of the agent general on sale date
  • All Customer Records that have 'Allowed access to agent API' can be eligible for Priority Booking. Make sure the relevant agent's customer record/s each have a specific tag or attribute value, and use this information as the 'Customer Eligibility' criteria in the priority booking period
    • N.B. Promotion codes currently won't work to provide Priority Booking access for Agents via the API; only something stored against their customer record can be used to provide eligibility.
  • Select the relevant event/instances in the 'Event criteria' section of the Priority Booking period.

That's everything needed at the client end. For more info about setting up Priority Booking periods, please see the following article: Priority Booking

For agents, they will now be able to process bookings for these instances ONLY if they match the 'Customer Eligibility' criteria set against the priority booking period.

Agent Set-up​

  • Agents will now be able to process bookings for event instances that clients grant priority booking access to, before their official 'startSellingAtAgents' date and time.
  • However, the instances will still show as 'isonsale=false' where the 'startSellingAtAgents' value is in the future, and the 'startSellingAtAgents' value does not take any eligible priority booking periods into account.
  • The agent may get errors such as "problems" : [ "Event instance is not on sale" ]. They can ignore the message and carry on.
  • This means that if their integration currently uses either the startSellingAtAgents date or isonsale=true to automatically decide which instances are pulled through to live listings of their websites, then agents would need to manually publish these instances to their sites.
  • The 'status' and 'status/detail' calls will be accurate and updated in real time.

Discounts and Offers​

In Spektrix, agency commission is your inside commission, which you are keeping and is not visible to the customer. Offers are the end customer discount that customers would get when they book tickets via your platform.

Agency Commission​

The commission is charged to the customers by the agent, it is retained by the agent and never reaches the client box office or counts towards the client’s revenue.

The client can set up your Agent Customer account with a single or different inside commissions (for example for matinees, different shows, one off instances and so on) as per your agreement.

Offers​

Spektrix allows clients to set up offers on the system, for example for a flash sale for end customers who book on your platform. The offer automatically applies based on the criteria the client chooses, including but not limited to Events, Instances, Customer. As an agent, whenever you work with an offer, the client must create the offer eligibility to include your unique Customer Agent record.

It is possible for you to run multiple offers at the same time for the same instances, for example you sell tickets as part of a flash sale, but for returning customers on your platform you are offering an extra x% off. There are two ways this can be handled:

  • the client may set you up with multiple Customer Agent records, each with their own offer for the selected instances.
  • you continue having only one Customer Agent Record, which is eligible for all discounts, and you handle the different discounts through promo codes.

It is important to note that offers can discount tickets at the basket, however they do not alter the Price List. The price list will always return the full value / face value of the tickets (before an offer is applied) and the basket will automatically calculate and display the discount and discount value of the tickets. This happens at this point so Spektrix can check if the offer is available based on the basket contents, limits of the offer, customer eligibility.

In order to display the discounted price list to the end customer, you may want to manually write the discounted prices of the tickets on your price list. Once the tickets are in the basket, the discount will be applied automatically, so the correct value of tickets will be displayed.

Last updated on by Theo