Incidents Message Structure

This document describes the structure of Incidents (LiveScore) messages delivered through the Hyper LiveScore Feed.

---

Message Structure

Common Header

Field	Type	Notes
MessageId	string (GUID)	Unique per message; GUID/UUID v4
Timestamp	ISO-8601	UTC
MessageType	int (enum)	1 = Fixture, 2 = LiveScore

LiveScore (Incidents)

Example

{
  "header": {
    "MessageId": "0a5aa9bc-4c5c-4d0a-8f75-0b8f6f12c9a1",
    "Timestamp": "2025-11-04T19:55:25Z",
    "MessageType": 2
  },
  "body": {
    "status": null,
    "id": 777001,
    "fixtureId": 123456,
    "name": "Goal",
    "kind": "ScoreChange",
    "values": [
      { "position": 1, "value": "1" },
      { "position": 2, "value": "0" }
    ],
    "scoreType": 1,
    "initiatorPosition": 1,
    "seconds": 625,
    "playerList": [
      { "id": 501, "teamId": 9001, "name": "Bukayo Saka" }
    ],
    "period": { "id": 1, "name": "1st Half" },
    "confidence": 0.94
  }
}

---

Fields

Field	Type	Required	Notes
fixtureId	int	Yes	Join to fixtures
status	string | null	No	Score/Statistics → 'Empty'/'Cancelled'; Period → 'Started'/'Finished'; else null
id	int	Yes	Incident identifier (reference)
name	string	Yes	Incident label (e.g., Goal)
kind	string	Yes	Incident category
values	array<Value> | null	No	Keyed values (e.g., score per side)
scoreType	int | null	No	Score semantics (if applicable)
initiatorPosition	int (enum) | null	No	1 = home, 2 = away
seconds	int | null	No	Elapsed time from kickoff
period	object	No	period.id: int, period.name: string
playerList	array<Player> | null	No	Optional list of players associated with the incident
confidence	double (0.0–1.0)	Yes	Confidence grade (always present)

---

Object Definitions

Value

Field	Type	Required	Notes
position	int (enum)	No	1 = home, 2 = away
value	string	No	Value for the given position

Player

Field	Type	Required	Notes
id	int	No	Player id
teamId	int | null	No	Team id
name	string	No	Player name

Period

Field	Type	Notes
id	int	Period identifier
name	string	Period name (e.g., "1st Half")

---

Incident Kinds

Common incident kinds include:

Kind	Description
ScoreChange	Score update (goal, point, etc.)
Period	Period start/end
Card	Yellow/red card
Substitution	Player substitution
Corner	Corner kick
Penalty	Penalty event

---

Confidence Score

The confidence field (0.0 to 1.0) indicates the reliability of the incident:

• 0.90+ — High confidence, multi-provider agreement

• 0.70–0.89 — Medium confidence

• Below 0.70 — Lower confidence (not typically published)

---

Related Documentation

• Technical Integration

• Fixture Message Structure

• Code Samples