Create a reservation — in the listing's PMS, or as a direct booking

Reservations · POST /v1/reservations

POST/v1/reservations

Note

A listing managed in a connected PMS (Mews, Cloudbeds, Hostaway, Guesty, Beds24, BookingSync, Lodgify, Smoobu, Hospitable, iGMS, OwnerRez) is booked in the PMS first, then recorded from the PMS record; the PMS checks availability (409 pms_unavailable) and what it cannot do is refused (422 pms_write_unsupported). Any other listing gets a direct booking priced from its own rates, with no availability check. A field the listing cannot take is 422 unsupported_field. 201 with pms.partial: true means the booking exists but pms.failedSections did not apply — do not create it again. Check GET /v1/listings/{id} → capabilities.reservations first. Guide: /docs/reservations/create

Request

curl -X POST https://api.repull.dev/v1/reservations \
  -H "Authorization: Bearer $REPULL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "listingId": 4118,
  "checkIn": "2026-10-01",
  "checkOut": "2026-10-05",
  "guest": { "firstName": "Ada", "lastName": "Lovelace", "email": "ada@example.com" },
  "adults": 2,
  "children": 1,
  "totalPrice": 880,
  "notes": "Late arrival, around 22:00."
}'

Response

{
  "id": "215708",
  "confirmationCode": "HA-4471923",
  "listingId": "4118",
  "platform": "direct",
  "status": "confirmed",
  "checkIn": "2026-10-01",
  "checkOut": "2026-10-05",
  "guestId": "91234",
  "totalPrice": 880,
  "currency": "USD",
  "unit": null,
  "pms": {
    "provider": "hostaway",
    "reservationId": "4471923",
    "applied": ["reservation"],
    "errors": [],
    "partial": false,
    "failedSections": []
  }
}

Body Parameters

listingIdintegerRequired

Internal Repull property id — see `GET /v1/properties`.

checkIndateRequired

Arrival, YYYY-MM-DD.

checkOutdateRequired

Departure, YYYY-MM-DD. Must be after `checkIn`.

guest{ firstName, lastName?, email?, phone? }Required

The guest on a new reservation. Matched against existing guests on email (then phone) plus name, so repeat guests are not duplicated.

adultsinteger

Adults, 1 or more.

childreninteger

Children, 0 or more.

guestCountinteger

Total guests. On a PMS listing without `adults`, used as the adult count.

statusstringDefault: confirmed

`confirmed` (default) or `tentative` — an optional hold, where the PMS has one.

platformstringDefault: direct

`direct` (default), `website` or `owner`. Channel platforms are absent: those bookings arrive through sync. `owner` is refused on a PMS listing (block owner stays in the PMS).

totalPricenumber

PMS listings only: the total for the stay, in the listing's currency. Honoured where `capabilities.reservations.customPrice` is true; omit it and the PMS prices the stay. Required on iGMS. Refused (422 unsupported_field) on a direct-booking listing.

notesstring

PMS listings only: booking notes stored in the PMS (max 5000 characters).

unitIdstring

PMS listings only: book this unit (`GET /v1/listings/{id}` → `units[].id`). Refused by PMSs that cannot target a unit.

sendConfirmationEmailboolean

PMS listings only: ask the PMS to email the guest its own confirmation, where it supports that.

checkInTimestring

Direct-booking listings only. HH:MM.

checkOutTimestring

Direct-booking listings only. HH:MM.

guestIdinteger

Direct-booking listings only: attach an existing guest instead of matching/creating one. Must belong to this workspace.

currencystring

Direct-booking listings only (a PMS books in the property's currency). ISO 4217.

Previous← Get Reservation NextUpdate Reservation →