Introduction

Welcome! This is the REST API specification for the XS2Event API. This API is documented in the OpenAPI format.

Model

Our model consists of the following layered entities. These entities are available as http resources. A detailed description of all entities and endpoins can be found in the OpenAPI specification

Events

• Event: A venue bounded one-time event happening given a start- and enddate. Optionally involving two teams
• Tournament: A time-ordered sequence of events for a given sport type, season and tournament type
• Venue: A fixed location (by GPS) in which an sport event can be held
• Ticket: Entrance voucher for a single event
• Reservation: Ticket allocation (optional)
• Booking: Ticket purchase

Tournament

Tournament is specified according to a

• Season: 22/23 or 2023
• SportType: Soccer, Motorsport, Tennis, Boxing
• Tournament Type: CUP or LEAGUE
• Name
• Region (country or just global (f1 for example))

Explanation

An event can be played as part of a competition or cup. In case of a competition, the teams, venue and date are known upfront. In case of a cup only the dates are known and in some situations the location of the final or semi finals.

In our system, the minimal required data to offer an event is:

• date
• location (venue)
• tournament

Please note that the date may change and is usually fixed 14 days prior to the start of the event.

Examples:

• Manchester United - Arsenal in the Premier League at date xyz. (Soccer, League)
• TT Assen 2025 in the MotoGP at date xyz (MotorSport, League)
• FA cup final at Wembley at date xyz (Soccer, Cup)

API Access

Please send your XS2Event account manager an email and you will get an API key shortly.

Backend endpoints

• Test/Staging
• Production

Authentication

We support currently for our API customers only API key authentication. This api key should be provided as a header parameter.

Rate-limiting

Rates are limited however with great margins. This to avoid misconfigured clients and to make sure the service is able for every client. The rates are based on IP. If for some reason a client violates the rate limit we return a 503 http response code (service unavailable)

Required Request Headers

Header	Default	Description
X-Api-Key	Your password	The API access key
Accept	application/json

Error Response codes

We are in the process of moving towards 400 (Bad Request) as primary response code if something is wrong with your request.

Until that you can consider 400 and 422 as being the same; something in the payload is invalid or missing.

Context	Response code	Response code name	Explanation	Example
Query String	400	Bad Request	Your query strings contains unknown fields or contains invalid or missing data	sport_type is a enum and you sent a unknown value
Query String	422	Unprocessable Entity	Your query strings contains fields which aren ot allowed	foo=bar is sent but not accepted
Payload	400	Bad Request	Your payload contains invalid or missing data	ticket_id is required but not sent
Payload	422	Unprocessable Entity	Your payload contains invalid or missing data	ticket_id is required but not sent
Request	401	Unauthorized	The API key is invalid or does not have the required permissions
Request	403	Forbidden	The API key is valid but does not have the required permissions
Request	404	Resource not found	The URL points to a resource that does not exists
Request	409	Conflict	The request conflicts with state on our server	Double create booking from a reservation
Request	503	Server Exception	An error occurred in our system	You ran into a bug

Input validation

The API input is validated against the allowed query- and uri parameters.

In case invalid data is send to us (for example not a valid date) or invalid query parameters we return a 422 or 400 response. If available, a message is put in the body with explanation

If the resource is not available we return a standard 404 message

If the user has a wrong API key we return a 401

If the user has not access to an endpoint due to his role we return a 403

Resources filtering and sorting

The following resources can be filtered according to the specified list of available query parameters. If invalid parameter is supplied a 422 response code a returned.

List of support resources for filtering/sorting

• tickets
• events
• tournaments
• teams

Default comparison is equal (=).

Additional resource filtering

Supported operators. Syntax is: query_parameter=operator:value

Comparison Operators	Description	Example
lt	Less than
gt	Greater than
le	Less then equal
ge	Great than equal
eq	equal
is_null	is null
is_not_null	is not empty value (if applicable)
like	case sensitive like (if applicable)
ilike	case insentive ilike
in	values in set of 1,2,3	/v1/teams?sport_type=in:[soccer, rugby]
not_in	values not in	/v1/teams?sport_type=not_in:[soccer, rugby]

If no comparison operator is supplied, the equal comparison is applied

Examples

• /tickets?sales_price=gt:5000 : Filter the ticket resources on sales price > 50 euro (or local currency)
• /tickets?stock=lt:5 : Tickets with less than 5 items in stock
• /tickets?stock=lt:5&sales_price=gt:10000 : Tickets with less than 5 items in stock and over the 100 euro.

Sorting

The output can be sorted by using the query param sorting

Syntax is: sorting=query_parameter:direction

Direction can be asc (ascending) or desc (descending)

You can sort on multiple fields by using a , between the sorting statements

Examples

• /tickets?sorting=sales_price:desc,stock:asc: First, the tickets will be sorted from expensive to cheap and then on availability

Resource flags

Some resources, such as tickets, have extra flags to signify rules that are active for that ticket. For commercial reasons, we (or our suppliers) do not want to be left with 1 single ticket since these are hard to sell.

Flag	Description
pairs_only	Only pairs of tickets can be ordered (2-4-6-etc)
no_max_minus_1	To prevent a single ticket to be left over, the maximum - 1 quantity cannot be ordered

Datetime formats

Events, Tickets and Tournaments

The rule of thumb is that all event dates, tickets dates and tournament dates are local date time. If you want to derive the offset you can fetch /venues and based on the country code of the venue and the target country code you can calculate (your) localized time.

Resources

All fields related to the state of a resource are UTC. Such as created, updated, last_modified , deleted

Keep alive

We have a specific end-point which to check our system health. Rate limited at 1 request per second. Please use this end-point if you want to monitor the availability of our systems to avoid rate limits

Status page

Special page to show uptime/status of all our services

Link to status page

Currency / Currency formatting

The default currency is Euro (EUR). The /tickets endpoint encapsulates the currency in the response body. All prices are formatted as an integer (cents)