---
title: "Request to book"
method: POST
path: "/v1/booking_requests"
tags: ["Bookings"]
---

# Request to book

`POST /v1/booking_requests`

## Request

- Base URL: `https://threshold.rentals/api`
- URL: `https://threshold.rentals/api/v1/booking_requests`
- Auth: HTTP bearer

Turn an open quote into a booking. Set house_rules_accepted only after the guest agreed to the quote's house_rules. If the response has payment_url, the guest must open it and add a card within 60 minutes before the host gets the request.

## Headers

- `Idempotency-Key` string, required

## Request body

- BookingRequest
  - `quote_id` string, required
  - `buyer` object, required
    - `first_name` string, required
    - `last_name` string, required
    - `email` string, email, required
    - `phone` string
  - `house_rules_accepted` true, required
  - `special_requests` string: Shown to the host with the request

## Response `201`

The booking, with links for the guest

- BookingRequestResult
  - `booking` Booking
    - `id` string
    - `confirmation_code` string
    - `status` 'awaiting_payment' | 'pending_host_confirmation' | 'confirmed' | 'declined' | 'expired' | 'cancelled_by_guest' | 'cancelled_by_host' | 'cancelled_unpaid'
    - `property_id` string
    - `check_in` string, date
    - `check_out` string, date
    - `party` Party
      - `adults` integer
      - `children` integer
      - `infants` integer
      - `pets` integer
      - `service_animals` integer
    - `total` Money
      - `amount` integer, required: In cents
      - `currency` string, required
    - `amount_paid` Money
      - `amount` integer, required: In cents
      - `currency` string, required
    - `amount_refunded` Money
      - `amount` integer, required: In cents
      - `currency` string, required
    - `refund_schedule` RefundTier[]
      - `until` string, date-time: Cancel before this time…
      - `refund` Money
        - `amount` integer, required: In cents
        - `currency` string, required
    - `payment` object
      - `collected_by` 'threshold' | 'host'
      - `status` string
      - `plan` string
      - `payment_url` string, uri: Present when the guest still has to pay
      - `charge_date` string, date-time
      - `pay_by` string, date-time
    - `host_confirm_by` string, date-time
    - `arrival_info_available_at` string, date-time
    - `arrival_info_sent_at` string, date-time
    - `special_requests` string
    - `host_message` string
    - `created_at` string, date-time
  - `guest_status_url` string, uri: Private page for the guest to follow, pay, message or cancel
  - `payment_url` string, uri: Give to the guest: a secure Stripe page to add a card within 60 minutes
  - `agent_payment` object: Present when you can pay with a Stripe shared payment token instead of payment_url; see instructions.

## Other responses

- `400`: Invalid input (e.g. invalid_dates, unknown_amenity, place_not_found)
- `401`: Agent token missing (unauthorized)
- `404`: Not found (property_not_found, quote_not_found, booking_not_found)
- `409`: Conflict (dates_unavailable with alternatives, quote_converted, refund_changed, not_cancellable, stay_started)
- `410`: Quote expired: get a new one
- `422`: The stay or guest details don't meet the listing's rules (e.g. min nights, max guests, house_rules_not_accepted)
- `429`: Rate limited or too many open requests: see Retry-After

---

[API](https://skmtc.dev/threshold/apis/threshold-stays-api.md) · [All operations](https://skmtc.dev/threshold/apis/threshold-stays-api/llms.txt) · [OpenAPI document](https://skmtc.dev/threshold/apis/threshold-stays-api/revisions/7acf3ae91b56?raw)