Create a sandbox booking request for a vacation rental

POST /v1/developer/vacation-rentals/{vacationRental}/booking-requests

Operation ID: createVacationRentalBookingRequest

Records a request-to-book for the granted vacation rental as a REAL Kismet reservation record — the guestbook, journey, and telemetry planes light up exactly as for a live booking — with the PMS mirror suppressed and no charge. Sandbox semantics are the meaning of a TEST-environment installation on this operation; a LIVE installation receives 409 SANDBOX_ONLY in this contract version (live transactional writes are the Kismet Pay lane). The Developer Bearer credential establishes installation authority. A host BFF may additionally send its server-only X-Kismet-Guest-Token, X-Kismet-CSRF, and the kidSid verified during sign-in; that token subject then establishes the human and guest contact becomes optional. Contact can enrich only the same principal and never selects another guest. Anonymous requests retain the required guest contact contract. Server-side authority: the stay is re-fitted against the synced calendar and re-quoted by the same engine checkout uses; a client price is never accepted. Replay-safe: the same installation + rental + stay + guest email resolves to the same request and confirmation code; send Idempotency-Key to create a deliberate second request for the same guest and stay. Never writes a revenue-attribution record and never fires an ad destination.

Contract status

Field	Value
Maturity	`beta`
Required capability	`bookings.write`
Freshness class	`sandbox-write`
Quota cost	`1`
Operational owner	API + Booking Platform

All operations require a Kismet Developer Bearer credential. Collection and resource authority is resolved from the credential’s installation grants; identifiers in the URL never grant access.

Request parameters

Name	In	Type	Required	Description
`vacationRental`	path	string	yes
`idempotency-key`	header	string	no
`x-kismet-guest-token`	header	string	no	Optional server-only guest access token. When present, the token subject is the booking human and guest contact cannot select another identity.
`x-kismet-csrf`	header	string	no	Required with X-Kismet-Guest-Token. Same-origin proof validated by the host BFF.

Request body

The request body is JSON. The canonical schema is:

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "checkIn",
    "checkOut",
    "guests"
  ],
  "properties": {
    "checkIn": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "checkOut": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "guests": {
      "type": "integer",
      "minimum": 1,
      "maximum": 99
    },
    "guest": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "firstName",
        "lastName",
        "email"
      ],
      "properties": {
        "firstName": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "lastName": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "email": {
          "type": "string",
          "minLength": 3,
          "maxLength": 254
        },
        "phone": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 40
        }
      }
    },
    "kidSid": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^kid_[A-Za-z0-9]{6,40}$"
    }
  }
}

Minimal example:

{
  "checkIn": "2026-09-10",
  "checkOut": "2026-09-14",
  "guests": 4
}

cURL

curl --request POST \
  "$KISMET_API_ORIGIN/v1/developer/vacation-rentals/sand-sea-110/booking-requests" \
  --header "Authorization: Bearer $KISMET_DEVELOPER_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{"checkIn":"2026-09-10","checkOut":"2026-09-14","guests":4}'

Responses

Status	Meaning
201	Created successfully.
400	Invalid request parameters or body.
401	Missing, invalid, expired, or inappropriate credential/session.
403	Credential lacks the required grant/capability, or an origin/CSRF check failed.
409	Request conflicts with the installation environment or current state.
429	Rate limit or quota exceeded; inspect response metadata before retrying.
503	A required Kismet dependency is temporarily unavailable.

Success example

{
  "requestId": "55555555-5555-4555-8555-555555555555",
  "confirmationCode": "SBX-K7QM2H9",
  "status": "received",
  "sandbox": true,
  "stay": {
    "checkIn": "2026-08-01",
    "checkOut": "2026-08-04",
    "nights": 3,
    "guests": 2
  },
  "vacationRental": {
    "id": "22222222-2222-4222-8222-222222222222",
    "slug": "sandbox-chalet"
  },
  "display": {
    "nightlyMinor": 30000,
    "totalBeforeTaxMinor": 90000,
    "currency": "USD"
  }
}