---
title: "Upsert Roster"
method: POST
path: "/api/v1/roster"
tags: ["Roster"]
---

# Upsert Roster

`POST /api/v1/roster`

Upsert roster entries (batch support).

For each entry:
1. Resolve player_id: use provided value, look up by (team_id, jersey_number, season), or generate new UUID
2. Upsert player_info (by player_id)
3. Upsert player_jersey mapping (team_id + jersey_number + season -> player_id)
4. Upsert roster entry
5. Upsert team_roster (season + player_id -> team_id)

**Important:** When a player changes jersey number, you MUST provide `player_id` in the request.
Otherwise the system cannot resolve the existing player (the new jersey has no prior mapping)
and will create a duplicate player record. player_id is the canonical identity; jersey_number
is only a roster attribute.

## Headers

- `x-api-key` string, nullable
- `League` string, nullable

## Request body

- RosterUpsertRequest — Request schema for upserting roster entries (batch support).
  - `entries` RosterEntryRequest[], required — List of roster entries to upsert
    - `player_id` string, nullable — Player identifier. Auto-resolved from jersey number if not provided. Required when updating a player who changed jersey number—otherwise a duplicate player record will be created.
    - `team_id` string, required — Team identifier
    - `jersey_number` integer, required — Player's jersey number
    - `season` string, required — Season identifier (e.g. '2024-25')
    - `player_name` string, nullable — Player's name (can be filled in later)

## Response `200`

Successful Response

- RosterUpsertResponse — Response schema for roster upsert operation.
  - `success` boolean, required — Whether the operation was successful
  - `message` string, required — Status message
  - `entries` RosterEntryResponse[], required — List of upserted roster entries
    - `id` integer, required — Unique identifier of the roster entry
    - `player_id` string, required — Player identifier
    - `team_id` string, required — Team identifier
    - `jersey_number` integer, required — Player's jersey number
    - `player_name` string, required — Player's name

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/preciser/apis/preciser-data-management-api.md) · [All operations](https://skmtc.net/preciser/apis/preciser-data-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/preciser/preciser-data-management-api/versions/c5f6b8674011/schema)