VTee API

Adds an email to a venue's Marketing List from your own form. This is what the signup widget uses behind the scenes. No API key: the list's signup key names the list, and it only works while the venue has Website signups switched on for that list. It answers any origin (CORS *), so you can call it with fetchfrom the venue's site. It sets no cookies.

fetch('https://vteegolf.com/api/embed/signup', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ list: 'LIST_SIGNUP_KEY', email: 'pat@example.com', firstName: 'Pat' }),
}).then(r => r.json());
// → { "ok": true }

An address already on the list also returns { "ok": true }. Errors return { "ok": false, "error": "…" } with a message you can show the visitor: 400 invalid email, 404 unknown list or signups switched off, 429 rate limited (8 signups per visitor per 10 minutes, 300 per list per hour, 1,000 per list per day).

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 }
      ]
    }
  ]
}

With duration (what an AI agent should pass once the customer has said how long they want) the payload collapses to one price per start time:

{
  "isOpen": true,
  "date": "2026-08-30",
  "duration": 60,
  "slots": [
    { "time": "18:00", "timeDisplay": "6:00 PM", "price": 45, "isPeak": true, "isAppointmentOnly": false }
  ]
}

When no start time fits that length, slots is empty and a note names the lengths that do fit. 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.

Every bay right now, in one call: whether its SimLock kiosk is online, whether the bay is locked or in a session (and how the session was opened, when it ends, which simulator is running), the booking in progress and the next one, and any open Live Assistance request. Built for an operations dashboard or a remote concierge desk — poll it every 15–60 seconds. It is the live picture; history and future bookings stay on /reservations/calendar.

curl https://vteegolf.com/api/v1/bays/status \
  -H "Authorization: Bearer vtk_your_api_key"

{
  "generatedAt": "2026-09-23T19:00:00.000Z",
  "count": 2,
  "bays": [
    {
      "id": 3,
      "name": "Bay 3",
      "position": 3,
      "type": "GOLF_SIM",
      "locationId": 1,
      "kiosk": { "deviceCount": 1, "online": true, "lastSeenAt": "2026-09-23T18:59:12.000Z", "appVersion": "6.2.0", "screensOff": false },
      "session": { "state": "unlocked", "source": "RESERVATION", "endsAt": "2026-09-23T19:30:00.000Z", "reservationId": 18412, "activeSim": "GSPro" },
      "currentReservation": { "id": 18412, "type": "SIMULATOR", "startsAt": "2026-09-23T18:30:00.000Z", "endsAt": "2026-09-23T19:30:00.000Z", "customerName": "Jordan Smith" },
      "nextReservation": { "id": 18420, "type": "SIMULATOR", "startsAt": "2026-09-23T20:00:00.000Z", "endsAt": "2026-09-23T21:00:00.000Z", "customerName": "Ana" },
      "helpRequestedAt": null
    },
    {
      "id": 9,
      "name": "Ocean Bay",
      "position": 1,
      "type": "GOLF_SIM",
      "locationId": 2,
      "kiosk": null,
      "session": null,
      "currentReservation": null,
      "nextReservation": null,
      "helpRequestedAt": null
    }
  ]
}

• kiosk and session are null on a bay with no SimLock device — there is nothing to report a session from. online means the kiosk checked in within the last five minutes.
• session.source is how the bay was opened: RESERVATION, EVENT, ACCESS_CODE, MASTER_CUSTOMER or MASTER_ADMIN (staff codes), MASTER on older sessions, or null for a staff unlock with no recorded mode. A booking-backed session follows the booking if it is extended.
• currentReservation and nextReservation cover confirmed bookings and holds (ACTIVE, HOLD) — what the bay will actually unlock for. A checkout still paying (PENDING_PAYMENT) shows on the calendar feed but not here. nextReservation looks as far as tomorrow.
• helpRequestedAtis set while a guest's Live Assistance request is open on the bay. It clears when staff act on it (Clear, End Session, the master code) or the guest takes it back; a session ending on its own leaves it standing so a late request still reaches someone.
• All times are UTC ISO 8601; convert to the venue's zone for display.

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 email; callers with no email on file get a confirmation SMS with a link to pay or manage the booking instead. 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
    }
  ]
}