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:
Fetch the data: call the address and get the response back.
Parse it: convert the raw response into a usable object so individual fields can be read out of it.
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.
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:
https://api.padelos.co/customers/tournament/listing?clubId=216932&sport=padel&availability=available
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.