> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.trutee.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.trutee.app/_mcp/server.

# Quickstart

> Authenticate, discover a course, find availability, and create a Pay at Course Reservation.

## Before you begin

[Request Public API access](mailto:support@trutee.app?subject=Public%20API%20access), then choose a [user API key or OAuth](/home/get-started/authentication-and-organizations). 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:

```bash
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.

```bash
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.

| Request                | Constraint                                                                                                                                                        |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Availability dates     | One through 7 inclusive course-local dates in `YYYY-MM-DD` format                                                                                                 |
| Availability courses   | At most 10 repeated `course_id` values                                                                                                                            |
| Party size             | Integer from 1 through 5; never more than the course's `max_players_per_tee_time` (4 by default, 5 when enabled)                                                  |
| Geographic search      | Latitude −90 through 90, longitude −180 through 180, and radius greater than 0 through 100 miles; provide all three together                                      |
| Local-time filters     | 24-hour `HH:mm`; `local_time_end` cannot precede `local_time_start`                                                                                               |
| Availability page size | Integer from 1 through 100; default 50                                                                                                                            |
| Reservation            | 1–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 identity         | First 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 ID  | `external_reference_id` is optional, scoped to the Integration Organization, may be shared by multiple Reservations, and contains 1–255 characters after trimming |
| Reservation list       | Page size 1–50; play-date range at most 366 days                                                                                                                  |
| Cancellation           | Optional non-empty reason up to 500 characters after trimming; encoded JSON body at most 8 KiB                                                                    |

## 1. List courses

**`TypeScript`**

```typescript title="TypeScript"
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();
```

**`Python`**

```python title="Python"
import os
import requests

response = requests.get(
    "https://api.trutee.app/courses",
    headers={
        "Authorization": f"Bearer {os.environ['TRUTEE_ACCESS_TOKEN']}",
        "Trutee-Version": "2026-07-29",
    },
    timeout=30,
)
response.raise_for_status()
courses = response.json()
```

**`cURL`**

```curl title="cURL"
curl https://api.trutee.app/courses \
  -H "Authorization: Bearer $TRUTEE_ACCESS_TOKEN" \
  -H "Trutee-Version: 2026-07-29"
```

```json title={"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.

**`TypeScript`**

```typescript title="TypeScript"
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();
```

**`Python`**

```python title="Python"
import os
import requests

response = requests.get(
    "https://api.trutee.app/availability",
    params={
        "course_id": "crs_example_encrypted",
        "start_date": "2026-08-15",
        "end_date": "2026-08-15",
        "party_size": 2,
        "holes": 18,
        "cart": "riding",
    },
    headers={
        "Authorization": f"Bearer {os.environ['TRUTEE_ACCESS_TOKEN']}",
        "Trutee-Version": "2026-07-29",
    },
    timeout=30,
)
response.raise_for_status()
availability = response.json()
```

**`cURL`**

```curl title="cURL"
curl "https://api.trutee.app/availability?course_id=crs_example_encrypted&start_date=2026-08-15&end_date=2026-08-15&party_size=2&holes=18&cart=riding" \
  -H "Authorization: Bearer $TRUTEE_ACCESS_TOKEN" \
  -H "Trutee-Version: 2026-07-29"
```

```json title={"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.

**`TypeScript`**

```typescript title="TypeScript"
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",
  },
});
```

**`Python`**

```python title="Python"
response = requests.get(
    "https://api.trutee.app/availability",
    params=[
        ("start_date", "2026-08-15"),
        ("end_date", "2026-08-15"),
        ("party_size", 2),
        ("course_id", "crs_first_encrypted"),
        ("course_id", "crs_second_encrypted"),
    ],
    headers={
        "Authorization": f"Bearer {os.environ['TRUTEE_ACCESS_TOKEN']}",
        "Trutee-Version": "2026-07-29",
    },
    timeout=30,
)
```

**`cURL`**

```curl title="cURL"
curl "https://api.trutee.app/availability?start_date=2026-08-15&end_date=2026-08-15&party_size=2&course_id=crs_first_encrypted&course_id=crs_second_encrypted" \
  -H "Authorization: Bearer $TRUTEE_ACCESS_TOKEN" \
  -H "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.

**`TypeScript`**

```typescript title="TypeScript"
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",
  },
});
```

**`Python`**

```python title="Python"
response = requests.get(
    "https://api.trutee.app/availability",
    params={
        "start_date": "2026-08-15",
        "end_date": "2026-08-16",
        "party_size": 4,
        "latitude": 39.7392,
        "longitude": -104.9903,
        "radius_miles": 25,
    },
    headers={
        "Authorization": f"Bearer {os.environ['TRUTEE_ACCESS_TOKEN']}",
        "Trutee-Version": "2026-07-29",
    },
    timeout=30,
)
```

**`cURL`**

```curl title="cURL"
curl "https://api.trutee.app/availability?start_date=2026-08-15&end_date=2026-08-16&party_size=4&latitude=39.7392&longitude=-104.9903&radius_miles=25" \
  -H "Authorization: Bearer $TRUTEE_ACCESS_TOKEN" \
  -H "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.

```json title={"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" }]
    }
  ]
}

```

**`TypeScript`**

```typescript title="TypeScript"
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();
```

**`Python`**

```python title="Python"
import json
import os
import requests

with open("direct-booking-request.json", encoding="utf-8") as request_file:
    request_body = json.load(request_file)

response = requests.post(
    "https://api.trutee.app/reservations",
    headers={
        "Authorization": f"Bearer {os.environ['TRUTEE_ACCESS_TOKEN']}",
        "Trutee-Version": "2026-07-29",
        "Idempotency-Key": "booking-external-order-1042",
    },
    json=request_body,
    timeout=30,
)
response.raise_for_status()
reservation = response.json()
```

**`cURL`**

```curl title="cURL"
curl -X POST https://api.trutee.app/reservations \
  -H "Authorization: Bearer $TRUTEE_ACCESS_TOKEN" \
  -H "Trutee-Version: 2026-07-29" \
  -H "Idempotency-Key: booking-external-order-1042" \
  -H "Content-Type: application/json" \
  --data @direct-booking-request.json
```

```json title={"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](/home/build/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:

**`TypeScript`**

```typescript title="TypeScript"
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();
```

**`Python`**

```python title="Python"
import os
import requests

reservation_id = os.environ["TRUTEE_RESERVATION_ID"]
response = requests.get(
    f"https://api.trutee.app/reservations/{reservation_id}",
    headers={
        "Authorization": f"Bearer {os.environ['TRUTEE_ACCESS_TOKEN']}",
        "Trutee-Version": "2026-07-29",
    },
    timeout=30,
)
response.raise_for_status()
reservation = response.json()
```

**`cURL`**

```curl title="cURL"
curl "https://api.trutee.app/reservations/$TRUTEE_RESERVATION_ID" \
  -H "Authorization: Bearer $TRUTEE_ACCESS_TOKEN" \
  -H "Trutee-Version: 2026-07-29"
```

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

**`TypeScript`**

```typescript title="TypeScript"
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();
```

**`Python`**

```python title="Python"
import os
import requests

reservation_id = os.environ["TRUTEE_RESERVATION_ID"]
response = requests.post(
    f"https://api.trutee.app/reservations/{reservation_id}/cancellations",
    headers={
        "Authorization": f"Bearer {os.environ['TRUTEE_ACCESS_TOKEN']}",
        "Trutee-Version": "2026-07-29",
        "Idempotency-Key": "cancel-test-external-order-1042",
    },
    json={"reason": "Integration test cleanup"},
    timeout=30,
)
response.raise_for_status()
cancelled_reservation = response.json()
```

**`cURL`**

```curl title="cURL"
curl -X POST "https://api.trutee.app/reservations/$TRUTEE_RESERVATION_ID/cancellations" \
  -H "Authorization: Bearer $TRUTEE_ACCESS_TOKEN" \
  -H "Trutee-Version: 2026-07-29" \
  -H "Idempotency-Key: cancel-test-external-order-1042" \
  -H "Content-Type: application/json" \
  --data '{"reason":"Integration test cleanup"}'
```

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.