Player Matches API

The Hub platform provides an intelligent match-making system that helps players find opponents, organize matches, and manage invitations.

Search Available Match Slots

Search for available court slots with eligible players nearby for organizing a match.

Endpoint

GET /api/match/search

Query Parameters

lat

number

required

Latitude of the search center point

lng

number

required

Longitude of the search center point

radiusKm

number

default:"10"

Search radius in kilometers

date

string (date)

required

Date to search for available slots (ISO format: YYYY-MM-DD)

startTimeFrom

string (time)

required

Earliest acceptable start time (ISO format: HH:MM:SS)

startTimeTo

string (time)

required

Latest acceptable start time (ISO format: HH:MM:SS)

slotDurationMinutes

integer

default:"90"

Duration of the match in minutes

format

string

default:"TWO_VS_TWO"

Match format: TWO_VS_TWO, ONE_VS_ONE, AMERICANO

skillLevel

string

default:"ANY"

Required skill level: ANY, BEGINNER, INTERMEDIATE, ADVANCED, PROFESSIONAL

Response

Returns an array of available match slots sorted by distance.

resourceId

string (UUID)

required

ID of the available resource (court)

resourceName

string

required

Name of the court

resourceType

string

required

Type of the resource

venueId

string (UUID)

required

ID of the venue

venueName

string

required

Name of the venue

venueCity

string

required

City where the venue is located

venueLatitude

number

required

Venue latitude coordinate

venueLongitude

number

required

Venue longitude coordinate

distanceKm

number

required

Distance from search center in kilometers

startTime

string (time)

required

Slot start time

endTime

string (time)

required

Slot end time

price

number

required

Total price for the court booking

currency

string

required

Currency code

eligiblePlayersNearby

integer

required

Number of eligible players in the area who could join this match

Example Request

curl -X GET "https://api.hub.example.com/api/match/search?lat=40.4168&lng=-3.7038&radiusKm=5&date=2026-03-15&startTimeFrom=18:00:00&startTimeTo=21:00:00&slotDurationMinutes=90&format=TWO_VS_TWO&skillLevel=INTERMEDIATE" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example Response

[
  {
    "resourceId": "660e8400-e29b-41d4-a716-446655440001",
    "resourceName": "Court 1",
    "resourceType": "PADEL_COURT",
    "venueId": "550e8400-e29b-41d4-a716-446655440000",
    "venueName": "Padel Center Madrid",
    "venueCity": "Madrid",
    "venueLatitude": 40.4200,
    "venueLongitude": -3.7050,
    "distanceKm": 0.8,
    "startTime": "18:00:00",
    "endTime": "19:30:00",
    "price": 40.00,
    "currency": "EUR",
    "eligiblePlayersNearby": 12
  }
]

Create Match Request

Create a match request, block the court slot, and initiate the match-making process.

Endpoint

POST /api/match/requests

Request Body

resourceId

string (UUID)

required

ID of the resource to book

bookingDate

string (date)

required

Date of the match (ISO format: YYYY-MM-DD)

startTime

string (time)

required

Start time of the match (ISO format: HH:MM:SS)

slotDurationMinutes

integer

required

Duration of the match in minutes

format

string

required

Match format: TWO_VS_TWO, ONE_VS_ONE, AMERICANO

skillLevel

string

required

Required skill level: BEGINNER, INTERMEDIATE, ADVANCED, PROFESSIONAL

customMessage

string

Optional custom message to include in player invitations

searchLat

number

required

Latitude for searching eligible players

searchLng

number

required

Longitude for searching eligible players

searchRadiusKm

number

default:"10"

Search radius for finding eligible players in kilometers

Response

string (UUID)

required

Match request ID

resourceId

string (UUID)

required

ID of the booked resource

bookingDate

string (date)

required

Date of the match

startTime

string (time)

required

Start time of the match

endTime

string (time)

required

End time of the match

format

string

required

Match format

skillLevel

string

required

Required skill level

status

string

required

Match status: PENDING_PAYMENT, OPEN, MATCHED, CONFIRMED, COMPLETED, CANCELLED

invitationToken

string (UUID)

required

Shareable invitation token for direct invites

availableSlots

integer

required

Number of available player slots remaining

pricePerPlayer

number

required

Price per player for the match

expiresAt

string (timestamp)

Expiration timestamp for pending payment

players

array

required

Array of players in the match

Example Request

curl -X POST "https://api.hub.example.com/api/match/requests" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceId": "660e8400-e29b-41d4-a716-446655440001",
    "bookingDate": "2026-03-15",
    "startTime": "18:00:00",
    "slotDurationMinutes": 90,
    "format": "TWO_VS_TWO",
    "skillLevel": "INTERMEDIATE",
    "customMessage": "Looking for a fun evening match!",
    "searchLat": 40.4168,
    "searchLng": -3.7038,
    "searchRadiusKm": 5
  }'

Example Response

{
  "id": "990e8400-e29b-41d4-a716-446655440004",
  "resourceId": "660e8400-e29b-41d4-a716-446655440001",
  "bookingDate": "2026-03-15",
  "startTime": "18:00:00",
  "endTime": "19:30:00",
  "format": "TWO_VS_TWO",
  "skillLevel": "INTERMEDIATE",
  "status": "PENDING_PAYMENT",
  "invitationToken": "aa0e8400-e29b-41d4-a716-446655440005",
  "availableSlots": 3,
  "pricePerPlayer": 10.00,
  "expiresAt": "2026-03-08T16:15:00Z",
  "players": [
    {
      "playerId": "770e8400-e29b-41d4-a716-446655440002",
      "team": "TEAM_A",
      "role": "ORGANIZER",
      "joinedAt": "2026-03-08T16:00:00Z",
      "checkedIn": false,
      "checkedInAt": null
    }
  ]
}

After creating a match request, you must confirm payment within 15 minutes using the /api/match/requests/{id}/confirm-payment endpoint. Once payment is confirmed, the system will automatically send invitations to eligible players in the area.

Get My Matches

Retrieve all matches the authenticated player is participating in.

Endpoint

GET /api/match/requests/my

Response

Returns an array of match request objects (same structure as Create Match Request response).

Example Request

curl -X GET "https://api.hub.example.com/api/match/requests/my" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get Match Invitations

Retrieve all pending match invitations for the authenticated player.

Endpoint

GET /api/match/invitations

Response

string (UUID)

required

Invitation ID

matchRequestId

string (UUID)

required

ID of the match request

status

string

required

Invitation status: PENDING, ACCEPTED, DECLINED, EXPIRED

sentAt

string (timestamp)

required

When the invitation was sent

respondedAt

string (timestamp)

When the invitation was responded to

bookingDate

string (date)

required

Date of the match

startTime

string (time)

required

Start time of the match

endTime

string (time)

required

End time of the match

format

string

required

Match format

skillLevel

string

required

Required skill level

matchStatus

string

required

Current status of the match

availableSlots

integer

required

Number of available slots

pricePerPlayer

number

required

Price per player

resourceName

string

required

Name of the court

venueName

string

required

Name of the venue

venueCity

string

required

City where the venue is located

Example Request

curl -X GET "https://api.hub.example.com/api/match/invitations" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Accept Match Invitation

Accept a match invitation and join the match.

Endpoint

POST /api/match/invitations/{id}/accept

Path Parameters

string (UUID)

required

ID of the invitation to accept

Request Body

team

string

required

Team to join: TEAM_A or TEAM_B

Response

Returns the updated match request object.

Example Request

curl -X POST "https://api.hub.example.com/api/match/invitations/bb0e8400-e29b-41d4-a716-446655440006/accept" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"team": "TEAM_A"}'

Decline Match Invitation

Decline a match invitation.

Endpoint

POST /api/match/invitations/{id}/decline

Path Parameters

string (UUID)

required

ID of the invitation to decline

Response

Returns 204 No Content on success.

Example Request

curl -X POST "https://api.hub.example.com/api/match/invitations/bb0e8400-e29b-41d4-a716-446655440006/decline" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Join Match by Token

Join a match using a shareable invitation token (for direct invites).

Endpoint

POST /api/match/join/{token}

Path Parameters

token

string (UUID)

required

Invitation token from the match organizer

Request Body

team

string

required

Team to join: TEAM_A or TEAM_B

Response

Returns the updated match request object.

Example Request

curl -X POST "https://api.hub.example.com/api/match/join/aa0e8400-e29b-41d4-a716-446655440005" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"team": "TEAM_B"}'

Leave Match

Leave a match as a non-organizer player (must be more than 48 hours before match start).

Endpoint

DELETE /api/match/requests/{id}/leave

Path Parameters

string (UUID)

required

ID of the match to leave

Response

Returns 204 No Content on success.

Example Request

curl -X DELETE "https://api.hub.example.com/api/match/requests/990e8400-e29b-41d4-a716-446655440004/leave" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Players can only leave a match if it’s more than 48 hours before the start time. For last-minute cancellations, use the Report Absence endpoint instead.

Report Absence

Report that you cannot attend a match. This notifies other players and triggers the system to send substitute invitations.

Endpoint

POST /api/match/requests/{id}/absence

Path Parameters

string (UUID)

required

ID of the match

Response

Returns 204 No Content on success.

Example Request

curl -X POST "https://api.hub.example.com/api/match/requests/990e8400-e29b-41d4-a716-446655440004/absence" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Check In to Match

Check in to a match using your device’s GPS location. This confirms your attendance.

Endpoint

POST /api/match/requests/{id}/checkin

Path Parameters

string (UUID)

required

ID of the match to check in to

Query Parameters

lat

number

required

Your current latitude

lng

number

required

Your current longitude

accuracy

number

required

GPS accuracy in meters

Response

Returns 204 No Content on success.

Example Request

curl -X POST "https://api.hub.example.com/api/match/requests/990e8400-e29b-41d4-a716-446655440004/checkin?lat=40.4200&lng=-3.7050&accuracy=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Check-in is typically required to be within a certain radius of the venue location. Players who don’t check in may be marked as “no-show” which affects their reliability score.

Cancel Match Request

Cancel a match request as the organizer.

Endpoint

DELETE /api/match/requests/{id}

Path Parameters

string (UUID)

required

ID of the match to cancel

Response

Returns 204 No Content on success.

Example Request

curl -X DELETE "https://api.hub.example.com/api/match/requests/990e8400-e29b-41d4-a716-446655440004" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Only the match organizer can cancel a match request. All players will be notified and any payments will be refunded according to the cancellation policy.

Overview

Player Endpoints

Venue Endpoints

Owner Endpoints

Admin Endpoints

​Player Matches API

​Search Available Match Slots

​Endpoint

​Query Parameters

​Response

​Example Request

​Example Response

​Create Match Request

​Endpoint

​Request Body

​Response

​Example Request

​Example Response

​Get My Matches

​Endpoint

​Response

​Example Request

​Get Match Invitations

​Endpoint

​Response

​Example Request

​Accept Match Invitation

​Endpoint

​Path Parameters

​Request Body

​Response

​Example Request

​Decline Match Invitation

​Endpoint

​Path Parameters

​Response

​Example Request

​Join Match by Token

​Endpoint

​Path Parameters

​Request Body

​Response

​Example Request

​Leave Match

​Endpoint

​Path Parameters

​Response

​Example Request

​Report Absence

​Endpoint

​Path Parameters

​Response

​Example Request

​Check In to Match

​Endpoint

​Path Parameters

​Query Parameters

​Response

​Example Request

​Cancel Match Request

​Endpoint

​Path Parameters

​Response

​Example Request

Build docs developers (and LLMs) love

Player Matches API

Search Available Match Slots

Endpoint

Query Parameters

Response

Example Request

Example Response

Create Match Request

Endpoint

Request Body

Response

Example Request

Example Response

Get My Matches

Endpoint

Response

Example Request

Get Match Invitations

Endpoint

Response

Example Request

Accept Match Invitation

Endpoint

Path Parameters

Request Body

Response

Example Request

Decline Match Invitation

Endpoint

Path Parameters

Response

Example Request

Join Match by Token

Endpoint

Path Parameters

Request Body

Response

Example Request

Leave Match

Endpoint

Path Parameters

Response

Example Request

Report Absence

Endpoint

Path Parameters

Response

Example Request

Check In to Match

Endpoint

Path Parameters

Query Parameters

Response

Example Request

Cancel Match Request

Endpoint

Path Parameters

Response

Example Request