Player Matches API

Intelligent match-making system for finding and organizing padel matches

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

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

id · 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

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

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

id · 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

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

id · 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

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

id · string (UUID) · required

ID of the invitation to decline

Response

Returns 204 No Content on success.

Example Request

cURL

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

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

id · string (UUID) · required

ID of the match to leave

Response

Returns 204 No Content on success.

Example Request

cURL

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

id · string (UUID) · required

ID of the match

Response

Returns 204 No Content on success.

Example Request

cURL

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

id · 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

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

id · string (UUID) · required

ID of the match to cancel

Response

Returns 204 No Content on success.

Example Request

cURL

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.