Skip to main content

PadelOS Public Listing APIs

How to pull your club's public trainings, open match and tournament schedules using your Club ID, and use them on your own website.

Written by Haris K

Updated: The Trainings and Tournament listings now support a showParticipants filter, which adds the players already registered as a deliberately minimal participantList. The Open Match listing now supports a showPrivateMatches filter. See the filters table in each section below.


How to Use This Data

PadelOS offers a set of public APIs: web addresses that return your club's live data (trainings, open matches, tournaments and more) instead of a web page. Each one works the same basic way:

  • The address returns data in a format called JSON. It's a structured format, not ready-made HTML, so it isn't meant to be viewed directly. It's meant to be read by code.

  • Whoever builds or manages your website (a developer) fetches that address, reads the fields out of the response, and uses them to generate the HTML your visitors actually see, such as a training name, a price or a time slot.

  • In practice, that means four steps on the developer's side:

    1. Fetch the data: call the address and get the response back.

    2. Parse it: convert the raw response into a usable object so individual fields can be read out of it.

    3. Loop through the list: the data comes back as a list of items (trainings, matches, tournaments and so on), and the code goes through it one item at a time.

    4. Build the HTML: for each item, pull out the fields you want to show and insert them into the page.

This same pattern applies to every PadelOS public API. Only the address and the specific fields returned change. Below is how it works for each listing API.


Trainings Listing API

This endpoint returns the trainings and clinics currently open to the public at your club. No player login is required. It's meant for clubs that want to display their training schedule on their own website, or pull it into another system.

The Basic Request

Every request starts from the same address, with your Club ID added on:

Replace YOUR_CLUB_ID with your club's ID, provided by PadelOS.

Example, for a club called PadelART:

Asking for More Than One Club

If you manage multiple locations and want one combined list, separate the Club IDs with a comma:

(216933 here is a placeholder for a second location. Swap in your actual second Club ID.)

Narrowing the Results

You can add extra filters to the address to only show certain trainings. Add each one after an &.

Filter

What it does

sport

Only show one sport, e.g. sport=padel. Leave it out to show all sports.

day

Only show trainings on a specific weekday, e.g. day=Monday.

startTime / endTime

Only show trainings starting or ending within a time window, e.g. startTime=09:00.

searchTerm

Only show trainings whose name matches text you enter.

trainerId

Only show trainings run by one specific trainer.

availability

available shows only trainings with open spots, slots_full shows only full ones. Leave it out to show both.

hideFilters

Hide certain trainings from the list entirely. sold_out hides full ones, registration_closed hides ones that aren't open for sign-up yet.

showParticipants

Set to true to include the players already registered for each training, returned as participantList (see What You Get Back below). By default this is left out, which omits participantList entirely.

Example, only padel trainings with open spots at PadelART:

If you enter a value a filter doesn't recognise, that one filter is simply ignored. The rest of the request still works.

Splitting Results Into Pages

If your club runs a lot of trainings, you can ask for the list in smaller chunks instead of all at once:

  • limit: how many trainings per page, e.g. limit=10.

  • page: which page to fetch, e.g. page=2.

Leave both out and every matching training comes back in one response.

What You Get Back

The response is a list of trainings, each including:

  • Name, dates, and how often it repeats

  • The trainer(s) running it

  • Price

  • How many spots are filled and how many are available

  • Whether registration is currently open, and if not, when it opens

  • Any rating or gender restriction on who can join

  • A minimal list of the registered players, only when showParticipants=true was passed

Sample response, showing what one training in the list looks like:

  • id: 458213

  • name: Saturday Morning Padel Clinic

  • clubId: 216932

  • clubName: PadelART

  • startDate: 2026-09-19

  • endDate: 2026-10-24

  • recurrType: weekly

  • registrationType: individual

  • type: session_purchase

  • trainers: a list of trainer objects, each with id, firstName, lastName and imageUrl (here, Omar Haddad)

  • participantPrice: 35.00 (originalPrice: 35.00, discountApplied: false, discountPercentage: null)

  • maxParticipants: 6

  • participantCount: 4

  • isRegistrationOpen: true (registrationClosedReason: null)

  • minRating / maxRating: 2.5 / 4.0

  • gender: null (no restriction)

  • categoryList: Beginner Friendly

  • participantList: only present when showParticipants=true was passed. In this example it has two entries: Sara L. (female), and a second entry with every field blank.

On participantList: this list is deliberately minimal. It contains only firstName, lastName, gender and imageUrl for each player. There is no id, no rating, email or phone data, and no field that distinguishes a registered participant from a guest someone else added. It's meant for a basic "who's playing" display, not for profile data.

It only comes back populated when the club has explicitly enabled showing players for that specific training. Otherwise it's an empty array, even with showParticipants=true. A player who hasn't made their profile public, or a guest with no linked account, shows up with every field blank (as in the second entry above) rather than being omitted.

On field types: in all the listing APIs on this page, IDs (such as id, clubId and the trainer id) come back as strings, not numbers. Rating and price fields (minRating, maxRating, participantPrice, originalPrice) are also strings. maxParticipants and participantCount are plain integers.


Open Match Listing API

This endpoint returns the open matches currently available to join at your club. No player login is required. It's meant for clubs that want to display their open match schedule on their own website, or pull it into another system.

The Basic Request

Every request starts from the same address, with your Club ID added on:

Replace YOUR_CLUB_ID with your club's ID, provided by PadelOS. By default this returns matches starting from today that still have open spots.

Example, for a club called PadelART:

Asking for More Than One Club

If you manage multiple locations and want one combined list, separate the Club IDs with a comma:

(216933 here is a placeholder for a second location. Swap in your actual second Club ID.)

Narrowing the Results

You can add extra filters to the address to only show certain matches. Add each one after an &.

Filter

What it does

date

Only show matches from a specific date onwards, e.g. date=2026-09-20. Defaults to today.

sport

Only show one sport, e.g. sport=padel. Leave it out (or pass all) to show all sports.

gender

Only show matches of a given type, e.g. gender=mixed. Options are all, male, female and mixed.

courtSize

Only show matches on single or double courts.

courtType

Only show matches on a specific court type, as set up by your club.

courtFeature

Only show matches on a specific court surface, e.g. courtFeature=Clay.

visibility

Only show matches of a given visibility: public, private or super_league.

startTime / endTime

Only show matches starting or ending within a time window, e.g. startTime=09:00.

day

Only show matches on a specific weekday, e.g. day=Monday.

rating

Only show matches whose rating range includes a given value.

availability

available (default) shows only matches with open spots, slots_full shows only full ones, all shows both.

showPrivateMatches

Set to true to also include invite-only (private) and super_league matches in the listing, alongside the normal public ones. See Private and Super League Matches below for exactly what's returned for these. By default these are left out.

Example, only mixed padel matches with open spots at PadelART:

If you enter a value a filter doesn't recognise, that one filter is simply ignored. The rest of the request still works.

Private and Super League Matches

By default, this endpoint only returns public matches to anonymous (not logged in) requests. A logged-in player who has already joined a private or super_league match, or who has been invited to one, continues to see that specific match with full detail. This hasn't changed.

Passing showPrivateMatches=true additionally surfaces every private and super_league match at the club in the listing, even ones the current viewer has no access to. These come back as a teaser row, not a usable match:

  • id and shortUuid are returned as null

  • redirectUrl is returned as null

  • participants is returned as an empty list

This lets a club show that private matches are happening on their site (for example a count, a date or a time slot) without exposing who's in them or letting a visitor navigate to or join a match they weren't invited to.

If the viewer actually has access to a given private or super_league match (they're already a participant, or on its invite list), that specific match is still returned with full, normal detail. The teaser treatment only applies to matches the viewer has no access to.

Example: a club with 3 upcoming private matches, and a logged-out visitor who passes showPrivateMatches=true, gets back 3 rows for those matches. Each has id: null, shortUuid: null, redirectUrl: null and participants: an empty list. Date, time, sport, court and price are still included as normal.

Splitting Results Into Pages

Matches are grouped by date. A request returns matches for the date you asked for, plus the next few upcoming dates that have any matches at all.

  • limit: how many matches per page, e.g. limit=10.

  • page: which page to fetch, starting from 0.

If there are matches further out than the current window, the response tells you so. Repeat the request with a later date to keep paging forward.

What You Get Back

The response is a list of open matches, each including:

  • Date, time and duration

  • Sport, and whether it's a friendly or competitive match

  • Current status (for example open, paid or cancelled)

  • Gender and court-size restrictions

  • Rating band required to join, if any

  • Price per player, and whether a discount applies

  • Which court it's on

  • The players already in the match, and their team and slot (empty for a private or super_league teaser row, see above)

Sample response, showing what one open match in the list looks like:

  • id: 90123

  • shortUuid: ab12cd34

  • date: 2026-09-20

  • startTime / endTime: 18:00 / 19:30

  • sport: padel

  • type: friendly

  • status: open

  • gender: mixed

  • courtSize: double

  • minRating / maxRating: 2.0 / 3.5

  • pricePerSlot: 12.00 (originalPrice: 12.00, discountApplied: false)

  • isBooked: true

  • visibilityType: public

  • court: id 55, name Court 3, courtFeature Clay

  • participants: a list of players, each with team, slotNo and the player's first name and last initial (for example team 1, slot 1: Ahmed K.)

Sample of a private match returned because showPrivateMatches=true, where the viewer has no access to it:

  • id: null

  • shortUuid: null

  • date: 2026-09-21

  • startTime / endTime: 19:00 / 20:30

  • sport: padel

  • visibilityType: private

  • redirectUrl: null

  • participants: an empty list

Participant emails are never included in this response. As with the other listing APIs, IDs (including the court id) and rating fields come back as strings, not numbers.


Tournament Listing API

This endpoint returns the tournaments currently open to the public at your club. No player login is required. It's meant for clubs that want to display their tournament schedule on their own website, or pull it into another system.

The Basic Request

Every request starts from the same address, with your Club ID added on:

Replace YOUR_CLUB_ID with your club's ID, provided by PadelOS.

Example, for a club called PadelART:

Asking for More Than One Club

If you manage multiple locations and want one combined list, separate the Club IDs with a comma:

(216933 here is a placeholder for a second location. Swap in your actual second Club ID.)

Narrowing the Results

You can add extra filters to the address to only show certain tournaments. Add each one after an &.

Filter

What it does

sport

Only show one sport, e.g. sport=padel. Leave it out to show all sports.

format

Only show tournaments of a specific format, e.g. format=doubles.

matchType

Only show friendly or competitive tournaments, e.g. matchType=competitive.

category / categoryIds / categoryNames

Only show tournaments linked to a specific category. Use category for the category name, or categoryIds / categoryNames to match one or more categories at once (comma-separated).

day

Only show tournaments starting on a specific weekday, e.g. day=Saturday.

startTime / endTime

Only show tournaments starting or ending within a time window, e.g. startTime=09:00.

fromDate

Only show tournaments from a specific date onward, e.g. fromDate=2026-11-01.

searchTerm

Only show tournaments whose name matches text you enter.

rating

Only show tournaments open to players around a specific skill rating.

availability

available shows only tournaments with open spots, slots_full shows only full ones, all shows both. Leave it out and only tournaments with open spots are shown.

hideFilters

Hide certain tournaments from the list entirely. sold_out hides full tournaments, registration_closed hides ones that aren't open for sign-up yet.

showParticipants

Set to true to include the players already registered for each tournament, returned as participantList (see What You Get Back below). By default this is left out, which omits participantList entirely.

Example, only padel tournaments with open spots at PadelART:

If you enter a value a filter doesn't recognise, that one filter is simply ignored. The rest of the request still works.

Splitting Results Into Pages

If your club runs a lot of tournaments, you can ask for the list in smaller chunks instead of all at once:

  • limit: how many tournaments per page, e.g. limit=10. Capped at 50 per page.

  • page: which page to fetch, e.g. page=2.

Leave both out and you still get a single page of up to 50 tournaments. Use page to move to the next batch if your club has more than that upcoming.

What You Get Back

The response is a list of tournaments, each including:

  • Name, dates, start and end time, sport and format

  • Whether it's a friendly or competitive tournament

  • The organiser(s) running it

  • Price, including the original price and any discount applied

  • The categories offered, and how many spots remain across them

  • Whether registration is currently open, and if not, when it opens

  • Any rating restriction on who can join

  • A minimal list of the registered players, only when showParticipants=true was passed

Sample response, showing what one tournament in the list looks like:

  • id: 893321

  • name: City Padel Open

  • clubId: 216932

  • clubName: PadelART

  • startDate / endDate: 2026-11-07 / 2026-11-08

  • startTime / endTime: 09:00 / 18:00

  • format: Doubles

  • matchType: Competitive

  • sport: Padel

  • price: 45.00 (originalPrice: 50.00, discountApplied: true, discountPercentage: 10%)

  • remainingSlots: 6

  • categoryNames: Men's Open, Women's Open

  • minRating / maxRating: 2.0 / 4.5

  • isRegistrationOpen: true (registrationClosedReason: null)

  • tournamentOrganisers: a list of organiser objects, not plain name strings. Each has id, firstName, lastName and imageUrl (here, Omar Haddad).

  • participantList: only present when showParticipants=true was passed. Here it has one entry: Sara L. (female).

On participantList: just like the Trainings API above, this is a deliberately minimal list. It contains only firstName, lastName, gender and imageUrl per player, with no id and no rating, email or phone data. It only comes back populated when the club has enabled showing players for that specific tournament. Otherwise it's an empty array, even with showParticipants=true. A player who hasn't made their profile public shows up with every field blank rather than being omitted.

As with the other listing APIs, IDs and the rating and price fields come back as strings, not numbers.

Did this answer your question?