Players API — register, activate, and manage players

The Players API manages individual athlete profiles within Gestor Deportivo. A player profile stores biographical data, position preferences, and all in-game statistics (goals, cards, fouls). Before a player can be added to a team roster, they must be registered and then activated via an email confirmation code — ensuring every player profile is tied to a verified account.

Every request that requires authentication must include the header access-token: <jwt_token>. There is no Authorization: Bearer header on this API.

Player Lifecycle

New players go through a three-stage lifecycle before they can appear in tournament rosters:

register (/api/player/register)
    │
    ▼  email with activation code sent automatically
activate (/api/player/activate/:playerId/player)
    │
    ▼  activate: true
add to team roster (/api/team/updating/:teamId/players)

Register — Create the player profile. The player is stored with activate: false and an activation code is emailed to the authenticated user.
Activate — Submit the code received by email. Sets activate: true.
Add to team — Once active, use the Teams API to assign the player to a roster with a position and shirt number.

A player with activate: false cannot be added to a team roster. Always activate before assigning to a team.

Position Codes

All position fields (myPosition on a player profile, position on a roster entry) use the following codes:

Code	Full Name	Category
`GK`	Goalkeeper	Goalkeeper
`CB`	Centre-Back	Defender
`LB`	Left-Back	Defender
`RB`	Right-Back	Defender
`LWB`	Left Wing-Back	Defender
`RWB`	Right Wing-Back	Defender
`CDM`	Central Defensive Midfielder	Midfielder
`CM`	Central Midfielder	Midfielder
`CAM`	Central Attacking Midfielder	Midfielder
`LM`	Left Midfielder	Midfielder
`RM`	Right Midfielder	Midfielder
`LW`	Left Winger	Forward
`RW`	Right Winger	Forward
`CF`	Centre Forward	Forward
`ST`	Striker	Forward

Registration & Activation

Register a Player

POST /api/player/register Creates a new player profile linked to the authenticated user’s account. The player starts as inactive (activate: false). An activation code is automatically sent to the user’s registered email address. Auth required: Yes

namePlayer

string

required

Full name of the player.

genero

string

required

Player’s gender.

height

number

required

Player height (in centimetres).

municipality

string

required

Municipality / city of origin.

departament

string

required

Department / state / province of origin.

age

number

required

Player age in years.

myPosition

string

required

Preferred position code (e.g. GK, ST). See the position codes table above.

avatar

file

Profile photo (multipart/form-data). Optional.

curl -X POST https://api.example.com/api/player/register \
  -H "access-token: <jwt_token>" \
  -F "namePlayer=Carlos Mendoza" \
  -F "genero=Masculino" \
  -F "height=178" \
  -F "municipality=Medellín" \
  -F "departament=Antioquia" \
  -F "age=24" \
  -F "myPosition=CM" \
  -F "avatar=@/path/to/photo.jpg"

Show 200 — Player registered

status

boolean

true on success.

player

object

The newly created player document. activate will be false.

After this call, check the authenticated user’s email inbox for the activation code and pass it to Activate a Player.

Activate a Player

POST /api/player/activate/:playerId/player Confirms the player profile using the code sent by email during registration. On success, activate is set to true and the player becomes eligible to join team rosters. Auth required: Yes

playerId

string

required

MongoDB ObjectId of the player to activate.

code

string

required

The activation code received by email.

curl -X POST https://api.example.com/api/player/activate/64b2e3d4f5c6a7b8c9d01234/player \
  -H "access-token: <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{ "code": "A3F7K2" }'

Show 200 — Player activated

status

boolean

true — the player’s activate field is now true.

Profile Management

Update a Player

POST /api/player/update/:playerId/player Updates biographical and positional data for an existing player. All body fields are optional — send only the fields you want to change. Supplying a new avatar file replaces the existing image. Auth required: Yes

playerId

string

required

MongoDB ObjectId of the player to update.

namePlayer

string

Updated full name.

genero

string

Updated gender.

height

number

Updated height in centimetres.

municipality

string

Updated municipality.

departament

string

Updated department / state.

age

number

Updated age.

myPosition

string

Updated preferred position code. See position codes.

avatar

file

Replacement profile photo (multipart/form-data).

curl -X POST https://api.example.com/api/player/update/64b2e3d4f5c6a7b8c9d01234/player \
  -H "access-token: <jwt_token>" \
  -F "height=180" \
  -F "myPosition=CAM" \
  -F "avatar=@/path/to/new-photo.jpg"

Show 200 — Player updated

status

boolean

true on success.

Delete a Player

POST /api/player/remove/:playerId Permanently deletes a player profile and removes them from any team rosters. Auth required: Yes

playerId

string

required

MongoDB ObjectId of the player to delete.

curl -X POST https://api.example.com/api/player/remove/64b2e3d4f5c6a7b8c9d01234 \
  -H "access-token: <jwt_token>"

Show 200 — Player deleted

status

boolean

true on success.

Get Player by ID

POST /api/player/:playerId Fetches the full profile document for a single player, including all stat arrays. Auth required: Yes

playerId

string

required

MongoDB ObjectId of the player.

curl -X POST https://api.example.com/api/player/64b2e3d4f5c6a7b8c9d01234 \
  -H "access-token: <jwt_token>"

Show 200 — Player profile

status

boolean

true on success.

player

object

Full player document. See Player Model for field details.

Listing & Search

List All Players

POST /api/player/to-alls Returns a paginated list of all player profiles accessible to the authenticated user. Auth required: Yes

curl -X POST https://api.example.com/api/player/to-alls \
  -H "access-token: <jwt_token>"

Show 200 — All players

status

boolean

true on success.

data

array

Paginated array of player documents.

pagination

object

{ total, page, perPage, totalPages } pagination metadata.

List Players by Activation Status

POST /api/player/to-list-inactive/:activeParam/:pag?/:perpage? Filters players by their activation status. Pass "true" to list activated players, "false" to list pending/unactivated players. Auth required: Yes

activeParam

string

required

"true" — return only activated players (activate: true).
"false" — return only unactivated players (activate: false).

pag

number

Page number (1-based). Defaults to 1.

perpage

number

Results per page.

# List unactivated players
curl -X POST https://api.example.com/api/player/to-list-inactive/false/1/20 \
  -H "access-token: <jwt_token>"

# List activated players
curl -X POST https://api.example.com/api/player/to-list-inactive/true/1/20 \
  -H "access-token: <jwt_token>"

Show 200 — Filtered player list

status

boolean

true on success.

data

array

Array of player documents matching the requested activation status.

pagination

object

{ total, page, perPage, totalPages } pagination metadata.

Search Players

POST /api/player/search-player/:query/:pag?/:perpage? Case-insensitive search across namePlayer. Useful for autocomplete fields in tournament management UIs. Auth required: No

query

string

required

Search term matched against player names.

pag

number

Page number (1-based). Defaults to 1.

perpage

number

Results per page.

curl -X POST https://api.example.com/api/player/search-player/carlos/1/10

Show 200 — Search results

status

boolean

true on success.

data

array

Matching player documents.

pagination

object

{ total, page, perPage, totalPages } pagination metadata.

Player Model

Every player document returned by the API follows this schema.

_id

string

MongoDB ObjectId.

user

object

Embedded owner snapshot at the time of creation.

Show user fields

_id

string

ObjectId of the owner.

firstName

string

Owner’s first name.

lastName

string

Owner’s last name.

string

Owner’s email address.

code_player

string

System-generated unique player code.

namePlayer

string

Full name of the player.

genero

string

Player’s gender.

height

number

Height in centimetres.

municipality

string

Municipality of origin.

departament

string

Department / state of origin.

age

number

Age in years.

activate

boolean

true if the player has been verified via email code; false until then.

avatar

array

Array of image metadata objects for the player’s profile photo.

myPosition

object

Preferred position details.

Show myPosition fields

value

string

Position code (e.g. CM).

label

string

Human-readable label (e.g. "Central Midfielder").

description

string

Position description text.

Statistics Arrays

Each stat field is stored as an array of entries rather than a flat counter, enabling per-match breakdowns and audit trails.

goalsPlayer

array

Records of goals scored by this player.

ownGoal

array

Records of own goals conceded by this player.

penalty

array

Penalty kick records (scored or missed).

sanctions

array

Active disciplinary sanctions.

totalFaults

array

All fouls/faults committed.

yellowCard

array

Yellow card incidents.

redCard

array

Red card incidents.

blueCard

array

Blue card incidents (used in futsal and some indoor formats).

To aggregate totals from a stat array (e.g. count all goals), use player.goalsPlayer.length on the client side or query with MongoDB aggregation on the server.

Authentication & Users

Teams & Players

Events & Matches

Content

Players API — register, activate, and manage players

Player Lifecycle

Position Codes

Registration & Activation

Register a Player

Activate a Player

Profile Management

Update a Player

Delete a Player

Get Player by ID

Listing & Search

List All Players

List Players by Activation Status

Search Players

Player Model

Statistics Arrays

Build docs developers (and LLMs) love

Authentication & Users

Teams & Players

Events & Matches

Content

Documentation Index

​Player Lifecycle

​Position Codes

​Registration & Activation

​Register a Player

​Activate a Player

​Profile Management

​Update a Player

​Delete a Player

​Get Player by ID

​Listing & Search

​List All Players

​List Players by Activation Status

​Search Players

​Player Model

​Statistics Arrays

Build docs developers (and LLMs) love

Player Lifecycle

Position Codes

Registration & Activation

Register a Player

Activate a Player

Profile Management

Update a Player

Delete a Player

Get Player by ID

Listing & Search

List All Players

List Players by Activation Status

Search Players

Player Model

Statistics Arrays