Players API — profiles, stats, and season registration

The Players API lets you manage individual player profiles and their season-by-season participation. Player records are global — the same player can belong to different teams across different seasons via the team_players join table. Stats such as goals, yellow cards, and red cards are always scoped to a season.

Player statistics are per-season. The GET /players/:id endpoint returns stats for the currently active season. To fetch stats for a specific season, enrich player data from the Statistics API using the season_id query parameter.

Player object

integer

required

Unique player identifier.

name

string

required

Full player name.

birth_date

string

Date of birth in YYYY-MM-DD format.

photo_url

string

Public URL of the player photo (hosted on Cloudinary).

is_active

boolean

false when the player has been soft-deleted (sent to trash).

Get player detail

GET /players/:id

Returns a player’s profile together with their stats and current team for the active season.

Path parameters

integer

required

Player ID.

Response

integer

required

Player ID.

name

string

required

Player name.

birth_date

string

Date of birth (YYYY-MM-DD).

photo_url

string

Photo URL.

is_active

boolean

Whether the player is active.

team_id

integer | null

ID of the team the player belongs to in the active season.

team_name

string | null

Name of that team.

team_logo

string | null

Logo URL of that team.

stats

object | null

Season statistics. null if no stats record exists for the active season.

Show stats properties

integer

Stats record ID.

player_id

integer

Player ID.

season_id

integer

Season ID.

goals

integer

Goals scored.

yellow_cards

integer

Yellow cards received.

red_cards

integer

Red cards received.

matches_played

integer

Number of matches played.

Example

curl https://api.example.com/players/7

{
  "id": 7,
  "name": "Carlos López",
  "birth_date": "1998-04-15",
  "photo_url": "https://res.cloudinary.com/.../photo.jpg",
  "is_active": true,
  "team_id": 3,
  "team_name": "FC Example",
  "team_logo": "https://res.cloudinary.com/.../logo.jpg",
  "stats": {
    "id": 42,
    "player_id": 7,
    "season_id": 2,
    "goals": 11,
    "yellow_cards": 2,
    "red_cards": 0,
    "matches_played": 9
  }
}

List players

GET /players

Returns a paginated, searchable list of active players. When season_id is supplied, only players enrolled in that season are returned, each with their team name and jersey number.

Requires admin authentication.

Query parameters

season_id

integer

Filter to players enrolled in this season.

exclude_season_id

integer

Exclude players already enrolled in this season (useful when assigning players to a new season).

string

default:""

Case-insensitive, accent-insensitive name filter.

page

integer

default:"1"

Page number (1-indexed).

limit

integer

default:"10"

Number of results per page.

Response

{
  "players": [
    {
      "id": 7,
      "name": "Carlos López",
      "birth_date": "1998-04-15",
      "photo_url": "https://res.cloudinary.com/.../photo.jpg",
      "is_active": true,
      "team_name": "FC Example",
      "jersey_number": "10",
      "team_id": 3
    }
  ],
  "pagination": {
    "total": 34,
    "page": 1,
    "limit": 10,
    "totalPages": 4
  }
}

Create player

POST /players

Creates a new player. Optionally enrolls them in a season and assigns them to a team in the same request.

Requires admin authentication.

Body parameters

name

string

required

Full player name.

birth_date

string

Date of birth in YYYY-MM-DD format.

photo_url

string

Cloudinary URL of the player photo.

season_id

integer

If provided, creates a team_players row for this season.

team_id

integer

Team to assign the player to (requires season_id). When season_id is set but team_id is omitted, the player is enrolled in the season without a team.

Response

201 Created:

{
  "message": "Jugador creado correctamente",
  "player": {
    "id": 21,
    "name": "Marcos Ruiz",
    "birth_date": "2001-08-22",
    "photo_url": null,
    "is_active": true
  }
}

Update player

PUT /players/:id

Updates a player’s profile fields. When photo_url changes and the Cloudinary public_id differs, the old photo is automatically deleted from Cloudinary.

Requires admin authentication.

Path parameters

integer

required

Player ID.

Body parameters

name

string

required

Full player name.

birth_date

string

Date of birth in YYYY-MM-DD format.

photo_url

string

New photo URL. Pass the existing URL to keep the current photo.

Response

{
  "message": "Jugador actualizado correctamente",
  "player": { "id": 21, "name": "Marcos Ruiz Sánchez", "...": "..." }
}

Register player in a team/season

POST /players/:id/register

Enrolls a player in a season and optionally assigns them to a team. Any existing enrollment for the player in the same season is removed first to prevent duplicates.

Calling this endpoint replaces any existing team assignment for the player in the given season. Use it to transfer a player between teams mid-season.

Requires admin authentication.

Path parameters

integer

required

Player ID.

Body parameters

season_id

integer

required

Season to enroll the player in.

team_id

integer

Team to assign the player to. Omit to enroll in the season without a team.

jersey_number

string

Squad number. Must be unique within the team and season.

Response

{ "message": "Jugador inscrito o traspasado correctamente" }

Unregister player from a team

DELETE /players/:id/unregister

Removes a player’s assignment from a specific team and season. The player record itself is not deleted.

Requires admin authentication.

Path parameters

integer

required

Player ID.

Body parameters

team_id

integer

required

Team to remove the player from.

season_id

integer

required

Season to scope the removal to.

Response

{ "message": "Jugador dado de baja del equipo correctamente" }

Remove player from a season

DELETE /players/:id/season/:seasonId

Removes all of the player’s team_players records for the given season and deletes their player_stats for that season. The player profile is not deleted.

Requires admin authentication.

Path parameters

integer

required

Player ID.

seasonId

integer

required

Season ID.

Response

{ "message": "Jugador eliminado de la temporada correctamente" }

Soft-delete player

DELETE /players/:id

Sets is_active = false on the player. The player is moved to the trash but their data is preserved. Use POST /players/:id/restore to undo.

Requires admin authentication.

Path parameters

integer

required

Player ID.

Response

{ "message": "Jugador enviado a la papelera correctamente" }

Restore player

POST /players/:id/restore

Reverses a soft-delete by setting is_active = true.

Requires admin authentication.

Path parameters

integer

required

Player ID.

Response

{ "message": "Jugador restaurado correctamente" }

Permanently delete player

DELETE /players/:id/permanent

Physically removes the player from the database. Blocked if the player has match event history (goals/cards) or is enrolled in any team or season.

This action is irreversible. Ensure the player has no match events or season enrollments before calling this endpoint.

Requires admin authentication.

Path parameters

integer

required

Player ID.

Response

{ "message": "Jugador eliminado definitivamente de la base de datos" }

Admin: trash

GET /players/admin/trash

Returns all players where is_active = false, ordered alphabetically.

Requires admin authentication.

Admin: orphans

GET /players/admin/orphans

Returns active players that have no team_players, player_stats, or match_events associations — useful for cleaning up unused records.

Requires admin authentication.

Authentication

Matches

Teams & Players

Administration

Documentation Index

​Player object

​Get player detail

​Path parameters

​Response

​Example

​List players

​Query parameters

​Response

​Create player

​Body parameters

​Response

​Update player

​Path parameters

​Body parameters

​Response

​Register player in a team/season

​Path parameters

​Body parameters

​Response

​Unregister player from a team

​Path parameters

​Body parameters

​Response

​Remove player from a season

​Path parameters

​Response

​Soft-delete player

​Path parameters

​Response

​Restore player

​Path parameters

​Response

​Permanently delete player

​Path parameters

​Response

​Admin: trash

​Admin: orphans

Build docs developers (and LLMs) love

Player object

Get player detail

Path parameters

Response

Example

List players

Query parameters

Response

Create player

Body parameters

Response

Update player

Path parameters

Body parameters

Response

Register player in a team/season

Path parameters

Body parameters

Response

Unregister player from a team

Path parameters

Body parameters

Response

Remove player from a season

Path parameters

Response

Soft-delete player

Path parameters

Response

Restore player

Path parameters

Response

Permanently delete player

Path parameters

Response

Admin: trash

Admin: orphans