Vacatia API Catalog
/
Cloudbeds API
/
Reservation
/
getReservationsWithRateDetails

Cloudbeds API (v1.2)

Welcome to the documentation for Cloudbeds API Version v1.2! If you are looking to learn how to use the Cloudbeds API to access guest information, reservations, or similar data for your Cloudbeds customers, then you've come to the right place.

In this document you will find all the API methods we provide along with explanations for parameters and response examples.

If you have questions about different implementation steps (e.g. how to implement OAuth 2.0), please refer to our Integrations Portal.

Be sure to subscribe to the monthly Cloudbeds API announcement mailing list to receive information on new additions and improvements to the Cloudbeds API and related developer tools.

Endpoint: https://api.cloudbeds.com/api/v1.2/{method}

HTTPS: Our API requires HTTPS. We'll respond with an appropriate error if you're not using it.

Request Format: HTTP GET, POST and PUT (Content-Type: application/x-www-form-urlencoded)

Response Format: JSON

Response Header: X-Request-ID is added to response headers in all calls to help accelerate support and troubleshooting.

Run in Postman use this link to access our Public collection in Postman.

Download OpenAPI description
cloudbeds.json
cloudbeds.yaml
Languages
Servers
Mock server
https://tbg-api-docs.vacatia.com/_mock/cloudbeds/
https://api.cloudbeds.com/api/v1.2/

Authentication

Operations

Adjustment

Operations

AllotmentBlocks

Operations

AppSettings

Operations

Currency

Operations

CustomFields

Operations

Dashboard

Operations

Emails

Operations

Groups

Operations

Guest

Operations

Hotel

Operations

HouseAccount

Operations

Housekeeping

Operations

Integration

Operations

Invoices

Operations

Item

Operations

Package

Operations

Payment

Operations

Rate

Operations

Reservation

Operations

getReservation

Request

Returns information on a booking specified by the reservationID parameter

Query
propertyIDstring

Property ID

reservationIDstringrequired

Reservation Unique Identifier. Obtained from one of the "Reservations" group methods

curl -i -X GET \
  'https://tbg-api-docs.vacatia.com/_mock/cloudbeds/getReservation?propertyID=string&reservationID=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

dataobject

Details for the reservation queried

messagestring or null

To be used in case any error occurs (if success = false). If success = true, it does not exist.

Response
application/json
{
  "success": true,
  "data": {
    "propertyID": "string",
    "guestName": "string",
    "guestEmail": "string",
    "isAnonymized": true,
    "guestList": { … },
    "reservationID": "string",
    "dateCreated": "2019-08-24T14:15:22Z",
    "dateModified": "2019-08-24T14:15:22Z",
    "estimatedArrivalTime": "14:15:22Z",
    "source": "string",
    "sourceID": "string",
    "thirdPartyIdentifier": "string",
    "status": "confirmed",
    "total": 0,
    "balance": 0,
    "balanceDetailed": [ … ],
    "assigned": [ … ],
    "unassigned": [ … ],
    "cardsOnFile": [ … ],
    "customFields": [ … ],
    "startDate": "2019-08-24",
    "endDate": "2019-08-24",
    "allotmentBlockCode": "string",
    "channelProvidedCreditCard": true,
    "groupInventory": [ … ]
  },
  "message": "string"
}

postReservation

Request

Adds a reservation to the selected property

Bodyapplication/x-www-form-urlencoded
propertyIDstring or null

Property ID

sourceIDstring or null

The third-party source ID for this reservation.

thirdPartyIdentifierstring or null

If it was received from a booking channel, this can be an identifier from that channel.

startDatestring(date)

Check-In date.

endDatestring(date)

Check-Out date.

guestFirstNamestring

First name of the guest

guestLastNamestring

Last name of the guest

guestGenderstring or null
Enum"M""F""N/A"
guestCountrystring

Valid ISO-Code for Country (2 characters)

guestZipstring

ZIP Code

guestEmailstring

Guest email

guestPhonestring or null

Guest main phone number

estimatedArrivalTimestring or null(time)

Estimated Arrival Time, 24-hour format.

roomsArray of objects

Array with quantity of rooms

adultsArray of objects

Array with number of adults

childrenArray of objects

Array with number of children

paymentMethodstring

Payment Method of choice.

Enum"cash""credit""ebanking""pay_pal"
cardTokenstring or null

Credit Card identifier. Payment Method must be credit. This field should be filled with credit card identifier according to gateway. Only available for Stripe and should send the Customer ID.

paymentAuthorizationCodestring or null

Transaction identifier. Payment Method must be credit. This field should be filled with transaction identifier according to gateway. Only available for Stripe and it should be filled with Charge ID associated to the Payment Intent.

customFieldsArray of objects or null

Array with custom fields information

promoCodestring or null

Promotional code. Required for specials and packages that uses it. "rateID" parameter required for using "promoCode".

allotmentBlockCodestring or null

Allotment block code to add reservation to allotment block.

groupCodestring or null

Code from the Aggregate Allotment block the reservation will be added to.

dateCreatedstring or null(date-time)

Date reservation was made. Defaults to current date if omitted.

sendEmailConfirmationboolean or null

Send confirmation email to guest.

Default true
curl -i -X POST \
  https://tbg-api-docs.vacatia.com/_mock/cloudbeds/postReservation \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d propertyID=string \
  -d sourceID=string \
  -d thirdPartyIdentifier=string \
  -d startDate=2019-08-24 \
  -d endDate=2019-08-24 \
  -d guestFirstName=string \
  -d guestLastName=string \
  -d guestGender=M \
  -d guestCountry=string \
  -d guestZip=string \
  -d guestEmail=string \
  -d guestPhone=string \
  -d estimatedArrivalTime=14:15:22Z \
  -d 'rooms=[object Object]' \
  -d 'adults=[object Object]' \
  -d 'children=[object Object]' \
  -d paymentMethod=cash \
  -d cardToken=string \
  -d paymentAuthorizationCode=string \
  -d 'customFields=[object Object]' \
  -d promoCode=string \
  -d allotmentBlockCode=string \
  -d groupCode=string \
  -d dateCreated=2019-08-24T14:15:22Z \
  -d sendEmailConfirmation=true

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

reservationIDstring

Reservation identifier

statusstring

Reservation status
'not_confirmed' - Reservation is pending confirmation
'confirmed' - Reservation is confirmed

Enum"not_confirmed""confirmed"
guestIDstring

Guest ID

guestFirstNamestring

Guest First Name

guestLastNamestring

Guest Last Name

guestGenderstring or null

Guest Gender

Enum"M""F""N/A"
guestEmailstring

Guest Email

startDatestring(date)

Reservation CheckIn date

endDatestring(date)

Reservation CheckOut date

dateCreatedstring(date-time)

Reservation creation datetime

grandTotalnumber

Grand Total

unassignedArray of objects

unassigned rooms array

messagestring or null

To be used in case any error occurs (if success = false). If success = true, it does not exist.

Response
application/json
{
  "success": true,
  "reservationID": "string",
  "status": "not_confirmed",
  "guestID": "string",
  "guestFirstName": "string",
  "guestLastName": "string",
  "guestGender": "M",
  "guestEmail": "string",
  "startDate": "2019-08-24",
  "endDate": "2019-08-24",
  "dateCreated": "2019-08-24T14:15:22Z",
  "grandTotal": 0,
  "unassigned": [
    { … }
  ],
  "message": "string"
}

getReservations

Request

Returns a list of reservations that matched the filters criteria.
Please note that some reservations modification may not be reflected in this timestamp. ### Group account support

Query
propertyIDstring

ID for the properties to be queried (comma-separated, i.e. 37,345,89).
It can be omitted if the API key is single-property, or to get results from all properties on an association.

statusstring

Filter by current reservation status

Enum"not_confirmed""confirmed""canceled""checked_in""checked_out""no_show"
resultsFromstring(date-time)

Inferior limit datetime, used to filter reservations, based on booking date

resultsTostring(date-time)

Superior limit datetime, used to filter reservations, based on booking date

modifiedFromstring(date-time)

Inferior limit datetime, used to filter reservations, based on booking modification date

modifiedTostring(date-time)

Superior limit datetime, used to filter reservations, based on booking modification date

checkInFromstring(date)

Filters reservations result to return only reservations with check-in date range starting on this date

checkInTostring(date)

Filters reservations result to return only reservations with check-in date range ending on this date

checkOutFromstring(date)

Filters reservations result to return only reservations with check-out date range starting on this date

checkOutTostring(date)

Filters reservations result to return only reservations with check-out date range ending on this date

roomIDstring

Filters reservation with the supplied room ID. CheckIn/checkOut dates OR status are required. If dates are provided and span more than one day, more than one reservation can be returned. If roomID supplied, roomName is ignored.

roomNamestring

Filters reservation with the supplied room name (customizable by each property). CheckIn/checkOut dates OR status are required. If dates are provided and span more than one day, more than one reservation can be returned.

includeGuestsDetailsboolean

If guests details should be included or not

Default false
includeCustomFieldsboolean

If reservation custom fields should be included or not

Default false
includeAllRoomsboolean

When specified, the response will include an additional rooms field that combines both unassigned and assigned rooms.

Default false
sourceIdstring

Filters reservation with the supplied source ID.

sourceReservationIdstring

Filters reservation with the supplied reservation source ID.

ratePlanIdstring

Filters reservation with the supplied rate plan ID.

firstNamestring

Filters reservation with the supplied primary guest first name.

lastNamestring

Filters reservation with the supplied primary guest last name.

guestIDstring

Filters reservation with the supplied Guest ID (Including additional guests).

sortByRecentboolean

Sort response results by most recent action

pageNumberinteger

Results page number

Default 1
pageSizeinteger

Results page size. Max = 100

Default 100
curl -i -X GET \
  'https://tbg-api-docs.vacatia.com/_mock/cloudbeds/getReservations?checkInFrom=2019-08-24&checkInTo=2019-08-24&checkOutFrom=2019-08-24&checkOutTo=2019-08-24&firstName=string&guestID=string&includeAllRooms=false&includeCustomFields=false&includeGuestsDetails=false&lastName=string&modifiedFrom=2019-08-24T14%3A15%3A22Z&modifiedTo=2019-08-24T14%3A15%3A22Z&pageNumber=1&pageSize=100&propertyID=string&ratePlanId=string&resultsFrom=2019-08-24T14%3A15%3A22Z&resultsTo=2019-08-24T14%3A15%3A22Z&roomID=string&roomName=string&sortByRecent=true&sourceId=string&sourceReservationId=string&status=not_confirmed' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

dataArray of objects

Details for the reservation queried

countinteger

Number of results returned

totalinteger

Total number of results

Response
application/json
{
  "success": true,
  "data": [
    { … }
  ],
  "count": 0,
  "total": 0
}

getReservationsWithRateDetails

Request

Returns a list of reservations with added information regarding booked rates and sources. The results are limited to 2 years in the past unless resutsFrom parameter is set to another date.
Please note that some reservations modification may not be reflected in this timestamp.

Query
propertyIDstring

Property ID

resultsFromstring(date-time)

Inferior limit datetime, used to filter reservations, based on booking date. If it is not set, will return the reservations starting 2 years ago

resultsTostring(date-time)

Superior limit datetime, used to filter reservations, based on booking date. If it is not set, will return the reservations up to current date

modifiedFromstring(date-time)

Superior limit datetime, used to filter reservations, based on modification date.

modifiedTostring(date-time)

Superior limit datetime, used to filter reservations, based on modification date.

sortByRecentboolean

Sort response results by most recent action

reservationIDstring

Reservation identifiers, comma-separated, i.e. 37,345,89, used to return transactions limited to the selected reservations.

reservationCheckOutFromstring(date)

Superior limit datetime, used to filter reservations, based on reservation check-out date.

reservationCheckOutTostring(date)

Superior limit datetime, used to filter reservations, based on reservation check-out date.

includeDeletedboolean

Include deleted reservations

Default false
excludeStatusesstring

List of statuses (separated by comma) to be excluded from search

pageNumberinteger

Results page number

Default 1
pageSizeinteger

Results page size. Max = 100

Default 100
curl -i -X GET \
  'https://tbg-api-docs.vacatia.com/_mock/cloudbeds/getReservationsWithRateDetails?excludeStatuses=string&includeDeleted=false&modifiedFrom=2019-08-24T14%3A15%3A22Z&modifiedTo=2019-08-24T14%3A15%3A22Z&pageNumber=1&pageSize=100&propertyID=string&reservationCheckOutFrom=2019-08-24&reservationCheckOutTo=2019-08-24&reservationID=string&resultsFrom=2019-08-24T14%3A15%3A22Z&resultsTo=2019-08-24T14%3A15%3A22Z&sortByRecent=true' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

dataArray of objects

Details for the reservations returned

countinteger

Number of results returned

totalinteger

Total number of results

Response
application/json
{
  "success": true,
  "data": [
    { … }
  ],
  "count": 0,
  "total": 0
}

getReservationAssignments

Request

Returns a list of rooms/reservations assigned for a selected date.

Query
propertyIDstring

Property ID

datestring(date)

Date selected to get the assignments. If no date is passed, it will return the results for the current day.

curl -i -X GET \
  'https://tbg-api-docs.vacatia.com/_mock/cloudbeds/getReservationAssignments?date=2019-08-24&propertyID=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

dataArray of objects

Details for the rooms assigned on the selected date

messagestring or null

To be used in case any error occurs (if success = false). If success = true, it does not exist.

Response
application/json
{
  "success": true,
  "data": [
    { … }
  ],
  "message": "string"
}

getReservationInvoiceInformation

Request

Returns information that can be used to create an invoice for the selected reservation

Query
propertyIDstring

Property ID

reservationIDstringrequired

Reservation Unique Identifier

curl -i -X GET \
  'https://tbg-api-docs.vacatia.com/_mock/cloudbeds/getReservationInvoiceInformation?propertyID=string&reservationID=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

dataArray of objects

Details for the rooms assigned on the selected date

messagestring or null

To be used in case any error occurs (if success = false). If success = true, it does not exist.

Response
application/json
{
  "success": true,
  "data": [
    { … }
  ],
  "message": "string"
}

postReservationNote

Request

Adds a reservation note

Bodyapplication/x-www-form-urlencoded
propertyIDstring or null

Property ID

reservationIDstring

Reservation Unique Identifier

reservationNotestring

Note to be added to reservation

userIDstring or null

User ID Identify the actual user that is posting the note

curl -i -X POST \
  https://tbg-api-docs.vacatia.com/_mock/cloudbeds/postReservationNote \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d propertyID=string \
  -d reservationID=string \
  -d reservationNote=string \
  -d userID=string

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

reservationNoteIDstring

Reservation note ID

messagestring or null

To be used in case any error occurs (if success = false). If success = true, it does not exist.

Response
application/json
{
  "success": true,
  "reservationNoteID": "string",
  "message": "string"
}

getReservationNotes

Request

Retrieves reservation notes based on parameters

Query
propertyIDstring

Property ID

reservationIDstringrequired

Reservation Unique Identifier

curl -i -X GET \
  'https://tbg-api-docs.vacatia.com/_mock/cloudbeds/getReservationNotes?propertyID=string&reservationID=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

dataArray of objects

Details for the notes on that reservation

messagestring or null

To be used in case any error occurs (if success = false). If success = true, it does not exist.

Response
application/json
{
  "success": true,
  "data": [
    { … }
  ],
  "message": "string"
}

putReservationNote

Request

Updates an existing reservation note.

Bodyapplication/x-www-form-urlencoded
propertyIDstring or null

Property ID

reservationIDstring

Reservation Unique Identifier

reservationNoteIDstring

Reservation Note ID

reservationNotestring

Note to be added to reservation

curl -i -X PUT \
  https://tbg-api-docs.vacatia.com/_mock/cloudbeds/putReservationNote \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d propertyID=string \
  -d reservationID=string \
  -d reservationNoteID=string \
  -d reservationNote=string

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

messagestring or null

To be used in case any error occurs (if success = false). If success = true, it does not exist.

Response
application/json
{
  "success": true,
  "message": "string"
}

deleteReservationNote

Request

Archives an existing reservation note.

Query
propertyIDstring

Property ID

reservationIDstringrequired

Reservation Unique Identifier

reservationNoteIDstringrequired

Reservation Note ID

curl -i -X DELETE \
  'https://tbg-api-docs.vacatia.com/_mock/cloudbeds/deleteReservationNote?propertyID=string&reservationID=string&reservationNoteID=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

messagestring or null

To be used in case any error occurs (if success = false). If success = true, it does not exist.

Response
application/json
{
  "success": true,
  "message": "string"
}

postReservationDocument

Request

Attaches a document to a reservation

Bodyapplication/x-www-form-urlencoded
propertyIDstring or null

Property ID

reservationIDstring

Reservation Unique Identifier

filestring(binary)

Form-based File Upload
Allowed file types: *.pdf, *.rtf, *.doc, *.docx, *.txt, *.jpg, *.jpeg, *.png, *.gif, *.csv, *.xls, *.xlsx, *.xml
Allowed max file size: 100MB

curl -i -X POST \
  https://tbg-api-docs.vacatia.com/_mock/cloudbeds/postReservationDocument \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d propertyID=string \
  -d reservationID=string \
  -d file=string

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

messagestring or null

To be used in case any error occurs (if success = false). If success = true, it does not exist.

dataobject

Details for the uploaded file

Response
application/json
{
  "success": true,
  "message": "string",
  "data": {
    "fileID": "string"
  }
}

putReservation

Request

Updates a reservation, such as custom fields, estimated arrival time, room configuration and reservation status.

Bodyapplication/x-www-form-urlencoded
propertyIDstring or null

Property ID

reservationIDstring

Reservation Unique Identifier, one reservation ID per call.

estimatedArrivalTimestring or null(time)

Estimated Arrival Time, 24-hour format.

statusstring or null

Reservation status
'confirmed' - Reservation is confirmed
'not_confirmed' - Reservation not passed confirmation
'canceled' - Reservation is canceled
'checked_in' - Guest is in hotel
'checked_out' - Guest already left hotel
'no_show' - Guest didn't showed up on check-in date

Enum"confirmed""not_confirmed""canceled""checked_in""checked_out""no_show"
checkoutDatestring or null(date)

Update the checkoutDate across the whole reservation

customFieldsArray of objects or null

Array with custom fields information

roomsArray of objects or null

Array with rooms information to change accommodations assigned to the reservation

dateCreatedstring or null(date-time)

Date reservation was made. Do not change if omitted.

sendStatusChangeEmailboolean or null

Send email on reservation status change to property and guest.

Default false
curl -i -X PUT \
  https://tbg-api-docs.vacatia.com/_mock/cloudbeds/putReservation \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d propertyID=string \
  -d reservationID=string \
  -d estimatedArrivalTime=14:15:22Z \
  -d status=confirmed \
  -d checkoutDate=2019-08-24 \
  -d 'customFields=[object Object]' \
  -d 'rooms=[object Object]' \
  -d dateCreated=2019-08-24T14:15:22Z \
  -d sendStatusChangeEmail=false

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

messagestring or null

To be used in case any error occurs.

dataobject or null

Returns the reservation data as defined by getReservation call.

Response
application/json
{
  "success": true,
  "message": "string",
  "data": {}
}

getSources

Request

Gets available property sources

Query
propertyIDsstring

ID for the properties to be queried (comma-separated, i.e. 37,345,89).

curl -i -X GET \
  'https://tbg-api-docs.vacatia.com/_mock/cloudbeds/getSources?propertyIDs=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

dataArray of objects
messagestring or null

To be used in case any error occurs (if success = false). If success = true, it does not exist.

Response
application/json
{
  "success": true,
  "data": [
    { … }
  ],
  "message": "string"
}

Room

Operations

Taxes and Fees

Operations

User

Operations