Create matches in Yardages
from your own application.

Overview

The Yardages API lets third-party applications create matches with pre-filled player information. Users are then redirected to Yardages to complete setup (handicaps and course selection) before entering scores.

Authentication

All API requests require a valid API key. Include it in the request header using either format below.

Create match endpoint

{
  "players": ["Alice Johnson", "Bob Smith"],
  "courseName": "St Andrews Old Course",
  "date": "2026-12-25"
}

{
  "setupUrl": "https://play.yardages.app/setup-match/abc12345",
  "editUrl": "https://play.yardages.app/match/abc12345",
  "viewUrl": "https://play.yardages.app/match/view/xyz67890",
  "editId": "abc12345"
}

{
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked.",
  "statusCode": 401
}

{
  "error": "Invalid player count",
  "message": "Must provide 2-4 player names",
  "statusCode": 400
}

{
  "error": "Database error",
  "message": "Failed to create match. Please try again.",
  "statusCode": 500
}

Code examples

curl -X POST https://play.yardages.app/api/create-match \
  -H "Content-Type: application/json" \
  -H "X-API-Key: yar_your_api_key_here" \
  -d '{
    "players": ["Alice Johnson", "Bob Smith"],
    "courseName": "Pebble Beach",
    "date": "2026-12-25"
  }'

const response = await fetch('https://play.yardages.app/api/create-match', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'yar_your_api_key_here'
  },
  body: JSON.stringify({
    players: ['Alice Johnson', 'Bob Smith'],
    courseName: 'Pebble Beach',
    date: '2026-12-25'
  })
});

const data = await response.json();

if (response.ok) {
  window.location.href = data.setupUrl;
} else {
  console.error('Error:', data.message);
}

Integration flow

1. 1

   Call the endpoint

   Send a POST request with player names, course hint, and match date.

2. 2

   Receive URLs

   Response includes setupUrl, editUrl, viewUrl, and editId.

3. 3

   Redirect the user

   Send them to setupUrl to complete handicaps and course selection.

4. 4

   User completes setup

   The user fills in handicaps and tees, then lands on the match edit page.

5. 5

   Track the match

   Store editId, editUrl, and viewUrl in your system for future reference.

Best practices

• Validate player names. Trim whitespace and reject empty strings before sending.
• Use ISO date format. Always format dates as YYYY-MM-DD.
• Pre-populate course hints. Pass the most likely course in courseName to speed up user setup.
• Handle errors gracefully. Check HTTP status codes and show user-friendly messages.
• Store returned URLs. Save editId, editUrl, and viewUrl against your match record for future access.