Getting Started

The Partner Trips API lets your booking suppliers start travelmode trip plans for their travel groups, hand each trip to its organizer, and keep your site's copy of the trip description in sync.

1. Get your organization key

Your organization is registered by the Travelmode team, which issues you an API key with the trips:* scopes. Keys look like tm_trips_... and are shown exactly once — store the plaintext securely.

Every request sends the key as a bearer token:

curl -H "Authorization: Bearer tm_trips_your_key_here" \
  https://api.travelmode.ai/v1/partner/suppliers

2. Register a supplier

Each of your group providers gets a supplier record under your organization. external_id is your own id for them.

curl -X POST https://api.travelmode.ai/v1/partner/suppliers \
  -H "Authorization: Bearer tm_trips_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "sup-4711", "name": "Alpine Group Tours"}'

The response contains supplier_id — use it (or your external_id) when starting trips.

3. Start a trip

curl -X POST https://api.travelmode.ai/v1/partner/trips \
  -H "Authorization: Bearer tm_trips_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dolomites Hiking Week",
    "summary": "7-day guided group hike",
    "supplier_external_id": "sup-4711",
    "external_ref": "booking-2026-0live42",
    "metadata": {"destination": "Dolomites, Italy", "start_date": "2026-09-12", "end_date": "2026-09-19"}
  }'

The 201 response includes two URLs:

• claim.claim_url — send this to the group organizer. Opening it (and signing in) makes the trip theirs, in their own travelmode account.
• planner_url — where the group continues planning in travelmode's UI after the claim.

4. Keep your listing in sync

Read the trip anytime with GET /v1/partner/trips/[tripId], or subscribe to trip.updated webhooks. See Description Sync and Webhooks.