Skip to navigation

Quickstart

View as Markdown

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:

Authorization: Bearer $TRUTEE_ACCESS_TOKEN
Trutee-Version: 2026-07-29

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.

Trutee-Organization: $TRUTEE_ORGANIZATION

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.

RequestConstraint
Availability datesOne through 7 inclusive course-local dates in YYYY-MM-DD format
Availability coursesAt most 10 repeated course_id values
Party sizeInteger from 1 through 5; never more than the course’s max_players_per_tee_time (4 by default, 5 when enabled)
Geographic searchLatitude −90 through 90, longitude −180 through 180, and radius greater than 0 through 100 miles; provide all three together
Local-time filters24-hour HH:mm; local_time_end cannot precede local_time_start
Availability page sizeInteger from 1 through 100; default 50
Reservation1–12 allocations, 1–5 golfers per allocation (up to the course’s players per tee time), at most 50 golfers total, and a 64 KiB encoded JSON body
Guest identityFirst and last names are 1–100 characters after trimming; provide an email up to 320 characters or a phone up to 40 characters containing at least 7 digits
External Reference IDexternal_reference_id is optional, scoped to the Integration Organization, may be shared by multiple Reservations, and contains 1–255 characters after trimming
Reservation listPage size 1–50; play-date range at most 366 days
CancellationOptional non-empty reason up to 500 characters after trimming; encoded JSON body at most 8 KiB

1. List courses

const response = await fetch("https://api.trutee.app/courses", {
headers: {
Authorization: `Bearer ${process.env.TRUTEE_ACCESS_TOKEN}`,
"Trutee-Version": "2026-07-29",
},
});
if (!response.ok) throw new Error(`Course discovery failed (${response.status})`);
const courses = await response.json();
Course discovery response
{
"data": [
{
"id": "crs_example_encrypted",
"name": "Pine Ridge Golf Club",
"slug": "pine-ridge",
"description": "A mountain course with public and expanded inventory.",
"holes": 18,
"par": 72,
"yardage": 6842,
"course_rating": 71.8,
"slope_rating": 129,
"booking_enabled": true,
"timezone": "America/Denver",
"address": {
"line_1": "100 Fairway Drive",
"line_2": null,
"city": "Golden",
"state": "CO",
"postal_code": "80401",
"country": "US",
"latitude": 39.7555,
"longitude": -105.2211
},
"contact": {
"phone": "+13035550100",
"email": "golf@pineridge.example",
"website": "https://pineridge.example"
},
"media": {
"image_url": "https://cdn.example/pine-ridge.jpg",
"logo_url": null
},
"amenities": {
"driving_range": true,
"putting_green": true,
"lessons": true,
"carts": true,
"walking": true,
"rental_clubs": true
},
"created_at": "2026-01-15T18:00:00.000Z",
"updated_at": "2026-07-28T16:30:00.000Z",
"effective_access_tier": "expanded",
"availability_policy": {
"access_tier": "expanded",
"booking_days_in_advance": 120,
"tee_times_release_time_local": "07:00",
"max_players_per_tee_time": 4
}
}
],
"meta": {
"request_id": "req_course_example"
}
}

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.

const url = new URL("https://api.trutee.app/availability");
url.search = new URLSearchParams({
course_id: "crs_example_encrypted",
start_date: "2026-08-15",
end_date: "2026-08-15",
party_size: "2",
holes: "18",
cart: "riding",
}).toString();
const response = await fetch(url, {
headers: {
Authorization: `Bearer ${process.env.TRUTEE_ACCESS_TOKEN}`,
"Trutee-Version": "2026-07-29",
},
});
if (!response.ok) throw new Error(`Availability search failed (${response.status})`);
const availability = await response.json();
Availability response
{
"data": [
{
"course_id": "crs_example_encrypted",
"tee_time_id": "ttm_example_encrypted",
"offer_id": "off_example_encrypted",
"offer_expires_at": "2026-07-29T14:05:00.000Z",
"available_spots": 4,
"max_players": 4,
"access_tier": "expanded",
"time": {
"starts_at": "2026-08-15T14:10:00.000Z",
"local_date": "2026-08-15",
"local_time": "08:10",
"timezone": "America/Denver"
},
"pricing": {
"green_fee": { "amount_minor": 8500, "currency": "USD" },
"cart_fee": { "amount_minor": 1800, "currency": "USD" },
"total_per_golfer": { "amount_minor": 10300, "currency": "USD" }
},
"requirements": {
"holes": 18,
"cart": "riding",
"cart_requirement": "optional",
"cart_policy": "not_included",
"booking_policy_fingerprint": "policy_2026_07"
},
"cancellation": {
"window_hours": 24,
"fee": { "amount_minor": 2500, "currency": "USD" }
}
}
],
"meta": {
"request_id": "req_availability_example",
"has_more": false,
"next_cursor": null,
"limits": {
"max_courses": 10,
"max_local_dates": 7,
"max_page_size": 100
},
"read_budget": {
"candidate_courses": 1,
"resolved_courses": 1,
"course_days": 1
}
}
}

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.

const params = new URLSearchParams({
start_date: "2026-08-15",
end_date: "2026-08-15",
party_size: "2",
});
params.append("course_id", "crs_first_encrypted");
params.append("course_id", "crs_second_encrypted");
const response = await fetch(`https://api.trutee.app/availability?${params}`, {
headers: {
Authorization: `Bearer ${process.env.TRUTEE_ACCESS_TOKEN}`,
"Trutee-Version": "2026-07-29",
},
});

Search near a location

Provide latitude, longitude, and radius together. Omit course_id when asking Trutee to resolve nearby accessible courses.

const params = new URLSearchParams({
start_date: "2026-08-15",
end_date: "2026-08-16",
party_size: "4",
latitude: "39.7392",
longitude: "-104.9903",
radius_miles: "25",
});
const response = await fetch(`https://api.trutee.app/availability?${params}`, {
headers: {
Authorization: `Bearer ${process.env.TRUTEE_ACCESS_TOKEN}`,
"Trutee-Version": "2026-07-29",
},
});

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.

Direct booking request
{
"external_reference_id": "external-order-1042",
"guest": {
"first_name": "Avery",
"last_name": "Jordan",
"email": "avery@example.com",
"phone": "+13035550142"
},
"allocations": [
{
"offer_id": "off_example_encrypted",
"quantity": 2,
"players": [{ "first_name": "Morgan", "last_name": "Lee" }]
}
]
}
import { readFile } from "node:fs/promises";
const requestBody = await readFile("direct-booking-request.json", "utf8");
const response = await fetch("https://api.trutee.app/reservations", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TRUTEE_ACCESS_TOKEN}`,
"Trutee-Version": "2026-07-29",
"Idempotency-Key": "booking-external-order-1042",
"Content-Type": "application/json",
},
body: requestBody,
});
if (!response.ok) throw new Error(`Reservation creation failed (${response.status})`);
const reservation = await response.json();
201 Reservation response
{
"data": {
"id": "res_example_encrypted",
"status": "confirmed",
"course_id": "crs_example_encrypted",
"external_reference_id": "external-order-1042",
"guest": {
"first_name": "Avery",
"last_name": "Jordan",
"email": "avery@example.com",
"phone": "+13035550142"
},
"allocations": [
{
"tee_time_id": "ttm_example_encrypted",
"quantity": 2,
"time": {
"starts_at": "2026-08-15T14:10:00.000Z",
"local_date": "2026-08-15",
"local_time": "08:10",
"timezone": "America/Denver"
},
"selections": { "holes": 18, "cart": "riding" },
"pricing": {
"green_fee": { "amount_minor": 8500, "currency": "USD" },
"cart_fee": { "amount_minor": 1800, "currency": "USD" },
"total_per_golfer": { "amount_minor": 10300, "currency": "USD" }
},
"known_companions": [{ "first_name": "Morgan", "last_name": "Lee" }]
}
],
"golfer_count": 2,
"payment": {
"method": "pay_at_course",
"amount_due_now_minor": 0,
"currency": "USD"
},
"cancellation_policy": {
"window_hours": 24,
"fee": { "amount_minor": 2500, "currency": "USD" },
"policy_fingerprint": "policy_2026_07"
},
"cancellation_eligibility": {
"allowed": true,
"code": "allowed",
"message": "This Reservation may be cancelled through the API.",
"contact_course": false
},
"integration_attribution": {
"organization_name": "Example Travel",
"source": "public_api"
},
"created_at": "2026-07-29T14:01:00.000Z",
"updated_at": "2026-07-29T14:01:00.000Z",
"cancelled_at": null,
"messaging": {
"owner": "integration",
"trutee_confirmation_suppressed": true,
"trutee_cancellation_suppressed": true,
"course_name": "Pine Ridge Golf Club",
"guest_name": "Avery Jordan",
"allocations": [
{
"time": {
"starts_at": "2026-08-15T14:10:00.000Z",
"local_date": "2026-08-15",
"local_time": "08:10",
"timezone": "America/Denver"
},
"quantity": 2,
"selections": { "holes": 18, "cart": "riding" }
}
]
}
},
"meta": {
"request_id": "req_reservation_example"
}
}

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:

const response = await fetch(
`https://api.trutee.app/reservations/${process.env.TRUTEE_RESERVATION_ID}`,
{
headers: {
Authorization: `Bearer ${process.env.TRUTEE_ACCESS_TOKEN}`,
"Trutee-Version": "2026-07-29",
},
},
);
if (!response.ok) throw new Error(`Reservation retrieval failed (${response.status})`);
const reservation = await response.json();

For a course-approved test Reservation whose cancellation policy permits API cancellation, clean it up with a new idempotency key:

const response = await fetch(
`https://api.trutee.app/reservations/${process.env.TRUTEE_RESERVATION_ID}/cancellations`,
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TRUTEE_ACCESS_TOKEN}`,
"Trutee-Version": "2026-07-29",
"Idempotency-Key": "cancel-test-external-order-1042",
"Content-Type": "application/json",
},
body: JSON.stringify({ reason: "Integration test cleanup" }),
},
);
if (!response.ok) throw new Error(`Cancellation failed (${response.status})`);
const cancelledReservation = await response.json();

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.