Match Management
Every match in 4league moves through a defined lifecycle, from scheduling to final confirmation. The competition organizer drives the live scoreboard end-to-end. This guide covers scheduling, starting and ending live matches, the full list of event types you can record, lineups, video links, and disputes.
Match Lifecycle
Every match goes through a series of states. A match is "live" when its inProgress field holds the kick-off timestamp, and "finished" when that field is cleared.
Scheduled → Started → Finished
| State | What it means | Who can act |
|---|---|---|
| Scheduled | Match has a date and time but has not started. Lineups can be set. | Organizer; Team Managers can edit their own lineups. |
| Started (live) | Kick-off has been pressed. The match's inProgress field is set to a kick-off timestamp and live events (goals, cards, subs, etc.) can be recorded. |
Competition organizer only (see Who can run live scoring). |
| Finished | The match has been ended. inProgress is set back to false and recorded events are locked unless the organizer re-opens the match. |
Organizer can re-open or edit events afterwards. |
| Postponed | Rescheduled before kick-off. A new date must be set by the organizer. | Organizer |
Starting a Match
When the organizer taps "Start Match", the app calls the backend's start-match endpoint. The backend:
- Records the current Unix timestamp (in seconds) on the match as the kick-off time.
- Inserts a kick-off entry in the live-score timeline so subsequent events can be ordered.
- Sends a "Match started" push notification to every user following the competition.
Starting a match does not compute standings or change any other competition state — it only opens the scoreboard.
Ending a Match
When the organizer taps "End Match", the backend clears the inProgress flag on the match (setting it back to false) and records the update timestamp. If the match belongs to a competition that lives inside a parent organization, the backend then asynchronously recalculates that organization's stats and propagates them up the organization tree.
Ending an individual match does not recompute final competition standings, does not trigger promotion or relegation, and does not send a "winner" push notification. Those steps happen only when the organizer finalises the whole competition — see Finalizing a Competition below.
Finalizing a Competition
Finalisation is a separate explicit action — distinct from ending a single match. When the competition's owner marks the competition as completed, the backend:
- Computes the final standings using the competition's tie-breaking rules.
- Sends a "competition winner" push notification to every follower of the competition.
- Awards trophies to the relevant teams.
- Updates global team rankings.
- Applies any promotion and relegation rules configured on the competition, moving qualifying teams into the linked target competitions.
Until this finalisation step runs, finishing an individual match only locks that match's score and events — the competition's overall results, trophies, and promotion/relegation chain remain untouched.
Postponing Matches
When circumstances prevent a match from taking place on its scheduled date, the organizer can postpone it rather than cancelling.
Open the match
Navigate to the match from the competition schedule or the calendar view.
Tap "Postpone"
Select this option from the match actions menu. The match state changes to Postponed.
Set a new date
Choose the rescheduled date and time. All Team Managers and connected players receive a notification with the new date.
A match is scheduled for Saturday at 4 PM. Overnight rain makes the pitch unplayable. The organizer opens the match at 8 AM, taps "Postpone", and sets the new date to the following Saturday. Both Team Managers and all connected players receive a push notification immediately.
Resetting Results
If a score was entered incorrectly, the organizer can re-open a finished match, correct or delete its events, then end it again. The match's events and final score are updated when this happens.
Editing or deleting events after a match is finished changes that match's record immediately. However, competition-wide standings, trophies, top-scorer tables, and promotion/relegation outcomes only refresh when the competition is re-finalised. Notify Team Managers before making corrections.
Score Entry
Final Score
The simplest way to record a match. After the game, open the match and enter the score for each team. Tap "Confirm" to finish the match.
Half-Time Score
Optionally record the half-time score. This is displayed on the match detail page and in match statistics but does not affect the final standings calculation.
Penalty Shootouts
For cup matches that end in a draw, penalty shootout results can be entered separately from the regular 90-minute score.
A cup semi-final ends 2–2 after 90 minutes. The organizer enters the regular score as 2–2. In the penalty section, he enters Team A 4 – Team B 2. The match page shows "Team A wins 4–2 on penalties" and Team A advances to the final.
Match Events
Match events give depth to match records, power individual player stats, and make the match timeline a useful story for fans and coaches alike. The backend accepts a fixed catalogue of event types — only the events listed below are recognised by the live-score API.
Available on the iOS and Android apps only — not currently supported in the web app.
Supported Event Types
| Event | API flag | Meaning | Push notification? |
|---|---|---|---|
| Goal | addGoal |
A regular goal scored by the selected player. | Yes — “New GOOAL!” is pushed to every follower of the match. |
| Card | addCard + cardType |
A card shown to the selected player. When cardType is unset (or falsy) the card is recorded as yellow; when cardType is truthy the card is recorded as red. |
Yes — “Yellow card” or “Red card” is pushed to every follower of the match. |
| Own goal | ownGoal |
The selected player scored against their own team. | No |
| Penalty goal | penaltyGoal |
Goal scored from a penalty kick. | No |
| Missed penalty | missedPenalty |
The selected player took a penalty and did not score. | No |
| Missed goal | missedGoal |
A clear scoring chance that did not result in a goal. | No |
| Save | goalSaved |
A save by the selected player (typically the goalkeeper). | No |
| Assist | goalAssist |
Attributes an assist to the selected player. Recorded as part of, or attached to, a goal event. | No |
| Substitution | addExchange |
Records a player swap between bench and pitch. | No |
| Foul | addFoul |
A foul committed by the selected player. | No |
| VAR review | VAR |
Marks a VAR review on the timeline, with optional free-text detail. | No |
| Personal mistake | personalMistake |
Highlights a notable individual error. | No |
| Message | message |
A free-text note attached to the match timeline (commentary, weather break, etc.). | No |
Of all the events above, only goals (addGoal) and cards (addCard) trigger push notifications to people following the match. Other events are written to the live timeline silently and are visible to anyone who opens the match page, but they do not interrupt followers' devices.
Minute 23: Goal by Player A (assist Player B) — score 1–0. A "New GOOAL!" notification is sent to followers. Minute 45: Yellow card to Player C — followers receive a "Yellow card" push. Minute 60: Substitution — Player D replaces Player E, timeline only. Minute 78: Red card to Player F — followers get a "Red card" push. Minute 89: Goal by Player G — score 1–1, another goal push goes out. Each event appears on the timeline immediately for anyone watching the live match page.
Events can be added after the match is finished as well as during live mode. If you missed logging a goal during the game, the organizer can add it retrospectively and the stats will update.
Live Score Mode
Live Score Mode transforms 4league into a real-time scoreboard. Fans following the competition see events within seconds of them being entered.
Available on the iOS and Android apps only — not currently supported in the web app.
How Live Mode Works
Start live mode at kick-off
Open the match and tap "Start Match". The match's inProgress field is set to the current Unix timestamp, a kick-off entry is written to the timeline, and a "Match started" push goes out to everyone following the competition.
Add events in real time
Tap an event type from the supported list, enter the minute and relevant players, and confirm. The event is appended to the live timeline immediately. Goals and cards also fan out a push notification to followers.
Edit mistakes inline
If an event was entered against the wrong player or at the wrong minute, the organizer can edit or delete it directly from the match timeline while the match is still live.
End the match
Tap "End Match". The match's inProgress field is cleared, the final score and events are locked, and any parent-organization stats are recalculated in the background.
Organizer Ion taps "Start Match" at kick-off — every follower of the competition immediately receives a "Match started" push. As goals and cards happen, Ion enters them from the sideline; followers see each goal and card as a push within seconds, while other events (subs, fouls, VAR notes) silently update the timeline. At the final whistle, Ion taps "End Match" — the scoreboard locks and the recorded events become the official record.
Who can run live scoring
In the current backend, every live-scoring action is restricted to the competition organizer. That covers all five live-match actions: starting the match, adding live events (goals, cards, subs, fouls, VAR notes, messages, etc.), editing an event, deleting an event, and ending the match.
If a Team Manager or an assigned referee tries to call any of these endpoints, the backend returns 403 noRights and logs a security event. So referees and Team Managers can watch live scoring as it happens, but they cannot operate the scoreboard from inside the app today.
If you are an organizer who cannot be at the pitch, share a device that is logged in as the organizer account with a trusted volunteer — or schedule the score entry to happen post-match. Referees on their own accounts cannot currently run the live scoreboard.
The route layer ships a more permissive middleware that, on paper, would also accept the assigned match referee and any competition owner or member. However, each live-match controller currently overrides that with an admin-only fallback check, which is why only the organizer succeeds in practice. This is intentional belt-and-braces protection — the user-facing rule is the one stated above: organizer only.
Lineups & Formations
Before a match starts, Team Managers and organizers can set the formation and assign players to positions. This data feeds into match statistics and provides a tactical record of the game.
Available on the iOS and Android apps only — not currently supported in the web app.
Setting a Lineup
Open the match lineup screen
Available from the match detail page before the match starts.
Select a formation
Choose from standard formations (4-4-2, 4-3-3, 3-5-2, etc.) using the formation picker.
Assign players to positions
Tap each position on the pitch view and select the player from your squad list.
Mark the captain and substitutes
Designate one player as captain. Add up to 7 substitutes to the bench.
Coach Elena opens the lineup screen 30 minutes before kick-off. She selects 4-4-2, assigns all 11 starters to their positions, marks the goalkeeper as captain, and lists 5 substitutes. The lineup is saved and visible to fans browsing the match page.
Match Video Links
The organizer can attach a video link to any match. This is useful for leagues that broadcast matches on YouTube or stream via other platforms.
Open match settings
Navigate to the match detail page and tap the Edit or Settings button.
Paste the video URL
Enter a YouTube, Twitch, or other stream URL into the Video Link field.
Save and notify
Save the match. A "Watch Live" button now appears on the match detail page for all users.
The organizer of a county cup adds the YouTube live stream link one hour before kick-off. Fans browsing the match in the app see a "Watch Live" button. Tapping it opens the stream directly without leaving the app.
Match Acceptance & Disputes
After a match result is recorded, Team Managers can accept or dispute the outcome. This provides a fair way to flag errors or controversial decisions for the organizer to review before results become final.
Acceptance Flow
Result recorded by the organizer
Both Team Managers receive a notification that a result has been recorded and is pending their acceptance.
Team Manager accepts or disputes
If accepted by both sides, the result is confirmed. If disputed, the organizer is alerted to review.
Organizer resolves the dispute
The organizer reviews the match, corrects events if necessary, and re-confirms the result. Both teams are notified of the resolution.
After a heated match, Team B believes the recorded score is incorrect — the organizer entered 3–1 but Team B's manager insists one goal was offside and should not count. Team B taps "Dispute" and writes a brief note. The organizer reviews the match events, consults the referee, and confirms the original 3–1 score. Team B is notified and the result is finalised.
The organizer always has final authority over match results. A dispute flags the result for review but does not automatically change anything until the organizer makes a decision.