Developers

Developer documentation

Build with Turneo

One API to search, price and book experiences — in-house activities and third-party tours alike — plus embeddable Elements for your hotel website. Connect Turneo to your PMS, guest app, concierge tools or booking site.

Start with the quickstartAPI reference
Your first requestbash
curl "https://api.turneo.co/v2/experiences" \
  -H "X-API-Key: <your-api-key>" \
  -H "Accept: application/json"

Start here

Pick your path

Whether you're integrating the API or just embedding a booking widget, there's a short route to a first booking.

How it fits together

A booking in three calls

Every integration follows the same shape. Each step returns the IDs you need for the next.

Walk through it in the quickstart
  1. 01

    Find experiences

    List or search the experiences available to your guests — by store, destination, date or category.

    • GET /v2/experiences
    Experiences in the reference
  2. 02

    Price and check availability

    Each experience has bookable options. Paint a calendar of available dates, then load the concrete time slots for the party you're booking.

    • GET /v2/experiences/{id}/options
    • GET /v2/experiences/{id}/availability/slots
    Options in the reference
  3. 03

    Book and confirm

    Create a booking order to hold the slots — a shopping cart, held for about an hour — then confirm it to finalise the bookings.

    • POST /v2/booking-orders
    • POST /v2/booking-orders/{id}/confirm
    Orders in the reference

Key concepts

The vocabulary of the API

Eight objects cover almost everything you'll touch. Each links to its section of the reference.

  • Experience

    A tour, activity, event or service a guest can book — title, description, media, location, categories. The top-level object in the catalogue.

    Reference

  • Option

    One bookable configuration of an experience (“Shared boat tour” vs. “Private charter”), with its own schedule, pricing model, variants, add-ons and booking questions.

    Reference

  • Participant type

    The categories a guest books for: Adult, Child and Infant by default, plus custom types such as Senior or Student, enabled per option.

    Reference

  • Availability slot

    A concrete bookable time for an option on a given day, with remaining capacity per variant. Dates first, then slots for the chosen day.

    Reference

  • Booking order

    The cart you check out in one go: traveller details plus one or more bookings. Capacity is held while the order is on hold and finalised on confirm.

    Reference

  • Booking

    One reserved slot for one variant, on behalf of a traveller. Created through orders; then accepted, rescheduled, cancelled or refunded individually.

    Reference

  • Activity feed

    A chronological record of what happened across your account — bookings created, cancelled, rescheduled — for keeping downstream systems in sync.

    Reference

  • Partner account

    Every request is scoped by its X-API-Key to your partner account: your own experiences and bookings, plus experiences shared with you or publicly listed.

    Reference

Essentials

Working with the API

The conventions every endpoint follows, so you only have to learn them once.

Full conventions in the reference
Base URL
https://api.turneo.co — every endpoint lives under /v2/.
Authentication
Send your partner key in the X-API-Key header on every request. Scoping is derived from the key.
Format
JSON in and out, with camelCase keys. Multilingual fields are objects keyed by language code; pass ?language=de to get a single language.
Pagination
List endpoints take page and page_size and return { count, next, previous, results }.
Errors
A standard envelope: { type, errors: [{ code, field, message }] }. A 404 means the resource doesn’t exist or isn’t visible to your account.

Guides

Step-by-step integration guides

Written by the engineers who built the API and reviewed with every change to it.

All guides
  1. 01

    Getting Started with Experiences

    Search, price, and book experiences — a guided walkthrough of the booking flow.

  2. 02

    Multi-language content

    How to request and interpret translated content across the API.

  3. 03

    Adding Turneo Elements to your Hotel Website

    Embed a Turneo Element widget on your website so guests can browse and book experiences directly.

  4. 04

    Enabling Apple Pay on your Elements

    One-time domain verification steps required to accept Apple Pay through a Turneo Element.

  5. 05

    Integrating Turneo into your Mobile App

    Embed a Turneo Element in a WebView or build native screens on the API — and keep the guest's bookings in sync with your app.

API reference

Every endpoint, by resource

Generated from the same OpenAPI document that powers the interactive reference — try requests against production with your own key.

Open the API reference