Search K
Appearance
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 endpoints can be found in the OpenAPI specification
Events
- Event: A venue-bound one-time event happening on a given start and end date. 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 a sports event can be held.
- Ticket: Entrance voucher for a single event.
- Reservation: Ticket allocation (optional).
- Booking: Ticket purchase.
Tournament
A Tournament is specified according to:
- Season: 24/25 or 2025
- SportType: Soccer, Motorsport, Tennis, Boxing
- Tournament Type: CUP or LEAGUE
- Name
- Region (country or global, e.g., F1)
Explanation
An event can be played as part of a competition or cup. In the case of a competition, the teams, venue, and date are known upfront. In the 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 minimum 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 vs Arsenal in the Premier League on date xyz. (Soccer, League)
- TT Assen 2025 in the MotoGP on date xyz (Motorsport, League)
- FA Cup Final at Wembley on date xyz (Soccer, Cup)
API Access
Please send your XS2Event account manager an email, and you will get an API key shortly.
Backend endpoints
Authentication
Currently, we only support API key authentication for our API customers. This API key should be provided as a header parameter.
Rate-limiting
Rates are limited; however, the margins are generous. This is to avoid misconfigured clients and to ensure the service is available 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 API key | The API access key |
| Accept | application/json |
Error Response codes
We are in the process of moving towards 400 (Bad Request) as the primary response code if something is wrong with your request.
Until then, 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 string contains unknown fields or contains invalid or missing data | sport_type is an enum and you sent an unknown value |
| Query String | 422 | Unprocessable Entity | Your query string contains fields which are not 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 exist | |
| Request | 409 | Conflict | The request conflicts with the 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 sent to us (for example, not a valid date) or invalid query parameters, we return a 422 or 400 response. If available, a message is included in the body with an 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 does not have access to an endpoint due to their 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 an invalid parameter is supplied, a 422 response code is returned.
List of supported resources for filtering/sorting:
ticketseventstournamentsteams
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 than or equal | |
| ge | Greater than or equal | |
| eq | Equal | |
| is_null | Is null | |
| is_not_null | Is not empty value (if applicable) | |
| like | Case sensitive like (if applicable) | |
| ilike | Case insensitive 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 100 euro.
Sorting
The output can be sorted by using the query parameter 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 from being left over, the maximum - 1 quantity cannot be ordered |
Datetime formats
Events, Tickets and Tournaments
The rule of thumb is that all event dates, ticket 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, and deleted.
Keep alive
We have a specific endpoint to check our system health, rate-limited at 1 request per second. Please use this endpoint 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:
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).