Vacatia API Catalog
/
Cloudbeds API
/
Guest
/
postGuest

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

getGuest

Request

Returns information on a guest specified by the Reservation ID parameter

Query
propertyIDstring

Property ID

reservationIDstring

Reservation Unique Identifier. Required if no guestID is provided.

guestIDstring

Guest ID. Required if no reservationID is provided.

curl -i -X GET \
  'https://tbg-api-docs.vacatia.com/_mock/cloudbeds/getGuest?guestID=string&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 guest queried

Response
application/json
{
  "success": true,
  "data": {
    "firstName": "string",
    "lastName": "string",
    "gender": "M",
    "email": "string",
    "phone": "string",
    "cellPhone": "string",
    "country": "string",
    "address": "string",
    "address2": "string",
    "city": "string",
    "zip": "string",
    "state": "string",
    "birthDate": "2019-08-24",
    "documentType": "string",
    "documentNumber": "string",
    "documentIssueDate": "2019-08-24",
    "documentIssuingCountry": "string",
    "documentExpirationDate": "2019-08-24",
    "customFields": [ … ],
    "specialRequests": "string",
    "taxID": "string",
    "companyTaxID": "string",
    "companyName": "string",
    "isAnonymized": true,
    "guestOptIn": true,
    "isMerged": true,
    "newGuestID": "string"
  }
}

getGuestList

Request

Returns a list of guests, ordered by modification date ### Group account support

Query
propertyIDsstring

List of property IDs, comma-separated, i.e. 37,345,89

resultsFromstring(date-time)

Inferior limit datetime, used to filter guests result, based on latest creation/modification date

resultsTostring(date-time)

Superior limit datetime, used to filter guests result, based on latest creation/modification date

checkInFromstring(date)

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

checkInTostring(date)

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

checkOutFromstring(date)

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

checkOutTostring(date)

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

guestFirstNamestring

Filters guests result based on Guest First Name

guestLastNamestring

Filters guests result based on Guest Last Name

guestEmailstring

Filters guests result based on Guest Email

guestPhonestring

Filters guests result based on Guest Phone Number

guestCellPhonestring

Filters guests result based on Guest Cell Phone Number

statusstring

Reservation status
If more than one, send as comma-separated values. i.e. in_progress,confirmed

Enum"in_progress""confirmed""not_confirmed""canceled""checked_in""checked_out""no_show"
sortBystring

Sort By parameter

Default "modification"
Enum"creation""modification"
includeGuestInfoboolean

If API response should return with more of Guest's information

Default false
excludeSecondaryGuestsboolean

If true, response only returns main guest's

Default false
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/getGuestList?checkInFrom=2019-08-24&checkInTo=2019-08-24&checkOutFrom=2019-08-24&checkOutTo=2019-08-24&excludeSecondaryGuests=false&guestCellPhone=string&guestEmail=string&guestFirstName=string&guestLastName=string&guestPhone=string&includeGuestInfo=false&pageNumber=1&pageSize=100&propertyIDs=string&resultsFrom=2019-08-24T14%3A15%3A22Z&resultsTo=2019-08-24T14%3A15%3A22Z&sortBy=creation&status=in_progress' \
  -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 guest linked to the property (key is the Guest ID)

countinteger

Number of results returned

totalinteger

Total number of results

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": {
    "property1": { … },
    "property2": { … }
  },
  "count": 0,
  "total": 0,
  "message": "string"
}

getGuestsModified

Request

Returns a list of guests based on their modification date. Note that when a guest checks in or checks out of a room, their record is modified at that time. If no date range is passed, only the records for the current day are returned. Also note that if the guest is assigned to multiple rooms, it will result in multiple records. ### Group account support

Query
propertyIDsstring

List of property IDs, comma-separated, i.e. 37,345,89

inHouseboolean

When used, and true, will return guests only currently in-house. If the guest checks-out, it will not appear on the results.

Default false
resultsFromstring(date-time)

Inferior limit datetime, used to filter guests result, based on latest creation/modification date

resultsTostring(date-time)

Superior limit datetime, used to filter guests result, based on latest creation/modification date

checkInFromstring(date)

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

checkInTostring(date)

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

checkOutFromstring(date)

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

checkOutTostring(date)

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

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/getGuestsModified?checkInFrom=2019-08-24&checkInTo=2019-08-24&checkOutFrom=2019-08-24&checkOutTo=2019-08-24&inHouse=false&pageNumber=1&pageSize=100&propertyIDs=string&resultsFrom=2019-08-24T14%3A15%3A22Z&resultsTo=2019-08-24T14%3A15%3A22Z' \
  -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 guest linked to the property

countinteger

Number of results returned

totalinteger

Total number of results

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": [
    { … }
  ],
  "count": 0,
  "total": 0,
  "message": "string"
}

getGuestsByStatus

Request

Returns a list of guests in the current status (Not Checked In, In House, Checked Out or Cancelled), sorted by modification date. If no date range is passed, it returns all guests with the selected status. ### Group account support

Query
statusstringrequired

Guest status during the period

Enum"canceled""checked_out""in_house""not_checked_in"
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.

resultsFromstring(date-time)

Used to filter guests result, and returns only the guests that were last modified starting on "resultsFrom" value

resultsTostring(date-time)

Used to filter guests result, and returns only the guests that were last modified ending on "resultsTo" value

pageNumberinteger

Results page number

Default 1
pageSizeinteger

Results page size. Max = 100

Default 20
curl -i -X GET \
  'https://tbg-api-docs.vacatia.com/_mock/cloudbeds/getGuestsByStatus?pageNumber=1&pageSize=20&propertyID=string&resultsFrom=2019-08-24T14%3A15%3A22Z&resultsTo=2019-08-24T14%3A15%3A22Z&status=canceled' \
  -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 guest

countinteger

Number of results returned

totalinteger

Total number of results

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": [
    { … }
  ],
  "count": 0,
  "total": 0,
  "message": "string"
}

getGuestsByFilter

Request

Returns a list of guests matching the selected parameters ### Group account support

Query
propertyIDsstring

List of property IDs, comma-separated, i.e. 37,345,89

statusstringrequired

Current guest status

Enum"cancelled""checked_out""in_house""not_checked_in"
reservationIDstring
roomIDstring
guestNamestring
checkInFromstring(date)

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

checkInTostring(date)

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

checkOutFromstring(date)

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

checkOutTostring(date)

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

curl -i -X GET \
  'https://tbg-api-docs.vacatia.com/_mock/cloudbeds/getGuestsByFilter?checkInFrom=2019-08-24&checkInTo=2019-08-24&checkOutFrom=2019-08-24&checkOutTo=2019-08-24&guestName=string&propertyIDs=string&reservationID=string&roomID=string&status=cancelled' \
  -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 guest

countinteger

Number of results returned

totalinteger

Total number of results

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": [
    { … }
  ],
  "count": 0,
  "total": 0,
  "message": "string"
}

postGuestNote

Request

Adds a guest note

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

Property ID

guestIDstring

Guest ID

guestNotestring

Note to be added to guest profile. It's strictly forbidden to send unencrypted payment data through the API. Numeric values longer than 12 characters and considered valid by Luhn's algorithm will be rejected.

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/postGuestNote \
  -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 guestID=string \
  -d guestNote=string \
  -d userID=string

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

guestNoteIDstring

Guest 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,
  "guestNoteID": "string",
  "message": "string"
}

getGuestNotes

Request

Retrieves a guest notes

Query
propertyIDstring

Property ID

guestIDstringrequired

Guest ID

curl -i -X GET \
  'https://tbg-api-docs.vacatia.com/_mock/cloudbeds/getGuestNotes?guestID=string&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 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"
}

putGuestNote

Request

Updates an existing guest note.

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

Property ID

guestIDstring

Guest ID

noteIDstring

Note ID

guestNotestring

Note to be added to guest profile. It's strictly forbidden to send unencrypted payment data through the API. Numeric values longer than 12 characters and considered valid by Luhn's algorithm will be rejected.

curl -i -X PUT \
  https://tbg-api-docs.vacatia.com/_mock/cloudbeds/putGuestNote \
  -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 guestID=string \
  -d noteID=string \
  -d guestNote=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"
}

deleteGuestNote

Request

Archives an existing guest note.

Query
propertyIDstring

Property ID

guestIDstringrequired

Guest ID

noteIDstringrequired

Note ID

curl -i -X DELETE \
  'https://tbg-api-docs.vacatia.com/_mock/cloudbeds/deleteGuestNote?guestID=string&noteID=string&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

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"
}

putGuest

Request

Updates an existing guest with information provided. At least one information field is required for this call.

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

Property ID

guestIDstring

Valid Guest ID

guestFirstNamestring or null
guestLastNamestring or null
guestGenderstring or null
Enum"M""F""N/A"
guestEmailstring or null
guestPhonestring or null
guestCellPhonestring or null
guestAddress1string or null
guestAddress2string or null
guestCitystring or null
guestCountrystring or null

ISO-Code for Country (2 characters)

guestStatestring or null
guestZipstring or null
guestBirthDatestring or null(date)
guestDocumentTypestring or null

It is mandatory to send all document information
na - non selection
dni - Identity card
nie - Residence permit

Enum"na""driver_licence""student_id""passport""dni""nie""social_security_card"
guestDocumentNumberstring or null

(mandatory when guestDocumentType is sent)

guestDocumentIssueDatestring or null(date)

(mandatory when guestDocumentType is sent)

guestDocumentIssuingCountrystring or null

ISO-Code for Country (2 characters) (mandatory when guestDocumentType is sent)

guestDocumentExpirationDatestring or null(date)

(mandatory when guestDocumentType is sent)

guestCustomFieldsArray of objects or null
guestCompanyNamestring or null

Guest company name

guestCompanyTaxIdstring or null

Guest company tax ID

guestTaxIdstring or null

Guest tax ID unencrypted payment data through the API. Numeric values longer than 12 characters and considered valid by Luhn's algorithm will be rejected.

curl -i -X PUT \
  https://tbg-api-docs.vacatia.com/_mock/cloudbeds/putGuest \
  -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 guestID=string \
  -d guestFirstName=string \
  -d guestLastName=string \
  -d guestGender=M \
  -d guestEmail=string \
  -d guestPhone=string \
  -d guestCellPhone=string \
  -d guestAddress1=string \
  -d guestAddress2=string \
  -d guestCity=string \
  -d guestCountry=string \
  -d guestState=string \
  -d guestZip=string \
  -d guestBirthDate=2019-08-24 \
  -d guestDocumentType=na \
  -d guestDocumentNumber=string \
  -d guestDocumentIssueDate=2019-08-24 \
  -d guestDocumentIssuingCountry=string \
  -d guestDocumentExpirationDate=2019-08-24 \
  -d 'guestCustomFields=[object Object]' \
  -d guestCompanyName=string \
  -d guestCompanyTaxId=string \
  -d guestTaxId=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), or in case any warning message is needed. If success = true, it usually does not exist.

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

postGuestDocument

Request

Attaches a document to a guest

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

Property ID

guestIDstring

Guest 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/postGuestDocument \
  -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 guestID=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"
  }
}

postGuest

Request

Adds a guest to reservation as an additional guest.

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

Property ID

reservationIDstring

Reservation ID

guestFirstNamestring
guestLastNamestring
guestGenderstring or null
Enum"M""F""N/A"
guestEmailstring
guestPhonestring or null
guestCellPhonestring or null
guestAddress1string or null
guestAddress2string or null
guestCitystring or null
guestCountrystring

ISO-Code for Country (2 characters)

guestStatestring or null
guestZipstring or null
guestBirthDatestring or null(date)
guestDocumentTypestring or null

Document Type
dni - Identity card
nie - Residence permit
na - non selection

Enum"dni""driver_license""na""nie""passport""social_security_card""student_id"
guestDocumentNumberstring or null

(mandatory when guestDocumentType is sent)

guestDocumentIssueDatestring or null(date)

(mandatory when guestDocumentType is sent)

guestDocumentIssuingCountrystring or null

Valid ISO-Code for Country (2 characters) (mandatory when guestDocumentType is sent)

guestDocumentExpirationDatestring or null(date)

(mandatory when guestDocumentType is sent)

customFieldsArray of objects or null

Only guest custom fields are allowed.

guestNotestring or null

Note to be added to the Guest

reservationNotestring or null

Note to be added only to the Reservation.

guestCompanyNamestring or null

Guest company name

guestCompanyTaxIdstring or null

Guest company tax ID

guestTaxIdstring or null

Guest tax ID

curl -i -X POST \
  https://tbg-api-docs.vacatia.com/_mock/cloudbeds/postGuest \
  -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 guestFirstName=string \
  -d guestLastName=string \
  -d guestGender=M \
  -d guestEmail=string \
  -d guestPhone=string \
  -d guestCellPhone=string \
  -d guestAddress1=string \
  -d guestAddress2=string \
  -d guestCity=string \
  -d guestCountry=string \
  -d guestState=string \
  -d guestZip=string \
  -d guestBirthDate=2019-08-24 \
  -d guestDocumentType=dni \
  -d guestDocumentNumber=string \
  -d guestDocumentIssueDate=2019-08-24 \
  -d guestDocumentIssuingCountry=string \
  -d guestDocumentExpirationDate=2019-08-24 \
  -d 'customFields=[object Object]' \
  -d guestNote=string \
  -d reservationNote=string \
  -d guestCompanyName=string \
  -d guestCompanyTaxId=string \
  -d guestTaxId=string

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

guestIDstring or null

Returns the Guest ID if the request could be completed successfully

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,
  "guestID": "string",
  "message": "string"
}

postGuestsToRoom

Request

Assigns guest(s) to a room in a reservation and adds these guests as additional guests.

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

Property ID

reservationIDstring

Reservation ID

roomIDinteger

Room ID already assigned to Reservation

guestIDsstring

Guest ID(s) to be assigned to room. If more than one, send as comma-separated, i.e. 37,345,89

removeGuestIDsstring or null

If sent, will remove guest ID(s) before adding guests sent in guestIDs parameter. If more than one, send as comma-separated, i.e. 37,345,89. Main Guest is never removed.

removeAllboolean or null

If set true, will remove all guests assigned to roomID before assigning guests sent in guestIDs parameter. Main Guest is never removed.

curl -i -X POST \
  https://tbg-api-docs.vacatia.com/_mock/cloudbeds/postGuestsToRoom \
  -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 roomID=0 \
  -d guestIDs=string \
  -d removeGuestIDs=string \
  -d removeAll=true

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"
}

postGuestPhoto

Request

Attaches a photo to a guest

Bodyapplication/x-www-form-urlencoded
guestIDstring

Guest Unique Identifier

filestring(binary)

Form-based File Upload
Allowed file types: *.jpg, *.jpeg, *.png, *.gif
Allowed max file size: 15MB

curl -i -X POST \
  https://tbg-api-docs.vacatia.com/_mock/cloudbeds/postGuestPhoto \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d guestID=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"
  }
}

Hotel

Operations

HouseAccount

Operations

Housekeeping

Operations

Integration

Operations

Invoices

Operations

Item

Operations

Package

Operations

Payment

Operations

Rate

Operations

Reservation

Operations

Room

Operations

Taxes and Fees

Operations

User

Operations