Quickstart
Before you begin
Request Public API access, then choose a user API key or OAuth. Ask Trutee for a course-approved test Tee Time and cleanup plan before creating your first production Reservation. The bearer credential must represent an approved user; API key requests also identify the organization by its Trutee slug.
Use https://api-sandbox.trutee.app for sandbox requests and https://api.trutee.app for production requests. The examples below use production. The API Reference defaults to Sandbox; select Sandbox or Production from the environment menu before sending a request in the browser.
Every request uses:
When $TRUTEE_ACCESS_TOKEN is a user API key, also send this header on every request. OAuth requests omit it because their organization was selected during consent.
Reservation access is provisioned for an approved Integration Organization. Ordinary organization membership can discover public-access courses and public inventory, but does not automatically grant expanded inventory or Reservation capabilities. Unknown or unapproved roles fail closed.
Common request limits
These are the limits most likely to affect a first integration. The API Reference remains the machine-readable source of truth for every field.
1. List courses
Persist opaque IDs exactly as returned. Never parse or synthesize them.
Each course’s availability_policy.max_players_per_tee_time says how many players its tee times hold: 4 by default, 5 when the course allows fivesomes. Offer party sizes up to that number, and split larger groups across allocations. A tee time created before the course changed this setting keeps its own capacity, so check each result’s max_players.
2. Prepare the booking
Collect and validate the primary guest, known companion names, and your own stable External Reference ID before searching. Send that identifier in external_reference_id. The top-level guest is the primary golfer and consumes one spot in the earliest Tee Time allocation. Each allocation’s optional players array contains companions only—do not repeat the primary guest, and omit unnamed golfers.
3. Search availability
Dates and filters are interpreted in each course’s IANA time zone. A search spans at most 10 courses and 7 local dates.
Each result’s max_players is that tee time’s capacity, and available_spots is how many of those spots are still open. Results only include tee times with at least party_size open spots.
An offer_id is encrypted, principal-bound, policy-bound, and expires at offer_expires_at, five minutes after it is issued. Search only when the user is ready to book. Use the offer immediately and unchanged; if less than 30 seconds remain, search again before showing final confirmation.
Search more than one course
Repeat course_id for each course; do not join IDs with commas. All other filters apply to every selected course.
Search near a location
Provide latitude, longitude, and radius together. Omit course_id when asking Trutee to resolve nearby accessible courses.
When meta.has_more is true, repeat the same search with the same filters and limit, adding the returned meta.next_cursor as cursor. A cursor is valid only for that exact search scope.
4. Create a reservation
Generate a unique Idempotency-Key for the logical booking and persist it with the request body.
Treat a timeout or connection loss after submission as ambiguous. Retry the identical request with the identical key; see Retries and idempotency.
5. Verify the result and own the guest experience
The messaging object is canonical delivery data, not proof that Trutee sent anything. Send the guest’s confirmation and later cancellation message yourself. Save the Reservation ID and External Reference ID (external_reference_id) for retrieve and reconciliation.
Retrieve the saved Reservation before considering the integration test complete:
For a course-approved test Reservation whose cancellation policy permits API cancellation, clean it up with a new idempotency key:
Your first integration is complete when you can create, idempotently replay, retrieve, cancel, and find the Reservation through reconciliation. Do not test cancellation against a real guest booking.

