Create a sandbox booking request for a vacation rental

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

Operation ID: createVacationRentalBookingRequest

Create a sandbox booking request to test reservation, guest-account, and tracking behavior without charging a payment method or creating a reservation in the connected booking system. Requires a TEST installation; LIVE credentials receive 409 SANDBOX_ONLY. For production booking and payment, integrate Kismet Checkout separately. Kismet Checkout supports your own payment processor or Stripe and is designed to work with Agent Pay, which lets agents book directly with managers. The Developer Bearer credential authorizes the installation. For a signed-in guest, your same-origin backend also sends X-Kismet-Guest-Token, a validated X-Kismet-CSRF proof, and the kidSid verified during sign-in. The token identifies the guest; optional contact details may update only that same person. Without a guest token, guest contact details are required. Kismet checks the stay against synchronized availability and calculates the price on the server; client-supplied prices are not accepted. Repeating the same installation, rental, dates, and guest email returns the same request and confirmation code. Use Idempotency-Key when creating a deliberate additional request for the same guest and stay. This TEST operation does not record revenue attribution or send advertising conversion events.

Contract status

Field	Value
Maturity	`beta`
Required capability	`bookings.write`
Freshness class	`sandbox-write`
Quota cost	`1`

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": "2027-01-11",
  "checkOut": "2027-01-16",
  "guests": 4,
  "guest": {
    "firstName": "Taylor",
    "lastName": "Guest",
    "email": "[email protected]"
  }
}

cURL

Set KISMET_API_ORIGIN=https://api.ksmt.app and configure KISMET_DEVELOPER_API_KEY in your environment. Run server-credential requests from your backend, not browser code.

Guest access tokens come from the signed-in guest session held by your backend. Forward a CSRF proof only after your same-origin backend validates it. If shown, KISMET_SITE_ORIGIN is the authorized origin of your site. Do not substitute a guest ID or an invented token.

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":"2027-01-11","checkOut":"2027-01-16","guests":4,"guest":{"firstName":"Taylor","lastName":"Guest","email":"[email protected]"}}'

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.

201 response 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"
  }
}

201 response schema

Content type: application/json. Required fields, nullable values, and nested structures are defined below.

View complete response schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "requestId",
    "confirmationCode",
    "status",
    "sandbox",
    "stay",
    "vacationRental"
  ],
  "properties": {
    "requestId": {
      "type": "string"
    },
    "confirmationCode": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "received"
      ]
    },
    "sandbox": {
      "type": "boolean",
      "enum": [
        true
      ]
    },
    "stay": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "checkIn",
        "checkOut",
        "nights",
        "guests"
      ],
      "properties": {
        "checkIn": {
          "type": "string"
        },
        "checkOut": {
          "type": "string"
        },
        "nights": {
          "type": "integer"
        },
        "guests": {
          "type": "integer"
        }
      }
    },
    "vacationRental": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "slug"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "slug": {
          "type": "string"
        }
      }
    },
    "display": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "nightlyMinor",
        "totalBeforeTaxMinor",
        "currency"
      ],
      "properties": {
        "nightlyMinor": {
          "type": "integer"
        },
        "totalBeforeTaxMinor": {
          "type": "integer"
        },
        "currency": {
          "type": "string"
        }
      }
    }
  }
}