Player absences

Why a player is missing from a match arrives as an absence object on the player record. It appears on three endpoints:

Endpoint	Context
GET /v2/events/{id}/sub-participants	this match
GET /v2/participants/{id}	one player
GET /v2/participants/{id}/squad	a club or national-team squad

Only at VIP level

Absence information is provided exclusively for competitions covered at VIP level. At any other coverage level the field is null for every player - which is correct behaviour, not missing data.

The shape

No absence:

"absence": null

An absence:

"absence": {
  "id": 10,
  "position_reason_id": 2,
  "position_detailed_reason_id": 43,
  "due_to": null
}

You resolve two ids: position_reason_id against the three general reasons, and position_detailed_reason_id against the 72 detailed ones. The example above is a suspension (2) for cards (43).

The specification describes this field wrongly

ParticipantDetails.absence in the published OpenAPI document is typed as:

{ "type": ["array", "null"], "items": { "type": "string" } }

That is an array of strings. The real field is an object with four keys, shown above.

A client generated from the specification will therefore fail to parse a player who is actually absent. This is reported to the API team; until it is fixed, treat the schema for this one field as unreliable and code against the shape documented here.

due_to was null in every sample we captured, so its type and vocabulary are unconfirmed.

General reasons

id	Reason	Detailed reasons
1	Injury	42
2	Suspension	4
3	Other	26

Detailed reasons

Ids run 1 to 72 with no gaps. Grouped by their general reason:

Injury (position_reason_id: 1)

id	Name	id	Name
1	Hamstring Injury	22	Hand injury
2	Groin Injury	23	Heel injury
3	Achilles injury	24	Neck injury
4	Knee Injury	25	Oblique injury
5	Head injury	26	Quadricep injury
6	Calf injury	27	Pectoral injury
7	Thigh Injury	28	Pelvis injury
8	Chest Injury	29	Shin injury
9	Muscle injury	30	Thumb injury
10	Hip injury	31	Toe injury
11	Ankle injury	32	Triceps injury
12	Foot injury	33	Wrist injury
13	Back injury	34	Lower Leg injury
14	Shoulder injury	35	Ribs injury
15	Abdomen injury	36	Upper-Body Injury
16	Collarbone injury	37	Lower-Body Injury
17	Elbow injury	38	Patellar tendinitis
18	Eye injury	39	Concussion
19	Fibula injury	40	Illness
20	Finger injury	41	Physically unable to perform
21	Forearm injury	42	Injured reserve

Note that 40 Illness and 41 Physically unable to perform sit under Injury, not under Other - if you group by general reason for a UI badge, an illness shows as an injury.

Suspension (position_reason_id: 2)

id	Name
43	Cards
44	Team Suspension
45	League Suspension
46	Federation Suspension

Other (position_reason_id: 3)

id	Name	id	Name
47	Coach's decision	60	Disciplinary Action
48	Rest	61	Family Emergency
49	Club decision/Contract situation	62	Legal Matter
50	Trade-related reasons	63	Bereavement
51	Healthy scratch	64	Tactical decision
52	International duty	65	Optioned to minors
53	Legal issues	66	Not With Team
54	Military service	67	G League
55	Unknown reason	68	Concussion Protocol
56	Administrative reasons	69	Trade Pending
57	Transfer/Club change	70	Health and Safety Protocols
58	Personal reasons	71	Ineligible to Play
59	League Investigation	72	Return to Competition Reconditioning

Several of these are league-specific (G League, Optioned to minors, Healthy scratch come from North American sports), so expect a sparse distribution in any single competition.

This catalogue is hand-maintained

Unlike the per-sport data reference, these ids are not generated. There is no catalogue endpoint and no enum in the specification, so this table is a copy that can drift.

It lives in data/reference/absence-reasons.json as data, not prose, so that the day the API exposes a catalogue it can be replaced by a generated table without rewriting this page. The ask to the API team is a /v2/absence-reasons endpoint or an enum on the field.

Next

• Coverage levels - why this data only exists at VIP
• Get a squad - where the field appears in practice