Getting started

Golf Genius API v2

Read a customer's events, rosters, tee sheets, scores, and results from Golf Genius, and keep events in sync with your own system.

Get an API key Explore the API reference

What the API covers

Area What you can do
Customer List seasons, categories, directories, and master roster members.
Events List events, rosters, rounds, divisions, and courses. Create and change events, rounds, divisions, and roster registrations.
Tee sheets and scores Read a round's tee sheet with scores. Create and change pairing groups.
Results Read tournament results as HTML, JSON, or XML, and player and team points, season points, and UK handicapping data.

Get an API key

Contact Golf Genius Support to request an API key. Golf Genius users and third-party providers that serve Golf Genius customers can both request one.

An API key belongs to one customer (a club or association) and gives access to that customer's data. If your integration serves several customers, you receive a key for each one.

Make your first request

Every request goes to https://www.golfgenius.com.

Endpoints that read data take the API key in the path:

curl https://www.golfgenius.com/api_v2/YOUR_API_KEY/seasons

Endpoints that change data take the API key in an Authorization header instead. These are the endpoints that create, update, or delete events, rounds, divisions, roster registrations, and pairing groups: 

curl -X POST https://www.golfgenius.com/api_v2/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Spring League", "event_type": "league"}'

Treat the API key like a password. Read requests carry it in the URL, so keep those requests out of browser code and remove the key from URLs before you log them.

Work with IDs

IDs are 64-bit integers. JavaScript and many JSON parsers cannot hold them exactly: JavaScript reads 7059198245062353848 as 7059198245062354000.

  • Store IDs as strings.
  • Where a response has both an ID and a matching _str field, such as id and id_str or round_id and round_id_str, read the _str field.

The API reference displays its examples through JavaScript, so long numeric IDs in the examples appear rounded. The _str fields beside them show the exact values.

Request more pages

List events and List an event's roster return 100 results per page. Request further pages with the page query parameter. List master roster members also takes page.

Handle errors

When an endpoint that changes data cannot complete a request, it returns HTTP 400 with an errors array: 

{
  "errors": ["Failed to create League using the given parameters."]
}

Formats

  • Dates use YYYY-MM-DD, for example 2020-09-21.
  • Timestamps use YYYY-MM-DD HH:MM:SS ±HHMM, for example 2018-01-26 15:37:40 +0000.
  • Tee times use 12-hour time, for example 8:10 AM.
  • Tournament results are available as HTML, JSON, and XML. Golf Genius recommends HTML, which displays every tournament format correctly without extra work.

Keep events in sync with your system

An integration that keeps Golf Genius events in step with a tee sheet or registration system uses the endpoints in this order:

  1. Create the event with its divisions, rounds (dates), and webhooks. Set external_id on the event and its rounds to link them to your system. Golf Genius then syncs the event roster or the round tee sheets from your system.
  2. Add or change rounds and divisions as your schedule changes.
  3. Register golfers in the event roster and place them in pairing groups on each round's tee sheet, unless Golf Genius syncs them from your system.
  4. Read the tee sheet and scores during the round and the tournament results afterward.

Webhooks

Creating or updating an event accepts a webhooks object. It turns on updates for courses, pairings, players, scores, matches, match_results, and settings, each sent to an endpoint you choose. Golf Genius ignores webhooks unless the Webhook Integration feature is enabled for the customer.