Skip to content

General Platform Conventions

AVA Golf ingests shot-level golf data from multiple sources — launch monitors, simulators, GPS-based round trackers, and mobile scoring apps — and unifies it into a single analytics pipeline that powers strokes-gained analysis, trend tracking, and performance mapping.

This guide defines what we need from your integration so data flows cleanly into that pipeline. Requirements are split into two partner profiles:

  1. Rounds & Mobile App Partners — GPS-enabled apps and wearables that capture on-course round data (shot locations, scoring, club usage).
  2. Launch Monitor & Session Partners — hardware devices and simulator software that produce ball-flight and club-delivery metrics during practice or indoor sessions.

The closer your API output maps to the data schemas described here, the faster we ship your integration.

Before diving into partner-specific requirements, note the conventions that apply to every integration.

We support OAuth 2.0 (preferred) and OAuth 1.0a. Your API must provide a standard authorization flow with refresh-token support so we can re-authenticate silently without re-prompting the user. Every integration needs these endpoints, or functional equivalents:

POST/oauth/authorize

Initiate the OAuth flow; redirect the user to your consent screen.

POST/oauth/token

Exchange authorization code for access + refresh tokens.

POST/oauth/token/refresh

Refresh an expired access token without user interaction.

GET/users/me

Return the authenticated user’s profile. Must include a stable, unique user identifier.

Notify us when a round or session is completed, edited or deleted, and when a user disconnects or changes permissions. Webhooks are the preferred integration path; see Webhooks.

JSON over HTTPS.

We work in meters and meters per second internally. Your API may return imperial or metric — just be explicit about units in your documentation so we can convert correctly (see Unit Conventions).

Every shot and every session/round must carry a stable, unique identifier. Re-syncing the same data should never create duplicates.

ISO 8601 format with timezone offset (e.g., 2026-03-16T14:30:00-07:00). UTC is acceptable, but offset-aware is preferred so we can localize for the user.

For list endpoints returning historical data, implement cursor-based or offset pagination. Required for production-scale backfill of user history.

Document your rate limits and return a standard 429 Too Many Requests with a Retry-After header.

Use conventional HTTP status codes. Error bodies should include a machine-readable code and a human-readable message.

  • The shot identifier is sourceId everywhere. The Core Endpoints pages called it shotId; the Data Schema pages already said sourceId.
  • round.edited and round.deleted are strongly recommended, as session.edited and session.deleted already were. round.completed and session.completed are still required. See Webhooks.
  • The hole’s first-putt distance is firstPuttDistanceMeters, in meters like every other distance. It was firstPuttDistanceFeet.
  • Webhooks and the account-linking endpoints are each described once, for both partner families: Webhooks and Authentication & Account Linking.

Earlier changes weren’t recorded here.