HotelNative API Reference

Authentication

HotelNative uses three distinct authentication mechanisms depending on the caller type.

{
  "POST /api/auth/signin": "Standard NextAuth signin endpoint",
  "cookies": {
    "next-auth.session-token": "Secure httpOnly cookie (auto-managed by NextAuth)"
  }
}

{
  "flow": [
    "POST /api/guest/auth/request → email sent",
    "GET /api/guest/auth/verify?token=XXX → cookie set",
    "All /api/guest/* calls use cookie automatically"
  ]
}

{
  "flow": [
    "POST /api/travel-agents/portal/auth/login → email sent",
    "GET /api/travel-agents/portal/auth/verify?token=XXX → cookie set",
    "All /api/travel-agents/portal/* calls use cookie automatically"
  ]
}

Hotel Native ships with a built-in AI agent layer powered by Claude (claude-sonnet-4-6) with full authenticated access to every PMS domain. Unlike Cloudbeds — which requires third-party integrations like Whistle or Revinate to add AI — Hotel Native has Claude baked in at every layer.

{
  "message": "What time is checkout and can I get late checkout?",
  "bookingId": "uuid"
}

{
  "reply": "Standard checkout is at noon. I can request a 2pm late checkout for you — would you like me to do that?",
  "actions": [
    {
      "type": "service_request",
      "label": "Request late checkout",
      "data": {
        "type": "late_checkout"
      }
    }
  ]
}

{
  "organizationId": "uuid",
  "prompt": "Luxury hotel pool area at sunset with tropical plants",
  "style": "professional photography",
  "enhancePrompt": true,
  "sectionContext": {
    "sectionType": "hero",
    "title": "Welcome to KC Hotel",
    "industry": "hospitality"
  }
}

{
  "success": true,
  "cdnUrl": "https://media.hellonative.ai/tenants/org-uuid/ai-generated-1709832000.webp",
  "url": "https://media.hellonative.ai/tenants/org-uuid/ai-generated-1709832000.webp",
  "prompt": "A photorealistic luxury hotel pool area at golden hour sunset...",
  "model": "gemini-2.0-flash-exp-image-generation"
}

{
  "organizationId": "uuid",
  "imageUrl": "https://media.hellonative.ai/tenants/org/photo.webp",
  "prompt": "Describe this hotel room photo for a website listing",
  "task": "describe"
}

{
  "description": "A spacious junior suite with king-size bed, warm wooden accents, floor-to-ceiling windows overlooking tropical gardens, and a modern en-suite bathroom.",
  "tags": [
    "hotel room",
    "junior suite",
    "king bed",
    "garden view"
  ]
}

Booking Engine

Public-facing endpoints used by the hotel website booking widget. No authentication required — requests are scoped to a hotel by `appFolder`.

Reservations (PMS)

Create, manage, and update hotel reservations from the Property Management System. All endpoints require dashboard authentication.

Rooms & Rates (PMS)

Manage room types, rate plans, pricing, and physical room inventory.

Guests (PMS)

Guest profiles, history, and notes. Guest records are automatically created from bookings and linked across stays.

Custom Fields

Define extra fields to store arbitrary data on reservations or guests. Admins create field definitions (name, type, applies_to) in Settings → Policies → Custom Fields. Values are stored per entity (booking or guest) and can be retrieved or upserted via the API.

Housekeeping

Manage room cleaning status, housekeeping tasks, and daily assignment sheets.

Invoices & Payments

Manage folio charges, invoices, and electronic invoicing (Hacienda — Costa Rica tax authority).

Accounting

Transaction ledger and trial balance API. Combines folio charges and payments into a unified view for accounting exports and end-of-day reporting.

POS & Folio Charges

Post restaurant, spa, minibar, and other point-of-sale charges directly to a guest folio. Supports tax calculation, void/reversal, and fires `accounting/transaction` webhooks on every mutation.

Staff Management

Staff directory, role assignments, shift tracking, and time-clock operations.

Travel Agents (PMS)

Manage travel agent accounts, negotiated rates, commission tracking, and settlement statements.

Allotment Blocks

Pre-allocated inventory held for groups, conferences, and travel agency partners. Separate from maintenance room blocks — allotments are tentative or definite holds that count against availability.

Guest Portal

Self-service portal for in-house guests. Magic link authentication — no password required. Session cookie: `guest_session` (7-day TTL).

Travel Agent Portal

Self-service portal for travel agents to view negotiated rates, submit bookings for approval, and track commissions. Magic link auth — session cookie: `ta_session` (30-day TTL).

Channel Manager

Integrate with OTAs via Channex or RoomCloud. Both providers are supported via a factory pattern controlled by integrations.activeChannelManager in the organization record ("channex" | "roomcloud" | "none"). RoomCloud uses XML over HTTP; Channex uses REST. The pushAvailabilityUpdate() factory function routes to the correct provider automatically.

Digital Check-In

QR-code-based self check-in flow. A unique token is issued per booking; guests complete registration, upload their ID, and sign digitally.

Visitor Analytics

Real-time and historical website visitor tracking for hotel websites. No third-party tools — all data stays in your database.

Service Requests

In-room service requests from guests (via Guest Portal) managed by hotel staff.

Door Locks

Provider-agnostic digital key management. Tracks key lifecycle (issue, cancel, expire) for mobile keys and keycards. Integrate any lock provider (Dormakaba, ASSA ABLOY, Salto, VingCard) by listening to the `doorLockKey/key_requested` outbound webhook and writing back `externalKeyId` via PATCH.

Groups

Manage group bookings: corporate events, weddings, tour operators. A group has a header record, client roster, reservations, and notes.

Floor Plan

Manage the physical layout of the property — buildings, floors, and per-room positions used by the visual floor-plan view.

Hotel Settings

Property configuration including check-in/out times, late checkout policies, tax rates, and per-room-type pricing rules.

Webhooks (Inbound)

Inbound webhook receivers for external integrations — payment processors, CRM platforms, and channel managers.

Webhooks (Outbound)

HotelNative fires HTTP POST events to your endpoint when key operations happen in the PMS. Subscribe via PMS → Settings → Webhooks UI or the API below. SIGNATURE VERIFICATION — Every outbound request includes an X-HotelNative-Signature header using HMAC-SHA256 (Stripe-style). The format is: t=<unix_timestamp>,v1=<hmac_hex>. To verify: concatenate the timestamp + "." + raw request body, then HMAC-SHA256 it with your subscription secret. Compare to the v1 value. Reject if |now - t| > 300s to prevent replay attacks. SUPPORTED EVENTS (14 total): Reservations: reservation/created, reservation/updated, reservation/cancelled, reservation/checked_in, reservation/checked_out, reservation/status_changed Payments: payment/received, payment/refunded Guests: guest/created, guest/updated Housekeeping: housekeeping/task_created, housekeeping/task_completed Rates: rate/updated System: webhook/test All events share a common envelope: { id, event, organizationId, timestamp, data }.

Sandbox

Test your integration against a dedicated sandbox organization pre-seeded with demo rooms, bookings, and guests. Sandbox data is isolated from production and can be reset at any time. To get a sandbox account, email hello@hotelnative.ai.

AI-Native Platform

The core differentiator of Hotel Native: every module is connected to AI. Unlike legacy PMS platforms bolted with chatbots, Hotel Native is built AI-first — Claude Sonnet 4.6 powers the concierge, the upsell engine, staff automation, and agentic workflows that act autonomously across reservations, housekeeping, communications, and revenue management.

Self-Check-In Kiosk

Hotel Native includes a full touchscreen self-check-in kiosk at /kiosk. Guests scan a QR code or enter their booking reference, verify identity, optionally upload ID documents, and complete check-in without front desk staff. Supports bilingual EN/ES interface and integrates with door lock providers.

Upsell Engine

Hotel Native's multi-channel upsell engine sends personalized upgrade and add-on offers to guests via email and WhatsApp. Templates are configurable per property and triggered automatically based on check-in timing. All sends are logged with delivery status.

WhatsApp Integration

Hotel Native uses Baileys — a self-hosted WhatsApp Web client — to send and receive WhatsApp messages directly without Meta's Business API fees. The connection is managed server-side via QR code pairing. Inbound messages can trigger AI concierge responses, service requests, and booking lookups.

Email & SMS

Hotel Native sends transactional and marketing emails via SMTP (configurable per property). Automated emails fire for booking confirmation, check-in instructions, upsell offers, invoice delivery, and travel agent communications. SMS is supported via third-party integrations (Twilio, Telnyx) for OTP and guest notifications.

Marketing & Ads

Hotel Native integrates with Google Analytics 4, Meta (Facebook) Pixel, Google Ads conversions, and Google Search Console. Booking events fire automatically as conversions. The visitor analytics module tracks multi-touch attribution so you know which channels are generating reservations.

Blog & Media

Hotel Native ships a markdown-based blog CMS for each property. Blog posts are stored as markdown files and served with full SEO metadata, bilingual support, and structured data. Media (images, documents) is stored on Cloudflare R2 (S3-compatible) via signed upload URLs.

Channex Channel Manager

Hotel Native is a certified Channex channel manager integration. Channex syncs room availability and rates to OTA channels (Booking.com, Expedia, Airbnb, and 400+ others) in real-time via XML APIs. Hotel Native also supports RoomCloud as an alternative channel manager — switchable at runtime without a restart.

Event Catalogue

All events are delivered with this envelope:

{
  "id": "evt_uuid",
  "event": "reservation/created",
  "timestamp": "2026-03-04T15:30:00.000Z",
  "organizationId": "org_uuid",
  "data": {
    "bookingId": "uuid",
    "bookingReference": "HN-20260304-ABCD",
    "...": "..."
  }
}

Errors & Status Codes

All endpoints return JSON. Errors always include an `error` or `message` field.

{
  "ok": false,
  "error": "Room type not found",
  "code": "NOT_FOUND"
}