Players API

Manage player profiles, buddies, and preferences.

Endpoints

Method	Endpoint	Description
GET	/players/me	Get current player
PUT	/players/me	Update player profile
GET	/players/me/buddies	List buddies
POST	/players/me/buddies	Add buddy
DELETE	/players/me/buddies/{id}	Remove buddy
GET	/players/me/favorites	List favorite courses
GET	/players/me/preferences	Get preferences
PUT	/players/me/preferences	Update preferences

Get Current Player

Request

GET /players/me
Authorization: Bearer YOUR_TOKEN

Response

{
  "data": {
    "id": "pl_123",
    "firstName": "John",
    "lastName": "Smith",
    "email": "john@example.com",
    "phone": "+27821234567",
    "handicap": {
      "index": 12.4,
      "lastUpdated": "2025-01-10"
    },
    "memberships": [
      {
        "clubId": "royal-gc",
        "clubName": "Royal Golf Club",
        "type": "FULL",
        "status": "ACTIVE"
      }
    ],
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

Update Profile

Request

PUT /players/me
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "firstName": "John",
  "lastName": "Smith",
  "phone": "+27821234567"
}

Buddies

List Buddies

GET /players/me/buddies
Authorization: Bearer YOUR_TOKEN

Response:

{
  "data": [
    {
      "id": "bd_456",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane@example.com",
      "phone": "+27829876543",
      "status": "CONNECTED"
    }
  ]
}

Add Buddy

POST /players/me/buddies
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "email": "friend@example.com",
  "firstName": "Bob",
  "lastName": "Wilson"
}

Response:

{
  "data": {
    "id": "bd_789",
    "status": "PENDING",
    "inviteSentAt": "2025-01-15T12:00:00Z"
  }
}

Remove Buddy

DELETE /players/me/buddies/bd_456
Authorization: Bearer YOUR_TOKEN

Buddy Groups

Generate playing groups:

GET /players/me/buddies/groups?size=4&pad=0
Authorization: Bearer YOUR_TOKEN

Response:

{
  "data": {
    "groups": [
      {
        "players": ["John Smith", "Jane Doe", "Bob Wilson", "Alice Brown"]
      }
    ],
    "incomplete": []
  }
}

Favorites

List Favorites

GET /players/me/favorites
Authorization: Bearer YOUR_TOKEN

Response:

{
  "data": [
    {
      "courseId": "championship-course",
      "courseName": "Championship Course",
      "clubName": "Royal Golf Club",
      "addedAt": "2025-01-10T09:00:00Z"
    }
  ]
}

Add Favorite

POST /players/me/favorites
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "courseId": "championship-course"
}

Remove Favorite

DELETE /players/me/favorites/championship-course
Authorization: Bearer YOUR_TOKEN

Preferences

Get Preferences

GET /players/me/preferences
Authorization: Bearer YOUR_TOKEN

Response:

{
  "data": {
    "preferredSession": "MORNING",
    "walkingOption": "WALKING",
    "preferredDays": ["SATURDAY", "SUNDAY"],
    "earliestTime": "06:00",
    "latestTime": "10:00",
    "players": 4,
    "notifications": {
      "email": true,
      "sms": true,
      "push": true
    }
  }
}

Update Preferences

PUT /players/me/preferences
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "preferredSession": "MORNING",
  "walkingOption": "CART",
  "preferredDays": ["SATURDAY"],
  "players": 4
}

Set Watch Preference

Create a one-time alert watch:

POST /players/me/preferences/watch?save=false
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "courseId": "championship-course",
  "date": "2025-01-15",
  "preferredSession": "MORNING"
}

Player Status

Status	Description
ACTIVE	Normal account
PENDING	Awaiting verification
SUSPENDED	Temporarily blocked
INACTIVE	No recent activity

Buddy Status

Status	Description
PENDING	Invitation sent
CONNECTED	Both confirmed
DECLINED	Invitation declined
BLOCKED	Connection blocked

Error Codes

Code	Description
PLAYER_NOT_FOUND	Player ID not found
BUDDY_EXISTS	Already buddies
INVITE_PENDING	Invitation already sent
INVALID_EMAIL	Email format invalid