Booking APIs

Booking APIs are GET and POST request APIs that can be used to create and modify hotel reservations. In order to access the booking APIs you will need to have access to the Booking scope.

All of the booking APIs are secured by OAuth. The following should be included within the header of all your requests in order to gain access to the data:

• Authorization - An active bearer token.
  • Note: Tokens are unique to a specific hotel chain. If your application works with more than one hotel chain within Rover Connect you will need to make sure that the bearer token corresponds to the hotel chain you attempting to retrieve data for.
• API-Version - An API-Version should always be included within your request. (e.g. "1.0")

Available APIs:

• Guest Information (guests/id)
• List of all Reservations (reservations)
• List of reservations with status "Due In"
• List of reservations with status "Checked In"
• Reservation Lookup

All booking APIs are prefixed with the following URL:

https://api.stayntouch.com/connect/

Guest Information (guests/id)

Description

This method will return the details for a specific guest within the hotel chain.

Request

There are no query parameters for this method.

Response

• https://pms.stayntouch/connect/guests/620202

{
	"id": 620202,
	"first_name": "John",
	"last_name": "Smith",
	"email": "sample@sample.com",
	"address": {
		"address1": "123 First Street",
		"address2": null,
		"address3": null,
		"city": "Somecity",
		"state": "Somestate",
		"postal_code": "55555",
		"country": "US"
	},
	"birthday": "2017-08-15",
	"is_vip": false,
	"title": "Mr.",
	"works_at": "StayNTouch",
	"job_title": "Employee",
	"nationality": "US",
	"home_phone": null,
	"language": "EN",
	"opted_promotional_emails": false,
	"mobile_phone": null
}

Media type: application/json

Type: object

• id: (integer)
  • Guest identifier
• address: (object)
• address1: (string)
  • Address line 1 of 3
• address2: (string)
  • Address line 2 of 3
• address3: (string)
  • Address line 3 of 3
• city: (string)
  • City
• state: (string)
  • State
• postal_code: (string)
  • Postal code
• country: (string)
  • Country abbreviation (ISO)

• email: (string)
  • Guest's email
• title: (string)
  • Guest's title
• first_name: (string)
  • Guest's first name
• last_name: (string)
  • Guest's last name
• home_phone: (string)
  • Guest's home phone
• mobile_phone: (string)
  • Guest's mobile phone
• nationality: (string)
  • Guest's nationality
• language: (string)
  • Guest's preferred language
• company: (string)
  • Guest's company
• job_title: (string)
  • Guest's job title
• birthday: (string)
  • Guest's birthday
• vip: (boolean)
  • Whether the guest is a VIP
• opted_promotional_emails: (boolean)
  • Whether the guest has chosen to receive promotional emails

Possible Errors

• UNAUTHORIZED (401)
  • Missing API Version - This error will occur if you did not include an API-Version within your request header. An API-Version is always expected and required.
• UNAUTHORIZED (401)
  • Invalid or expired access token - This error will occur if there was a problem with the access token that you included within your request header.
    • If your access token has expired, which occurs every 30 days, you can request a new one using (/oauth/token) and passing in the refresh token you received previously.
    • You will receive this error if you are attempting to gain access to a hotel chain for which the given access token does not correspond.
• INVALID RECORD (404)
  • Couldn't find guestdetail - This error will occur if you are attempting to retrieve details for a guest with an ID that does not currently exist within the system.

List of all Reservations (reservations)

Description

This method can be used to find a reservation or retrieve a list of reservations.

Request

The following should be used as GET parameters:

• hotel_id (string) - filter to reservations to include those only for a specific hotel
• confirmation_number (string) - find a reservation by unique confirmation number
• alt_confirmation_number (string) - find a reservation by alternate confirmation number (applicable for reservations booked through an external booking service)
• last_name (string) - find a reservation by a guest's last name
• departure_date (date-only) - filter reservations by departure_date
• credit_card_last_4 (string) - filter reservations to include only those with a specific card
• page (integer - default: 1) - If the per_page parameter is also set or your chain consists of more than 25 reservations your response will become paginated. This parameter can be used to access a specific page within the pagination.
• per_page (integer - default: 25) - Use this parameter to set number of results you want in each page of the response.

Hints:

• If you are trying to find a single reservation, you will almost always want to use more than one of these parameters to filter reservations as the same guests may have multiple reservations within the hotel chain. It is recommended to find a reservation using either the confirmation number/alternate confirmation number OR the guest's last name and departure date.

Response

• https://pms-dev.stayntouch.com/connect/reservations?hotel_id=105&confirmation_number=106285

{
    "results": [
        {
            "id": 1662658,
            "hotel_id": 105,
            "confirmation_number": "106285",
            "status": "RESERVED",
            "arrival_date": "2017-08-25",
            "arrival_time": "11:48:02",
            "departure_date": "2017-08-25",
            "departure_time": "14:31:07",
            "room": {
                "id": 14740,
                "number": "12608",
                "room_type_id": 144,
                "status": "DIRTY",
                "service_status": "IN_SERVICE",
                "occupied": false
            },
            "stay_dates": [
                {
                    "date": "2017-08-25",
                    "amount": "200.00",
                    "rate_id": 3717,
                    "room_type_id": 144,
                    "adults": 1,
                    "children": 0
                }
            ],
            "guests": [
                {
                    "id": 613452,
                    "is_primary": true,
                    "first_name": "John",
                    "last_name": "Smith",
                    "email": "john@smith.com"
                }
            ],
            "company": null,
            "travel_agent": null,
            "upsell_applied": true,
            "early_check_in_applied": false,
            "late_check_out_applied": false
        }
    ],
    "total_count": 6286
}

Media type: application/json

Type: object

• id: (integer)
  
  • Reservation identifier
• hotel_id: (integer)
  • Hotel identifier
• confirmation_number: (string)
  • Rover confirmation number
• status: (one of RESERVED, CHECKEDIN, CHECKEDOUT, NOSHOW, CANCELED, PRE_CHECKIN)
  • Status of the reservation
• arrival_date: (date-only)
  • Expected check-in date
• arrival_time: (time-only)
  • Expected check-in time
• departure_date: (date-only)
  • Expected check-out date
• departure_time: (time-only)
  • Expected check-in time
• room: (object)
  
  • id: (integer)
    • Room identifier
  • number: (string)
    
    • Room number
  • room_type_id: (integer)
    • Room type identifier
  • status: (one of CLEAN, INSPECTED, DIRTY, OO, OS, PICKUP)
    • Housekeeping status of the room
  • service_status: (one of IN_SERVICE, OUT_OF_ORDER, OUT_OF_SERVICE)
    • Room service status
  • occupied: (boolean)
    • Occupancy status which is set to true when the room is assigned
• stay_dates: (array)
  
  • date: (date-only)
    • Stay date
  • amount: (string)
    • Amount for the night
  • rate_id: (integer)
    • Rate identifier
  • room_type_id: (integer)
    • Room type identifier
  • adults: (integer)
    • Number of adults
  • children: (integer)
    • Number of children
• guests: (array)
  
  • id: (string)
    • Guest identifier
  • is_primary: (boolean)
    • Whether the guest is primary
  • first_name: (string)
    • Guest's first name
  • last_name: (string)
    • Guest's last name
  • email: (string)
    • Guest's email
• company: (object)
  
  • id: (integer)
    • Company identifier
  • account_number: (string)
    • Account number unique to company
• travel_agent: (object)
  
  • id: (integer)
    • Travel agent ID
  • account_number: (string)
    • Account number unique to travel agent
• upsell_applied: (boolean)
  • Indicates if a guest chose to upsell
• early_check_in_applied: (boolean)
  • Indicates if early check-in was purchased
• late_check_out_applied: (boolean)
  • Indicates if late check-out was purchased

Possible Errors

• UNAUTHORIZED (401)
  • Missing API Version - This error will occur if you did not include an API-Version within your request header. An API-Version is always expected and required.
• UNAUTHORIZED (401)
  • Invalid or expired access token - This error will occur if there was a problem with the access token that you included within your request header.
    • If your access token has expired, which occurs every 30 days, you can request a new one using (/oauth/token) and passing in the refresh token you received previously.
    • You will receive this error if you are attempting to gain access to a hotel chain for which the given access token does not correspond.

List of all Reservations with status "Due In" (reservations/due_in)

Description

This method can be used to find a reservation or retrieve a list of reservations that are due in on the current day local to the hotel.

Request

The following should be used as GET parameters:

• hotel_id required (string) - filter to reservations to include those only for a specific hotel
• confirmation_number (string) - find a reservation by unique confirmation number
• alt_confirmation_number (string) - find a reservation by alternate confirmation number (applicable for reservations booked through an external booking service)
• last_name (string) - find a reservation by a guest's last name
• departure_date (date-only) - filter reservations by departure_date
• credit_card_last_4 (string) - filter reservations to include only those with a specific card
• page (integer - default: 1) - If the per_page parameter is also set or your chain consists of more than 25 reservations your response will become paginated. This parameter can be used to access a specific page within the pagination.
• per_page (integer - default: 25) - Use this parameter to set number of results you want in each page of the response.

Hints:

• If you are trying to find a single reservation, you will almost always want to use more than one of these parameters to filter reservations as the same guests may have multiple reservations within the hotel chain. It is recommended to find a reservation using either the confirmation number/alternate confirmation number OR the guest's last name and departure date.

Response

• https://pms-dev.stayntouch.com/connect/reservations/due_in?hotel_id=105&page=1&per_page=1

{
    "results": [
        {
            "id": 1662658,
            "hotel_id": 105,
            "confirmation_number": "106285",
            "status": "RESERVED",
            "arrival_date": "2017-08-25",
            "arrival_time": "11:48:02",
            "departure_date": "2017-08-25",
            "departure_time": "14:31:07",
            "room": {
                "id": 14740,
                "number": "12608",
                "room_type_id": 144,
                "status": "DIRTY",
                "service_status": "IN_SERVICE",
                "occupied": false
            },
            "stay_dates": [
                {
                    "date": "2017-08-25",
                    "amount": "200.00",
                    "rate_id": 3717,
                    "room_type_id": 144,
                    "adults": 1,
                    "children": 0
                }
            ],
            "guests": [
                {
                    "id": 613452,
                    "is_primary": true,
                    "first_name": "John",
                    "last_name": "Smith",
                    "email": "john@smith.com"
                }
            ],
            "company": null,
            "travel_agent": null,
            "upsell_applied": true,
            "early_check_in_applied": false,
            "late_check_out_applied": false
        }
    ],
    "total_count": 100
}

Media type: application/json

Type: object

• id: (integer)
  
  • Reservation identifier
• hotel_id: (integer)
  • Hotel identifier
• confirmation_number: (string)
  • Rover confirmation number
• status: (one of RESERVED, CHECKEDIN, CHECKEDOUT, NOSHOW, CANCELED, PRE_CHECKIN)
  • Status of the reservation
• arrival_date: (date-only)
  • Expected check-in date
• arrival_time: (time-only)
  • Expected check-in time
• departure_date: (date-only)
  • Expected check-out date
• departure_time: (time-only)
  • Expected check-in time
• room: (object)
  
  • id: (integer)
    • Room identifier
  • number: (string)
    
    • Room number
  • room_type_id: (integer)
    • Room type identifier
  • status: (one of CLEAN, INSPECTED, DIRTY, OO, OS, PICKUP)
    • Housekeeping status of the room
  • service_status: (one of IN_SERVICE, OUT_OF_ORDER, OUT_OF_SERVICE)
    • Room service status
  • occupied: (boolean)
    • Occupancy status which is set to true when the room is assigned
• stay_dates: (array)
  
  • date: (date-only)
    • Stay date
  • amount: (string)
    • Amount for the night
  • rate_id: (integer)
    • Rate identifier
  • room_type_id: (integer)
    • Room type identifier
  • adults: (integer)
    • Number of adults
  • children: (integer)
    • Number of children
• guests: (array)
  
  • id: (string)
    • Guest identifier
  • is_primary: (boolean)
    • Whether the guest is primary
  • first_name: (string)
    • Guest's first name
  • last_name: (string)
    • Guest's last name
  • email: (string)
    • Guest's email
• company: (object)
  
  • id: (integer)
    • Company identifier
  • account_number: (string)
    • Account number unique to company
• travel_agent: (object)
  
  • id: (integer)
    • Travel agent ID
  • account_number: (string)
    • Account number unique to travel agent
• upsell_applied: (boolean)
  • Indicates if a guest chose to upsell
• early_check_in_applied: (boolean)
  • Indicates if early check-in was purchased
• late_check_out_applied: (boolean)
  • Indicates if late check-out was purchased

Possible Errors

• UNAUTHORIZED (401)
  • Missing API Version - This error will occur if you did not include an API-Version within your request header. An API-Version is always expected and required.
• UNAUTHORIZED (401)
  • Invalid or expired access token - This error will occur if there was a problem with the access token that you included within your request header.
    • If your access token has expired, which occurs every 30 days, you can request a new one using (/oauth/token) and passing in the refresh token you received previously.
    • You will receive this error if you are attempting to gain access to a hotel chain for which the given access token does not correspond.

List of all Reservations with status "Checked In" (reservations/checked_in)

Description

This method can be used to find a reservation or retrieve a list of reservations that are checked in on the current business day local to the hotel.

Request

The following should be used as GET parameters:

• hotel_id required (string) - filter to reservations to include those only for a specific hotel
• confirmation_number (string) - find a reservation by unique confirmation number
• alt_confirmation_number (string) - find a reservation by alternate confirmation number (applicable for reservations booked through an external booking service)
• last_name (string) - find a reservation by a guest's last name
• departure_date (date-only) - filter reservations by departure_date
• credit_card_last_4 (string) - filter reservations to include only those with a specific card
• page (integer - default: 1) - If the per_page parameter is also set or your chain consists of more than 25 reservations your response will become paginated. This parameter can be used to access a specific page within the pagination.
• per_page (integer - default: 25) - Use this parameter to set number of results you want in each page of the response.

Hints:

• If you are trying to find a single reservation, you will almost always want to use more than one of these parameters to filter reservations as the same guests may have multiple reservations within the hotel chain. It is recommended to find a reservation using either the confirmation number/alternate confirmation number OR the guest's last name and departure date.

Response

• https://pms-dev.stayntouch.com/connect/reservations/checked_in?hotel_id=105&page=1&per_page=1

{
    "results": [
        {
            "id": 1662658,
            "hotel_id": 105,
            "confirmation_number": "106285",
            "status": "CHECKEDIN",
            "arrival_date": "2017-08-25",
            "arrival_time": "11:48:02",
            "departure_date": "2017-08-25",
            "departure_time": "14:31:07",
            "room": {
                "id": 14740,
                "number": "12608",
                "room_type_id": 144,
                "status": "DIRTY",
                "service_status": "IN_SERVICE",
                "occupied": false
            },
            "stay_dates": [
                {
                    "date": "2017-08-25",
                    "amount": "200.00",
                    "rate_id": 3717,
                    "room_type_id": 144,
                    "adults": 1,
                    "children": 0
                }
            ],
            "guests": [
                {
                    "id": 613452,
                    "is_primary": true,
                    "first_name": "John",
                    "last_name": "Smith",
                    "email": "john@smith.com"
                }
            ],
            "company": null,
            "travel_agent": null,
            "upsell_applied": true,
            "early_check_in_applied": false,
            "late_check_out_applied": false
        }
    ],
    "total_count": 6286
}

Media type: application/json

Type: object

• id: (integer)
  
  • Reservation identifier
• hotel_id: (integer)
  • Hotel identifier
• confirmation_number: (string)
  • Rover confirmation number
• status: (one of RESERVED, CHECKEDIN, CHECKEDOUT, NOSHOW, CANCELED, PRE_CHECKIN)
  • Status of the reservation
• arrival_date: (date-only)
  • Expected check-in date
• arrival_time: (time-only)
  • Expected check-in time
• departure_date: (date-only)
  • Expected check-out date
• departure_time: (time-only)
  • Expected check-in time
• room: (object)
  
  • id: (integer)
    • Room identifier
  • number: (string)
    
    • Room number
  • room_type_id: (integer)
    • Room type identifier
  • status: (one of CLEAN, INSPECTED, DIRTY, OO, OS, PICKUP)
    • Housekeeping status of the room
  • service_status: (one of IN_SERVICE, OUT_OF_ORDER, OUT_OF_SERVICE)
    • Room service status
  • occupied: (boolean)
    • Occupancy status which is set to true when the room is assigned
• stay_dates: (array)
  
  • date: (date-only)
    • Stay date
  • amount: (string)
    • Amount for the night
  • rate_id: (integer)
    • Rate identifier
  • room_type_id: (integer)
    • Room type identifier
  • adults: (integer)
    • Number of adults
  • children: (integer)
    • Number of children
• guests: (array)
  
  • id: (string)
    • Guest identifier
  • is_primary: (boolean)
    • Whether the guest is primary
  • first_name: (string)
    • Guest's first name
  • last_name: (string)
    • Guest's last name
  • email: (string)
    • Guest's email
• company: (object)
  
  • id: (integer)
    • Company identifier
  • account_number: (string)
    • Account number unique to company
• travel_agent: (object)
  
  • id: (integer)
    • Travel agent ID
  • account_number: (string)
    • Account number unique to travel agent
• upsell_applied: (boolean)
  • Indicates if a guest chose to upsell
• early_check_in_applied: (boolean)
  • Indicates if early check-in was purchased
• late_check_out_applied: (boolean)
  • Indicates if late check-out was purchased

Possible Errors

• UNAUTHORIZED (401)
  • Missing API Version - This error will occur if you did not include an API-Version within your request header. An API-Version is always expected and required.
• UNAUTHORIZED (401)
  • Invalid or expired access token - This error will occur if there was a problem with the access token that you included within your request header.
    • If your access token has expired, which occurs every 30 days, you can request a new one using (/oauth/token) and passing in the refresh token you received previously.
    • You will receive this error if you are attempting to gain access to a hotel chain for which the given access token does not correspond.

Reservation Lookup (reservations/id)

Description

This method can be used to get reservation details queried by the reservation identifier.

Request

This method has no query parameters.

Response

• https://pms-dev.stayntouch.com/connect/reservations/1662658

{
    "results": [
        {
            "id": 1662658,
            "hotel_id": 105,
            "confirmation_number": "106285",
            "status": "CHECKEDOUT",
            "arrival_date": "2017-08-25",
            "arrival_time": "11:48:02",
            "departure_date": "2017-08-25",
            "departure_time": "14:31:07",
            "room": {
                "id": 14740,
                "number": "12608",
                "room_type_id": 144,
                "status": "DIRTY",
                "service_status": "IN_SERVICE",
                "occupied": false
            },
            "stay_dates": [
                {
                    "date": "2017-08-25",
                    "amount": "200.00",
                    "rate_id": 3717,
                    "room_type_id": 144,
                    "adults": 1,
                    "children": 0
                }
            ],
            "guests": [
                {
                    "id": 613452,
                    "is_primary": true,
                    "first_name": "John",
                    "last_name": "Smith",
                    "email": "john@smith.com"
                }
            ],
            "company": null,
            "travel_agent": null,
            "upsell_applied": true,
            "early_check_in_applied": false,
            "late_check_out_applied": false
        }
    ],
    "total_count": 6286
}

Media type: application/json

Type: object

• id: (integer)
  
  • Reservation identifier
• hotel_id: (integer)
  • Hotel identifier
• confirmation_number: (string)
  • Rover confirmation number
• status: (one of RESERVED, CHECKEDIN, CHECKEDOUT, NOSHOW, CANCELED, PRE_CHECKIN)
  • Status of the reservation
• arrival_date: (date-only)
  • Expected check-in date
• arrival_time: (time-only)
  • Expected check-in time
• departure_date: (date-only)
  • Expected check-out date
• departure_time: (time-only)
  • Expected check-in time
• room: (object)
  
  • id: (integer)
    • Room identifier
  • number: (string)
    
    • Room number
  • room_type_id: (integer)
    • Room type identifier
  • status: (one of CLEAN, INSPECTED, DIRTY, OO, OS, PICKUP)
    • Housekeeping status of the room
  • service_status: (one of IN_SERVICE, OUT_OF_ORDER, OUT_OF_SERVICE)
    • Room service status
  • occupied: (boolean)
    • Occupancy status which is set to true when the room is assigned
• stay_dates: (array)
  
  • date: (date-only)
    • Stay date
  • amount: (string)
    • Amount for the night
  • rate_id: (integer)
    • Rate identifier
  • room_type_id: (integer)
    • Room type identifier
  • adults: (integer)
    • Number of adults
  • children: (integer)
    • Number of children
• guests: (array)
  
  • id: (string)
    • Guest identifier
  • is_primary: (boolean)
    • Whether the guest is primary
  • first_name: (string)
    • Guest's first name
  • last_name: (string)
    • Guest's last name
  • email: (string)
    • Guest's email
• company: (object)
  
  • id: (integer)
    • Company identifier
  • account_number: (string)
    • Account number unique to company
• travel_agent: (object)
  
  • id: (integer)
    • Travel agent ID
  • account_number: (string)
    • Account number unique to travel agent
• upsell_applied: (boolean)
  • Indicates if a guest chose to upsell
• early_check_in_applied: (boolean)
  • Indicates if early check-in was purchased
• late_check_out_applied: (boolean)
  • Indicates if late check-out was purchased

Possible Errors

• UNAUTHORIZED (401)
  • Missing API Version - This error will occur if you did not include an API-Version within your request header. An API-Version is always expected and required.
• UNAUTHORIZED (401)
  • Invalid or expired access token - This error will occur if there was a problem with the access token that you included within your request header.
    • If your access token has expired, which occurs every 30 days, you can request a new one using (/oauth/token) and passing in the refresh token you received previously.
    • You will receive this error if you are attempting to gain access to a hotel chain for which the given access token does not correspond.
• INVALID RECORD (404)
  • Couldn't find reservation - This error will occur if you are attempting to find a reservation with ID that does not currently exist within the system.
    • Note: The reservation ID inside the URL is different from the confirmation number and alternate confirmation number; however, these can be used to find the ID with a reservation lookup method. (/reservations)