VTee API

Name, address, phone, timezone, weekly hours, today's effective hours (including holiday overrides), bay count, and booking configuration for the business your key belongs to. Call it once at startup to learn the timezone and booking rules.

{
  "name": "Iron Tee Golf",
  "address": "123 Fairway Dr, Austin, TX, 78701",
  "phone": "+15125550142",
  "timezone": "America/Chicago",
  "todayHours": { "date": "2026-08-26", "isOpen": true, "openTime": "09:00", "closeTime": "22:00" },
  "hours": [
    { "day": "monday", "isOpen": true, "openTime": "09:00", "closeTime": "22:00", "appointmentOnly": false },
    { "day": "tuesday", "isOpen": false }
  ],
  "bayCount": 6,
  "durationConfig": { "minDuration": 30, "maxDuration": 240, "interval": 30, "advanceBookingDays": 10 }
}

Open time slots for one day: which bays are free at each slot, which durations fit, and what each duration costs. This is what an agent should call before booking. Dates beyond the business's advance-booking window return 400 with the furthest bookable date.

{
  "isOpen": true,
  "timeSlots": [
    {
      "time": "18:00",
      "timeDisplay": "6:00 PM",
      "isPeak": true,
      "isAppointmentOnly": false,
      "availableBays": [{ "bayId": 3, "name": "Bay 3", "type": "GOLF_SIM" }],
      "durationOptions": [
        { "minutes": 60, "label": "1 hour", "price": 45 },
        { "minutes": 90, "label": "1.5 hours", "price": 67.5 }
      ]
    }
  ]
}

A closed day returns { "isOpen": false, "timeSlots": [] } — with "appointmentOnly": true when the day is bookable only by contacting the business.

Every booking in a date range — the feed for calendar views, dashboards, and home-automation panels. Returns each reservation with its bay, times, status, and customer. Ranges are capped at 31 days per call; page by month for longer horizons. Cross-midnight bookings that spill into the range are included.

curl "https://vteegolf.com/api/v1/reservations/calendar?startDate=2026-08-01&endDate=2026-08-31" \
  -H "Authorization: Bearer vtk_your_api_key"

{
  "startDate": "2026-08-01",
  "endDate": "2026-08-31",
  "count": 2,
  "reservations": [
    {
      "id": 18412,
      "date": "2026-08-14",
      "endDate": "2026-08-14",
      "startTime": "18:00",
      "endTime": "19:30",
      "durationMinutes": 90,
      "status": "ACTIVE",
      "type": "SIMULATOR",
      "price": 67.5,
      "bay": { "id": 3, "name": "Bay 3", "type": "GOLF_SIM" },
      "locationId": null,
      "guestCount": 0,
      "customer": { "name": "Jordan Smith", "phone": "5125550199", "isGuest": false },
      "product": { "id": 12, "name": "Sim Rental" },
      "groupId": null,
      "eventId": null,
      "createdAt": "2026-08-02T16:21:09.000Z"
    },
    {
      "id": 18475,
      "date": "2026-08-20",
      "endDate": "2026-08-20",
      "startTime": "09:00",
      "endTime": "12:00",
      "durationMinutes": 180,
      "status": "ACTIVE",
      "type": "ADMIN_BLOCK",
      "price": 0,
      "bay": { "id": 1, "name": "Bay 1", "type": "GOLF_SIM" },
      "locationId": null,
      "guestCount": 0,
      "customer": null,
      "product": { "id": 12, "name": "Sim Rental" },
      "groupId": null,
      "eventId": 91,
      "createdAt": "2026-08-10T11:00:00.000Z"
    }
  ]
}

• customer is null for admin blocks; isGuest distinguishes walk-in guest bookings from account holders. Customer emails are never included in the calendar feed.
• endDate differs from date only when a booking crosses midnight; endTime is wall-clock and wraps accordingly.
• Multi-bay group bookings share a groupId.
• Responses over 5,000 rows set "truncated": true — narrow the range if you ever see it.

A customer's reservations, matched by phone number (with or without country code). This is how a call agent answers "when is my booking again?". The POST twin takes { "phone": "..." } in the body.

{
  "reservations": [
    {
      "id": 18412,
      "date": "2026-08-14",
      "startTime": "18:00",
      "duration": 90,
      "bayName": "Bay 3",
      "price": 67.5,
      "status": "ACTIVE",
      "user": { "id": 512, "firstName": "Jordan", "lastName": "Smith" }
    }
  ]
}

Books a bay. If the phone number matches an existing customer the booking lands on their account (names optional); unknown callers must include first and last name and are booked as guests. Omit bayId to let VTee pick the optimal bay. The customer gets a confirmation SMS with a link to pay or manage the booking; payment is otherwise collected in store.

curl -X POST https://vteegolf.com/api/v1/reservations \
  -H "Authorization: Bearer vtk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-08-30",
    "startTime": "18:00",
    "duration": 90,
    "guestPhone": "512-555-0199",
    "guestFirstName": "Jordan",
    "guestLastName": "Smith"
  }'

HTTP/1.1 201 Created

{
  "reservation": {
    "id": 18412,
    "date": "2026-08-30",
    "startTime": "18:00",
    "duration": 90,
    "bayName": "Bay 3",
    "price": 67.5,
    "status": "ACTIVE"
  }
}

Conflicts (the slot was just taken, no bay fits, the time is appointment-only) return 409 with a human-readable error an agent can relay verbatim. Dates past the advance-booking window return 400 with the furthest bookable date.

Reschedules a reservation — date, start time, duration, and/or bay. Only the fields you send change; price recalculates automatically when the duration changes. The POST twin takes reservationId in the body instead of the URL.

Returns the updated reservation summary, or 409 when the new slot conflicts.

Cancels a reservation belonging to your business. Canceling an already-canceled reservation is a no-op that returns { "success": true, "alreadyCanceled": true }.

curl -X DELETE https://vteegolf.com/api/v1/reservations/18412 \
  -H "Authorization: Bearer vtk_your_api_key"

{ "success": true }

Checks whether a phone number belongs to a known customer — lets an agent greet a regular by name without re-asking for details. Body: { "phone": "512-555-0199" }.

{ "found": true, "firstName": "Jordan", "lastName": "Smith" }

// or
{ "found": false }

/memberships?phone=returns a customer's memberships with plan, status, and minute usage — { "customer": null, "memberships": [] } when the phone matches nobody. /memberships/planslists the plans the business offers (name, pricing cadence, signup URL where self-serve signup is enabled), for answering "what memberships do you have?".

{
  "customer": { "id": 512, "firstName": "Jordan", "lastName": "Smith", "email": "jordan@example.com", "phone": "5125550199" },
  "memberships": [
    {
      "id": 88,
      "status": "ACTIVE",
      "plan": { "id": 4, "name": "Gold", "type": "UNLIMITED", "monthlyPrice": 199 },
      "minutesUsed": 340,
      "minutesAllowed": 1200,
      "startDate": "2026-01-05",
      "billingDate": 5
    }
  ]
}