Innkeeper

Docs › Integrating with a Website

Integrating with a Website

Last updated on July 25, 2026

There are two ways to send a booking request into Innkeeper Web PMS from an external website. Both create a booking with status Pending, unassigned to a room — your staff review it on the dashboard and Approve or Decline it from there.

  • Public form — link or embed a hosted page, no code required.
  • Booking API — your own site’s backend submits requests programmatically.

Option 1: Public Form

Link or embed (via an <iframe>) this page directly:

https://yourdomain.com/book.php

It’s a self-contained page — it collects guest name, email, phone, dates, and an optional message, and shows its own success/error state. Nothing to configure.

Option 2: Booking API

For a website with its own backend that wants to submit bookings itself (for example, a custom booking form on your marketing site) rather than sending guests to book.php.

This is a server-to-server API. Your site’s backend (PHP, Node, etc.) calls it directly — it is not meant to be called from JavaScript running in the visitor’s browser. There’s no CORS support, and calling it client-side would expose your API key in the page source.

Getting your API key

In Innkeeper Web PMS, go to Settings › Booking API. A key is generated automatically the first time you view that page. The same card shows your exact endpoint URL and a ready-to-run curl example, and lets you regenerate the key if it’s ever leaked.

Endpoint

POST https://yourdomain.com/booking_api.php

Authentication

Send the key in a header:

X-API-Key: your-key-here

An api_key POST field also works if your HTTP client can’t set custom headers, but the header is preferred.

Request Body

JSON (Content-Type: application/json) or standard form-encoded — either works.

Field Required Notes
guest_name Yes Full name
email Yes Must be a valid email address
check_in Yes YYYY-MM-DD, cannot be in the past
check_out Yes YYYY-MM-DD, must be after check_in
phone No  
message No Free text (special requests etc.)
website_booking_ref No Your own site’s booking/order ID, for reconciliation. Only stored if Settings › Enable Website Booking Reference is turned on — silently dropped otherwise. Shown on the booking page and invoices when enabled.

Example — curl

curl -X POST https://yourdomain.com/booking_api.php \
  -H "X-API-Key: your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "guest_name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "555-1234",
    "check_in": "2026-08-01",
    "check_out": "2026-08-05",
    "message": "Late check-in, arriving around 9pm",
    "website_booking_ref": "WEB-10456"
  }'

website_booking_ref is optional and only kept if Settings › Enable Website Booking Reference is turned on — safe to always send, it’s just ignored otherwise.

Example — PHP

<?php
$ch = curl_init('https://yourdomain.com/booking_api.php');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: your-key-here',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'guest_name' => 'Jane Doe',
    'email'      => 'jane@example.com',
    'phone'      => '555-1234',
    'check_in'   => '2026-08-01',
    'check_out'  => '2026-08-05',
    'message'    => 'Late check-in, arriving around 9pm',
    'website_booking_ref' => 'WEB-10456',
]));

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($response['success']) {
    // $response['booking_id']
} else {
    // $response['error']
}

Response

Success — 200 OK

{ "success": true, "booking_id": 123 }

Failure

{ "success": false, "error": "A valid email address is required." }
HTTP Status Meaning
200 Booking created
400 Validation error (see error message)
401 Missing or invalid API key
405 Wrong HTTP method (only POST is accepted)

What Happens After a Request Comes In

  • The booking appears on the dashboard with a purple Pending badge, and a Pending Requests count shows in the top metrics.
  • Public form (book.php) only: if SMTP is configured (Settings › Email SMTP Credentials), the address in Notification Email gets an alert email with the request details, and the guest gets a short confirmation email. Both are best-effort — a missing or broken SMTP setup never blocks the booking itself from being created.
  • The Booking API does not send either email. It’s assumed your own site already confirms the request to the visitor and/or notifies your team — the API just creates the Pending booking.
  • Staff open the booking from the dashboard:
    • Approve Request opens a popup to pick a room, occupancy, and nightly rates (pre-filled from the room’s defaults, editable). Confirming attaches the room, sets the booking to Confirmed, and automatically emails the guest their invoice as a PDF.
    • Decline Request sets the booking to Declined and sends the guest a short “unfortunately we can’t accommodate this request” email.

Security Notes

  • Treat the API key like a password — anyone with it can create bookings in your system. Don’t commit it to a public repo or expose it in client-side code.
  • Only use the key over HTTPS.
  • If it leaks, regenerate it from Settings immediately — the old key stops working the moment you do, so update it everywhere it’s used.
Neural Translation