Skip to content

Matches

Submit verified 2v2 results so ratings update with audit trail.

Plan: Requires Pro or Enterprise. Starter receives HTTP 403 plan_forbidden.

POST /v1/matches

Scope: write:matches. trust_tier partner_attested, tournament_official, and imported complete immediately and update PadelRank scores. player_confirmed is stored as pending until your product confirms it.

Every participant must be a public player, a private player your partner created, or a member of one of your rosters.

cURL
curl -s -X POST "https://api.padelrank.me/v1/matches" \
    -H "Authorization: Bearer $PADELRANK_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "external_ref": "your-app-match-9821",
    "played_at": "2026-06-16T18:30:00Z",
    "winning_team": "A",
    "trust_tier": "partner_attested",
    "participants": [
      { "username": "maria_s", "team": "A", "court_position": "left" },
      { "username": "joao_p", "team": "A", "court_position": "right" },
      { "username": "ana_r", "team": "B", "court_position": "left" },
      { "username": "pedro_l", "team": "B", "court_position": "right" }
    ],
    "set_scores": [
      {
        "set_number": 1,
        "team_a_games": 6,
        "team_b_games": 4,
        "game_winners": ["A","A","A","A","B","B","B","B","A","A"]
      },
      {
        "set_number": 2,
        "team_a_games": 6,
        "team_b_games": 2
      }
    ]
  }'

Participants accept either profile_id or username per slot.

Optional set_scores stores the scoreline. Optional game_winners on each set is the chronological list of games (A / B). Optional first_server_team is who served game 1 — teams alternate, so the API can derive serve vs return without tagging every game. Optional competition_type (social, training, league, tournament), duration_minutes, venue_label, and session_external_ref tag a club night. See Coach analysis.

POST /v1/matches/batch

Ingest a social night or americano round in one call (max 25 matches). Session fields apply to every match unless a match overrides them.

cURL
curl -s -X POST "https://api.padelrank.me/v1/matches/batch" \
    -H "Authorization: Bearer $PADELRANK_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "session_external_ref": "friday-social-2026-06-20",
    "venue_label": "Club night",
    "competition_type": "social",
    "matches": [
      {
        "external_ref": "court-1-round-1",
        "played_at": "2026-06-20T19:00:00Z",
        "winning_team": "A",
        "trust_tier": "partner_attested",
        "duration_minutes": 55,
        "participants": [
          { "username": "maria_s", "team": "A", "court_position": "left" },
          { "username": "joao_p", "team": "A", "court_position": "right" },
          { "username": "ana_r", "team": "B", "court_position": "left" },
          { "username": "pedro_l", "team": "B", "court_position": "right" }
        ],
        "set_scores": [
          {
            "set_number": 1,
            "team_a_games": 6,
            "team_b_games": 4,
            "first_server_team": "A",
            "game_winners": ["A","A","A","A","B","B","B","B","A","A"]
          }
        ]
      }
    ]
  }'

GET /v1/matches

List matches your partner submitted. Scope: write:matches or read:players. Query: limit (1–100, default 25), offset, session_external_ref, since.

GET /v1/matches/sessions/{ref}

Club-night recap: unique players, closest vs lopsided scorelines, average duration, and a win leaderboard. Same session_external_ref you sent on ingest.

cURL
curl -s "https://api.padelrank.me/v1/matches/sessions/friday-social-2026-06-20" \
    -H "Authorization: Bearer $PADELRANK_API_KEY"

GET /v1/matches/{id}

Returns match metadata, participants, and set_scores (including game_winners when ingested) for matches your partner submitted.

Idempotency

Always send external_ref from your domain. Duplicate refs for the same partner return HTTP 409 with the existing match id. There is no separate idempotency header.