Teams API — profiles, rosters, and season management

The Teams API gives you full control over team profiles in the Futsal League Manager. Public endpoints expose team detail and roster data for a given season, while admin-protected endpoints handle team creation, updates, soft deletion, and season registration.

Team object

integer

required

Unique team identifier.

name

string

required

Full team name.

kit_color

string

Primary kit colour (free-text, e.g. "red", "#FF0000").

logo_url

string

Public URL of the team logo image (hosted on Cloudinary).

delegate

string

Name of the team delegate or contact person.

coach

string

Name of the head coach.

phone

string

Contact phone number.

is_active

boolean

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

List teams

GET /teams

Returns a paginated, searchable list of active teams. Optionally filtered to teams that have stats or players registered in a specific season.

Query parameters

season_id

integer

Filter to teams enrolled in this season.

exclude_season_id

integer

Exclude teams already enrolled in this season (useful when adding teams 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

{
  "teams": [
    {
      "id": 1,
      "name": "FC Example",
      "logo_url": "https://res.cloudinary.com/.../logo.jpg",
      "kit_color": "blue",
      "delegate": "Jane Smith",
      "coach": "John Doe",
      "phone": "600123456"
    }
  ],
  "pagination": {
    "total": 12,
    "page": 1,
    "limit": 10,
    "totalPages": 2
  }
}

Get team detail

GET /teams/:id

Returns full team profile including the current-season roster, stats, and match schedule. Authentication is optional; when a valid token is provided, the response also includes whether the requesting user follows the team.

Path parameters

integer

required

Team ID.

Query parameters

season_id

integer

Season to scope roster and stats to. Defaults to the active season when omitted.

Response

integer

required

Team ID.

name

string

required

Team name.

kit_color

string

Primary kit colour.

logo_url

string

Logo image URL.

delegate

string

Delegate name.

coach

string

Coach name.

phone

string

Contact phone.

is_active

boolean

Whether the team is active.

isFollowing

boolean

true if the authenticated user follows this team. Always false for unauthenticated requests.

players

object[]

Show player properties

integer

Player ID.

name

string

Player name.

photo_url

string

Player photo URL.

jersey_number

string

Squad number for this season.

goals

integer

Goals scored in the season (defaults to 0).

stats

object | null

Team statistics for the requested season. null when no stats record exists yet.

Show stats properties

played

integer

Matches played.

won

integer

Matches won.

drawn

integer

Matches drawn.

lost

integer

Matches lost.

goals_for

integer

Goals scored.

goals_against

integer

Goals conceded.

points

integer

Total points (3 win / 1 draw / 0 loss).

yellow_cards

integer

Yellow cards accumulated.

red_cards

integer

Red cards accumulated.

group_name

string

Name of the league group.

matches

object[]

All matches for the season involving this team, ordered by date ascending.

upcomingMatches

object[]

Subset of matches where status is "pendiente" (not yet played).

Example

curl https://api.example.com/teams/3

curl "https://api.example.com/teams/3?season_id=2"

Get team roster

GET /teams/:id/players

Returns the list of players assigned to a team for a specific season.

Path parameters

integer

required

Team ID.

Query parameters

season_id

integer

required

Season to retrieve the roster for.

Response

Array of player objects sorted by jersey number:

[
  {
    "id": 7,
    "name": "Carlos López",
    "photo_url": "https://res.cloudinary.com/.../photo.jpg",
    "jersey_number": "10"
  }
]

Create team

POST /teams

Creates a new team. Optionally enrolls the team in a season by creating a team_stats record.

Requires admin authentication. Include a valid Authorization: Bearer <token> header.

Body parameters

name

string

required

Team name.

kit_color

string

Primary kit colour.

logo_url

string

Cloudinary URL of the team logo.

delegate

string

Delegate name.

coach

string

Coach name.

phone

string

Contact phone number.

season_id

integer

If provided, the team is immediately enrolled in this season (a team_stats row is inserted).

Response

201 Created with the newly created team object:

{
  "message": "Equipo creado correctamente",
  "team": {
    "id": 14,
    "name": "Los Rayos",
    "kit_color": "yellow",
    "logo_url": null,
    "delegate": "Ana García",
    "coach": "Pep Mir",
    "phone": "611222333",
    "is_active": true
  }
}

Update team

PUT /teams/:id

Replaces all editable fields on a team. When logo_url changes and the old and new Cloudinary public_id values differ, the old image is deleted automatically.

Requires admin authentication.

Path parameters

integer

required

Team ID.

Body parameters

name

string

required

Team name.

kit_color

string

Primary kit colour.

logo_url

string

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

delegate

string

Delegate name.

coach

string

Coach name.

phone

string

Contact phone number.

Response

{
  "message": "Equipo actualizado correctamente",
  "team": { "id": 14, "name": "Los Rayos FC", "..." : "..." }
}

Soft-delete team

DELETE /teams/:id

Sets is_active = false on the team. The team is moved to the trash but its data is preserved. Use POST /teams/:id/restore to undo.

Requires admin authentication.

Path parameters

integer

required

Team ID.

Response

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

Remove team from a season

DELETE /teams/:id/season/:seasonId

Removes all team_stats rows for the team in the given season and sets team_id = NULL on all team_players rows for that season, effectively detaching players from the team without deleting them from the league.

Requires admin authentication.

Path parameters

integer

required

Team ID.

seasonId

integer

required

Season ID.

Response

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

Register team in a season

POST /teams/:id/register

Enrolls an existing team in a season by creating a team_stats record. Any existing record for the same team-season pair is replaced to prevent duplicates.

Requires admin authentication.

Path parameters

integer

required

Team ID.

Body parameters

season_id

integer

required

Season to enroll the team in.

Response

{ "message": "Equipo inscrito correctamente" }

Toggle follow

POST /teams/:id/toggle-follow

Follows the team if the user is not already following it, or unfollows it if they are. The response includes the new follow state.

Requires user authentication (any role).

Path parameters

integer

required

Team ID.

Response

{ "message": "Ahora sigues al equipo", "isFollowing": true }

{ "message": "Has dejado de seguir al equipo", "isFollowing": false }

Restore team

POST /teams/:id/restore

Reverses a soft-delete by setting is_active = true.

Requires admin authentication.

Path parameters

integer

required

Team ID.

Response

{ "message": "Equipo restaurado correctamente" }

Permanently delete team

DELETE /teams/:id/permanent

Physically removes the team from the database. This action is blocked if the team has any match history or is enrolled in any season.

This action is irreversible. Ensure the team has no associated matches or season stats before calling this endpoint.

Requires admin authentication.

Path parameters

integer

required

Team ID.

Response

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

Admin: trash

GET /teams/admin/trash

Returns all teams where is_active = false, ordered alphabetically.

Requires admin authentication.

Admin: orphans

GET /teams/admin/orphans

Returns active teams that have no team_stats, team_players, or matches associations — useful for cleaning up unused records.

Requires admin authentication.

Admin: season report

GET /teams/admin/report

Returns all teams enrolled in a season, each with their full player roster for that season. Useful for generating printable squad sheets.

Requires admin authentication.

Query parameters

season_id

integer

required

Season to report on.

Authentication

Matches

Teams & Players

Administration

Documentation Index

​Team object

​List teams

​Query parameters

​Response

​Get team detail

​Path parameters

​Query parameters

​Response

​Example

​Get team roster

​Path parameters

​Query parameters

​Response

​Create team

​Body parameters

​Response

​Update team

​Path parameters

​Body parameters

​Response

​Soft-delete team

​Path parameters

​Response

​Remove team from a season

​Path parameters

​Response

​Register team in a season

​Path parameters

​Body parameters

​Response

​Toggle follow

​Path parameters

​Response

​Restore team

​Path parameters

​Response

​Permanently delete team

​Path parameters

​Response

​Admin: trash

​Admin: orphans

​Admin: season report

​Query parameters

Build docs developers (and LLMs) love

Team object

List teams

Query parameters

Response

Get team detail

Path parameters

Query parameters

Response

Example

Get team roster

Path parameters

Query parameters

Response

Create team

Body parameters

Response

Update team

Path parameters

Body parameters

Response

Soft-delete team

Path parameters

Response

Remove team from a season

Path parameters

Response

Register team in a season

Path parameters

Body parameters

Response

Toggle follow

Path parameters

Response

Restore team

Path parameters

Response

Permanently delete team

Path parameters

Response

Admin: trash

Admin: orphans

Admin: season report

Query parameters