Core Endpoints — Rounds & Mobile App Partners

These integrations cover GPS-based round trackers, mobile scoring apps, and wearable devices that capture on-course shot locations, scores, and club usage during played rounds.

Authentication & Account Linking

POST/oauth/authorize

Initiate the OAuth flow.

POST/oauth/token

Token exchange.

POST/oauth/token/refresh

Silent token refresh.

GET/users/me

Authenticated user profile with a stable user ID.

Data Push (Webhook) — Preferred Path

Register a webhook that notifies AVA of round lifecycle events. This is the preferred integration pattern.

• Required events: round.completed required (round finished and saved), round.edited (user modifies a past round, e.g., corrects a score or moves a shot), round.deleted (user removes a round).
• Should include an HMAC signature header (or equivalent) for payload verification.

Edit & delete events matter

Without round.edited / round.deleted, stale data persists and must be corrected through AVA Golf — or all data must be re-synced via REST endpoints. These events are important for data integrity.

Two payload styles are supported — choose whichever fits your architecture:

1. Full payload: Webhook body contains the complete round with holes and shots.
2. Notification + fetch: Webhook body contains the round ID; AVA Golf retrieves full data via your REST endpoints.

Round Listing & Retrieval

GET/rounds

List completed rounds for the authenticated user.

• Should support date-range filtering (?startDate=&endDate=). Required for production-scale background sync.
• Should support pagination. Required for users with large round histories.
• Response should include: round ID, course name, course ID, round date, total score, and number of holes played.

GET/rounds/{roundId}

Full round detail including hole-by-hole breakdown and all shots.

GET/rounds/{roundId}/holes

Hole-level data for the round.

• Each hole must include: hole number, par, and score at minimum. Putts are strongly recommended.

GET/rounds/{roundId}/shots

All shots in the round, ordered by hole then shot-in-hole sequence.

• Each shot must include a unique shotId.
• Shots must be ordered by hole number then by shot sequence within the hole. Our processing pipeline depends on correct shot ordering.

User Club Bag (if available)

GET/users/me/clubs

Return the user’s configured club bag.

• Each club: club type, brand, model, loft (if known).
• This lets us cross-reference club selections in shot data.