Running a Roster Across a Season

A roster is not a one-off check. It is a standing question, and the lifecycle is built around that.

Submit early, and resubmit freely

Submit as soon as entries open, using your own event identifier. Resubmitting the same identifier replaces the line-up in place rather than creating a second roster, so you can push your current entrants on a schedule without tracking our identifiers or cleaning up duplicates.

Players who survive a resubmission keep their previous verdict. A single substitution will not read as everybody having just changed status.

Hold it open

Between submission and kickoff, leave the roster open and let clearance stay current. This is the period the product exists for. If you have webhooks, you do not need to poll — you will hear about changes as they happen.

Reading clearance is free and does not consume seats, so a dashboard can poll GET as often as it likes. Only a re-check bills.

Lock the line-up

Once entrants are final, set the roster to locked. That stops the line-up changing — but clearance keeps refreshing. This trips people up, and it is deliberate: locking is about the roster being final, not about stopping the verification. Catching a player going bad between lock and kickoff is the whole point.

When a cleared player goes bad

You will get a guardian.roster.entry.changed event with direction set to regression. What to do next is your call and your rulebook's, but the useful questions are:

• Is it blocked or review? A ban is usually clean-cut. A review may just mean their scan went stale, which a message to the player can fix in ten minutes.
• How close is kickoff? A stale attestation four days out is an admin task. The same thing twenty minutes before a final is a decision.
• Do you have a substitute rule? Decide this before the season, not during the incident. Organizers who write it down in advance have a much easier time than organizers improvising in front of an audience.

Archive when you are done

Set the roster to archived after the event. It stops appearing as active work and stops being re-checked, and the record stays available for disputes.

Seats and budgeting

A seat is one player checked on one roster, once. Submitting a 50-player roster costs 50 seats; re-checking it costs 50 more. Your allowance is monthly, and GET /api/guardian/rosters reports what you have used.

Practically: budget for your entrant count, times roughly how many times you expect to re-check across the event. Most organizers land between two and five checks per event — submission, a mid-week sweep, and match day.