Club portal integration

Goal: a club manages registrations and squads in its own portal (a member portal with matches, squads and payments) and uses MakeReady for scoring. Scores go back to the MakeReady website (public or private) and/or to the club portal. Both directions can be enabled independently.

Direction 1: club portal → MakeReady (registrations)

The club admin creates an API key in MakeReady with scope registrations:write (and optionally matches:write, matches:read, results:read).
The club admin creates the match in MakeReady with externalId = the id of the match in the club portal — or the club portal creates it itself with POST /api/v1/integrations/matches (scope matches:write; the call is idempotent on externalId). The event is owned by the user who created the API key, so it stays editable in the web portal (stages, status). A portal that links to an event created in MakeReady can set the externalId afterwards with PATCH /api/v1/integrations/matches/:ref.
On every change (or periodically) the club portal sends the complete list:

PUT /api/v1/integrations/matches/<externalId>/registrations
Authorization: Bearer mkr_…
Content-Type: application/json

{
  "source": "member-portal",
  "squads": [{ "externalId": "21", "name": "Squad 1", "startsAt": "2026-10-02T09:00:00Z" }],
  "competitors": [
    { "externalId": "165", "squadExternalId": "21", "firstName": "Stijn", "lastName": "Maes",
      "club": "Example Club", "division": "OPEN", "powerFactor": "major", "categories": [],
      "userEmail": "stijn.maes@agisko.be" }
  ],
  "removeMissing": true
}

Idempotent on externalId: MakeReady ids stay stable across repeated syncs, so scores already recorded stay attached to the right competitor.
userEmail links the registration to a MakeReady account (for "my scores" and private visibility). If the account does not exist yet, the link is made on a later sync.
removeMissing removes competitors who are no longer in the list, unless they already have scores.
From the first sync onwards matches.registration_source is set and squads and registrations in MakeReady are read-only (409 on edit).

Example mapping for a typical member portal

A member portal usually has tables for matches, squads and registrations (competitors). Such a model translates as follows:

Member portal (example)	MakeReady
match id	`match.externalId`
squad id, name, start time	`squads[].externalId`, `name`, `startsAt`
registration/competitor id	`competitors[].externalId`
first name, last name, club, division	same (normalise the division code, e.g. "Open" → `OPEN`)
member's e-mail address	`userEmail`
payment status	only send paid registrations (the club's choice)
discipline	`ipsc_handgun` / `lvr` / `multigun`

If the member portal has no notion of power factor, minor applies by default; the RO can change it at the chrono on the tablet (roadmap) or the club portal extends its registration form.

Direction 2: MakeReady → club portal (scores)

Pull

GET /api/v1/integrations/matches/<externalId>/results (scope results:read) returns the standings per division plus all raw StageScore revisions; the receiver takes the highest revision per (competitor, stage).

Push (webhooks)

The club admin registers a webhook (POST /api/v1/clubs/:id/integrations) with URL and events; the secret is shown once.

Event	When	Content
`stage_score.approved`	after every competitor-approved score accepted by the portal	match, stage, competitor (incl. `externalId`), raw score, calculated stage result, current standings
`match.status_changed`	status changes (e.g. `live` → `finished`)	matchId, externalId, status
`match.results_published`	match set to `finished`	full standings

Headers: X-MakeReady-Event, X-MakeReady-Delivery (unique id, for idempotency) and X-MakeReady-Signature: sha256=<hex HMAC-SHA256(secret, body)>. Failed deliveries are retried up to 8 times with exponential back-off (cron every 5 min). Always verify the signature and deduplicate on X-MakeReady-Delivery.

Publication on the MakeReady website

Independently of the club portal, match.visibility determines who sees the results on MakeReady: public, club (members of the organising club) or private (staff). A club can therefore choose: MakeReady only, its own portal only, or both.