Booking API

The Booking API lets your backend read and manage the bookings a contact has made on an OmniLab campaign — for example to power an account page that shows a customer's upcoming bookings and lets them cancel.

All endpoints are server-to-server: request an access token on your own backend, then call OmniLab with a bearer token. Never expose the client secret in a browser, kiosk page, or mobile app bundle.

Base URLs and environments

Every call uses the /v1/ base path on a tenant-specific host. The host follows this pattern, where <tenant> is your tenant key and <env> is the environment:

Keep staging and production credentials separate, and build and test against staging first. See Base URLs and environments for the wider rules.

Authenticate

Get a token with the client-credentials flow, then send it as Authorization: Bearer <token> on every Booking API call.

curl -X POST "https://<api-host>/v1/oauth:token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "YOUR_AUDIENCE",
    "grant_type": "client_credentials"
  }'

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600
}

Treat expires_in as the token lifetime in seconds: cache the token on your backend and refresh it before it expires, or after a 401 response. The full token guidance lives in Authentication.

Key concepts

Before the endpoint reference, three ideas explain how identifiers fit together.

How a contact is identified

In short: the external ID identifies the person, and the public key identifies the campaign. You only ever need to store the external ID you already have.

Campaigns, touchpoints, and the activity ID

A campaign in OmniLab is an interaction, identified by its public_key. An interaction can contain one or more bookable activities — also called touchpoints. Each booking in the response carries an activity object with its own id. That activity.id is the touchpoint identifier, and it is the key to telling bookings apart when a campaign has more than one bookable activity.

activity.id is unique within a campaign, not across campaigns — the same id can appear under two different campaigns. To identify a touchpoint uniquely, use activity.id together with the campaign's interaction.public_key. The two use cases below show this in practice.

The booking identifier and statuses

Each booking is identified by the booking field — a unique identifier (a UUID). Pass that exact value back to cancel the booking; don't add a prefix or transform it.

Endpoints

List a contact's bookings

GET /v1/interactions:fetchContactBookings

Returns every booking for one contact, with pagination and optional filters.

Query parameters

curl -X GET "https://<api-host>/v1/interactions:fetchContactBookings?external_id=9b33d8c1-64bd-4eff-b0e4-d2fb29ecbe83&booking_status=CONFIRMED&page_size=50&page_number=1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

Each booking in bookings contains the fields below. See Field formats and conventions for the exact format of each.

{
  "bookings": [
    {
      "activity": {
        "id": "b8b2a0e2-1f3c-4a7d-9c52-0c8f2d1a6e44",
        "title": "Santa Photo Experience",
        "location_hint": "Level 1, near the fountain"
      },
      "interaction": {
        "public_key": "winter-festival",
        "timezone": "Europe/London"
      },
      "group": {
        "unique_key": "example-brand",
        "display_name": "Example Brand"
      },
      "slot_starting_at": "2024-12-10T12:30:00Z",
      "slot_duration_in_minutes": 30,
      "booking_status": "CONFIRMED",
      "booked_at": "2024-12-01T09:15:00Z",
      "ticket_type": {
        "display_name": "Standard entry",
        "has_limited_capacity": true
      },
      "host": {
        "display_name": "Photo Station 2"
      },
      "booking": "2394d604-afcc-4f7f-98c1-ef3676c20d6b"
    }
  ],
  "page_number": 1,
  "page_size": 50,
  "total_count": 1
}

Field formats and conventions

Pass the slot_date_range.from and slot_date_range.to filters as RFC 3339 in UTC as well.

Cancel a booking

POST /v1/interactions:cancelInteractionBooking

Cancels one booking and its tickets. Pass the booking value returned by the fetch call, exactly as received.

curl -X POST "https://<api-host>/v1/interactions:cancelInteractionBooking" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "booking": "82ce03a0-939e-423f-811d-0345eacdc137"
  }'

A successful cancellation returns an empty JSON object ({}).

Use cases

Campaign with a single activity touchpoint

When a campaign has only one bookable activity, every booking in the response shares the same activity.id. You can list the bookings directly without grouping — each row is simply one slot the contact booked for that activity.

Campaign with multiple activity touchpoints

When a campaign offers several bookable activities (for example a Santa photo and a craft workshop in the same winter campaign), each booking carries the activity.id of the touchpoint it belongs to. Use activity.id to group or label bookings by activity, so the customer sees "Santa Photo Experience" and "Craft Workshop" as separate lines rather than a flat list. The activity.title gives you a ready-made label for each group.

Display bookings on an account page

A typical account-page flow:

Postman collections

OmniLab maintains a Postman collection per environment (Development, Staging/UAT, and Production) covering all of the endpoints above. Request the collection for your environment from your Customer Success Manager.

Good practices

• Run the token exchange on your backend and call the Booking API server-to-server.
• Cache the access token and refresh it before expires_in elapses or after a 401.
• Send date filters (slot_date_range.from / slot_date_range.to) in UTC.
• Display slot times in interaction.timezone, which is an IANA timezone name.
• Confirm with the customer before cancelling, and refresh the list afterwards.
• Handle an empty bookings array gracefully — a contact may have no bookings.

Related