---
title: "Get a player"
method: GET
path: "/v1/players/{player_id}"
tags: ["players"]
---

# Get a player

`GET /v1/players/{player_id}`

## Request

- Base URL: `https://lumify.ai`
- URL: `https://lumify.ai/v1/players/{player_id}`
- Auth: HTTP bearer

## Path parameters

- `player_id` integer, required

## Response `200`

Successful Response

- Player: Directory identity for one player. Shared keys on every sport; null means unknown, not 'wrong sport'. Sport-named metrics do not live here — tennis ranking is ``rankings`` (null on every other sport). Tennis ``/stats`` also exposes ``ranking`` / ``ranking_points`` on the tennis player block.
  - `id` integer, nullable: Lumify player ID.
  - `slug` string, nullable: URL-safe unique slug.
  - `full_name` string, nullable: Display name.
  - `first_name` string, nullable
  - `last_name` string, nullable
  - `sport` string, nullable: Sport slug, e.g. mlb, tennis, nfl.
  - `country_code` string, nullable: ISO 3166-1 alpha-3 country code.
  - `birthdate` string, nullable: YYYY-MM-DD date of birth.
  - `position` string, nullable: Roster position abbreviation when the sport has one (e.g. C, P, SS for MLB; QB, WR for NFL). Null for tennis and when not yet ingested.
  - `handedness` string, nullable: left | right | switch. Meaning is sport-specific (bats for MLB, shoots for NHL, playing hand for tennis). Null when unknown.
  - `height_cm` integer, nullable: Height in centimetres. Null when not ingested.
  - `weight_kg` number, nullable: Weight in kilograms. Null when not ingested.
  - `rankings` PlayerRankings
    - `singles` integer, nullable: ATP/WTA singles ranking. Tennis only.
    - `points` integer, nullable: ATP/WTA ranking points. Tennis only.
  - `current_team_id` integer, nullable: Lumify team ID when the player is on a club roster. Null for tennis.
  - `current_team_name` string, nullable: Current team display name. Null for tennis.
  - `is_active` boolean, nullable: False when deactivated or retired.
  - `retired_at` string, nullable: YYYY-MM-DD retirement date when known.
  - `image_url` string, nullable: Lumify media URL for the player headshot (https://lumify.ai/media/players/{sport}/{id}.{ext}). Null until the sport's headshot/enrichment job. Never a vendor CDN.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/lumify/apis/lumify-sports-intelligence-api.md) · [All operations](https://skmtc.dev/lumify/apis/lumify-sports-intelligence-api/llms.txt) · [OpenAPI document](https://skmtc.dev/lumify/apis/lumify-sports-intelligence-api/revisions/f91ea41a2606?raw)