--- title: "Create a sandbox booking request for a vacation rental" description: "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." --- `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: ```json { "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: ```json { "checkIn": "2026-09-10", "checkOut": "2026-09-14", "guests": 4 } ``` ## cURL ```sh 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 ```json { "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" } } ``` ## Machine-readable sources - [This page as Markdown](/api/reference/create-vacation-rental-booking-request.md) - [Developer API OpenAPI v0.7.0](/openapi.json)