Skip to content
Documentation · Bookings

API reference

Bookings

Resource bookings

A booking is identified by your sourceBookingId and tied to a property. Creating one triggers Properly's scheduling automation.

Creating a booking whose sourceBookingId already exists for the account returns:

409 Conflict Duplicate sourceBookingId. Update the existing booking instead.

Create a booking

POST /v1/bookings 201 Created x-api-key

Creates a booking, returns it inline, and triggers downstream scheduling automation. A duplicate sourceBookingId for the account → 409.

Request body
Field Type Required Notes
sourceBookingId string Required Your booking id. Duplicate for the account → 409 conflict.
startDate date-time Required Check-in.
endDate date-time Required Check-out.
numberOfGuests integer Required —
guestDetails object[] Required Non-empty. See Guest details.
propertyId string One of One of propertyId or sourcePropertyId identifies the property.
sourcePropertyId string One of Your property id.
title string Optional —
tags string[] Optional 1–10 items; an empty list is rejected.
otherAttributes object[] Optional See Other attributes.

Guest details

Guest details
Field Type Required Notes
sourceId string Required Your id for the guest.
firstName string Required —
lastName string Optional —
sourcePictureUrl string Optional A URL.

Other attributes

Other attributes
Field Type Required Notes
label string Required Max 100 chars.
value string | string[] Required A string of up to 500 chars, or an array of such strings.
group string Optional Max 100 chars.
pictures string[] Optional Picture URLs.
Request 
curl -X POST https://platform.getproperly.com/v1/bookings \
  -H "x-api-key: $PROPERLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f8a33a2-bd60-4c1e-9c11-booking-55871" \
  -d '{
    "sourceBookingId": "pms-bk-55871",
    "sourcePropertyId": "pms-100234",
    "startDate": "2026-10-03T15:00:00Z",
    "endDate": "2026-10-08T11:00:00Z",
    "numberOfGuests": 2,
    "guestDetails": [
      { "sourceId": "pms-guest-77", "firstName": "Ana", "lastName": "Smith" }
    ],
    "title": "Smith family stay"
  }'

List bookings in a date window

GET /v1/bookings 200 OK x-api-key

Returns every booking that overlaps the window: it arrives before dateTo and departs after dateFrom, so a guest who checked in before the window started is included. Cancelled bookings are included unless you filter by status. Collection envelope, cursor-paginated, ordered by startDate ascending. Invalid dates or a malformed cursor → 400.

Query parameters
Parameter Type Required Notes
dateFrom date-time Required —
dateTo date-time Required —
propertyId string Optional Only bookings for this one property.
status integer Optional 1 created, 2 dates changed, 3 cancelled.
cursor string Optional Opaque cursor from a previous page's nextCursor.
limit integer Optional 1–100, default 50.
Response fields
Field Type Required Notes
bookingId string Required The Properly id.
sourceBookingId string Optional The identifier you supplied at create.
propertyId string Optional —
status integer Optional 1 created, 2 dates changed, 3 cancelled.
startDate date-time Optional Check-in.
endDate date-time Optional Check-out.
title string Optional —
guestDetails object[] Optional Items { firstName, lastName }.
numberOfGuests integer Optional —
tags string[] Optional —
otherAttributes object[] Optional —
createdAt date-time Optional —
updatedAt date-time Optional —
curl 
curl "https://platform.getproperly.com/v1/bookings?dateFrom=2026-10-05T00:00:00Z&dateTo=2026-10-12T00:00:00Z&propertyId=8jL2mQxT4a" \
  -H "x-api-key: $PROPERLY_API_KEY"

Get a booking

GET /v1/bookings/{bookingId} 200 OK x-api-key

Returns one booking in the same read shape as the listing. 404 if unknown or owned by another account.

curl 
curl https://platform.getproperly.com/v1/bookings/bk_7Yt2 \
  -H "x-api-key: $PROPERLY_API_KEY"

Update a booking

PATCH /v1/bookings/{bookingId} 200 OK x-api-key

Partial update of booking fields; returns the updated booking.

Request body
Field Type Required Notes
title string Optional —
numberOfGuests integer Optional —
guestDetails object[] Optional Same shape as create.
tags string[] Optional 1–10 items; an empty list is rejected.
otherAttributes object[] Optional Same shape as create.
Request 
curl -X PATCH https://platform.getproperly.com/v1/bookings/bk_7Yt2 \
  -H "x-api-key: $PROPERLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "numberOfGuests": 3 }'

Change booking dates

PATCH /v1/bookings/{bookingId}/dates 200 OK x-api-key

Changes the dates and marks the booking as changed.

Request body
Field Type Required Notes
startDate date-time Required Check-in.
endDate date-time Required Check-out.
Request 
curl -X PATCH https://platform.getproperly.com/v1/bookings/bk_7Yt2/dates \
  -H "x-api-key: $PROPERLY_API_KEY" -H "Content-Type: application/json" \
  -d '{ "startDate": "2026-10-03T15:00:00Z", "endDate": "2026-10-08T11:00:00Z" }'

Cancel a booking

POST /v1/bookings/{bookingId}/cancel 200 OK x-api-key

No body. Returns the canceled booking.

Request 
curl -X POST https://platform.getproperly.com/v1/bookings/bk_7Yt2/cancel \
  -H "x-api-key: $PROPERLY_API_KEY"

Delete a booking

DELETE /v1/bookings/{bookingId} 204 No Content x-api-key

Deletes the booking. Returns 204 with no body.

Request 
curl -X DELETE https://platform.getproperly.com/v1/bookings/bk_7Yt2 \
  -H "x-api-key: $PROPERLY_API_KEY"

Type to search the Platform API docs.