Introduction
Welcome to the BookingCenter MyGuest API Partner Documentation! The APIs documented here allow you to programmatically:
- Create a Request
- Manage a Request
- Receive Request Information
- Receive Staff Information
- Receive Form Information
- Receive Category Information
Terminology
The following terms are used throughout API documentation:
- BookingCenter Partner Manager — Your Partner Manager helps get you set up to use the API.
- Property — The property the Partner will be accessing or managing information for. The property grants MyGuest API access to the Partner and their Partner Application.
- Partner Application — The software developed by Partner that consumes the MyGuest APIs to manage listings on a host's behalf.
- Partner — Develops and manages the Partner application. Partners are the target audience for this documentation.
Basic API Usage Steps
- Your BookingCenter Partner Manager approves your application for use and will provide you with your Api Credentials.
- The Property grants the Partner Application permission to manage their property account via the API.
- Your application should now be set up and, depending on authorization and permissions, be able to:
- Create and update requests (requests)
- Retrieve a list of available properties (properties) that have authorized partner application access.
- Access available request forms (forms) for the specified property.
- Access available staff (staff) for the specified property.
- Access available categories (categories) for the specified property.
API Development Cycle
- Acceptance into the Api Partner Program
- Partner Manager provides credentials to development environment
- The Property grants the Partner Application permission to manage their property account via the API.
Authentication:
All endpoints require authentication in the form of a login and key pair that were provided upon Partner registration. The api_login can be defined as either a string, or an integer, however the api_key must always be in UUID format.
it must be included in the request headers
x-api-login: 1123457 x-api-key: f4f7ca6c-72b7-4b1c-921e-f31243c2b5ce
Failure to include valid credentials as described will return a http status code 401 with a response Unauthorized.
Rate Limiting
To ensure API stability and prevent abuse, BookingCenter enforces rate limits at the partner level. Your application is responsible for operating within these rate limits. Once a rate limit has been exceeded, no more requests are handled until the limit expires. Attempting to issue requests repeatedly beyond the limit could result in your application being blocked for a longer period, other legitimate requests being rejected, and/or the IP address being blacklisted.
If you encounter issues with rate limits for your application, please ensure you have taken the following or similar actions:
- Build a queuing system to ensure that you don’t exceed the limits.
- Ensure that you do exponential backoff if you do exceed a rate limit.
- Ensure that the you have the
x-api-login
and x-api-key headers on your requests.
In the event the application exceeds the API Rate limiting an 429 error will be returned with a `retry-after` element notifying the application after the UTC time in which the API will accept new requests from it. A sample 429 rate limit message is provided below.
{ "api_version": 3, "status": "failed", "errors": { "code": 429, "message": "Too many requests", "retry-after": "2020-02-11T02:44:47+00:00" }, "request_uuid": "b84ecfde-19de-4ede-a96a-91f86c623841" }
Technical Support
To assist our partners' integration to our API platform, please use our support system at our Online Support Portal.
Endpoints:
Forms
Parameter | Description |
---|---|
room | Room number assigned to the booking without the siteid. Cannot be null |
booking_id | Primary Booking ID for the request, omitting the siteid. Cannot be null |
details | Details of the request. 2000 characters maximum. |
email | Guest Email . This is the primary key that will be used to match an existing guest or create a new guest in MyGuests |
name | Guest Name |
phone | Guest Primary Phone. Recommended to default to mobile number to support eventual SMS functionality |
rewards_number | Optional field for supporting a hotels rewards or loyalty program. Can be sent as null or omitted if not used. |
message_channel string optional | Used when created a Request related to a messaging API. |
message_thread string optional | Used when created a Request related to a messaging API. Optional field which can be sent as null or omitted if not used. String should match the thread id provided by the OTA for the messaging thread. If used `message_channel` element is required. |
guest_notify | Boolean to determine if we send an email to the guest on new request creation. Accepted values false or true |
form_name | One of "Self Checkin" , "E-Sign" case insensitive. Mapped to form name and category in MyGuests. If not found a new form will be created |
Staff
Parameter | Description |
---|---|
room | Room number assigned to the booking without the siteid. Cannot be null |
booking_id | Primary Booking ID for the request, omitting the siteid. Cannot be null |
details | Details of the request. 2000 characters maximum. |
email | Guest Email . This is the primary key that will be used to match an existing guest or create a new guest in MyGuests |
name | Guest Name |
phone | Guest Primary Phone. Recommended to default to mobile number to support eventual SMS functionality |
rewards_number | Optional field for supporting a hotels rewards or loyalty program. Can be sent as null or omitted if not used. |
message_channel string optional | Used when created a Request related to a messaging API. |
message_thread string optional | Used when created a Request related to a messaging API. Optional field which can be sent as null or omitted if not used. String should match the thread id provided by the OTA for the messaging thread. If used `message_channel` element is required. |
guest_notify | Boolean to determine if we send an email to the guest on new request creation. Accepted values false or true |
form_name | One of "Self Checkin" , "E-Sign" case insensitive. Mapped to form name and category in MyGuests. If not found a new form will be created |
Message Structure
Create Request
POST v2/requests/create/{hotelid}
Request Body Parameters within
Parameter | Description |
---|---|
room | Room number assigned to the booking without the siteid. Cannot be null |
booking_id | Primary Booking ID for the request, omitting the siteid. Cannot be null |
details | Details of the request. 2000 characters maximum. |
email | Guest Email . This is the primary key that will be used to match an existing guest or create a new guest in MyGuests |
name | Guest Name |
phone | Guest Primary Phone. Recommended to default to mobile number to support eventual SMS functionality |
rewards_number | Optional field for supporting a hotels rewards or loyalty program. Can be sent as null or omitted if not used. |
message_channel string optional | Used when created a Request related to a messaging API. |
message_thread string optional | Used when created a Request related to a messaging API. Optional field which can be sent as null or omitted if not used. String should match the thread id provided by the OTA for the messaging thread. If used `message_channel` element is required. |
guest_notify | Boolean to determine if we send an email to the guest on new request creation. Accepted values false or true |
form_name | One of "Self Checkin" , "E-Sign" case insensitive. Mapped to form name and category in MyGuests. If not found a new form will be created |
Example Request
{ "request": { "room": "32", "booking_id": "1332025-4X", "details": "credit card declined", "email": "jchieppa@gmail.com", "name": "Joe Banks", "phone": "7075551414", "rewards_number": null, "message_channel": "BookingCenter", "message_thread": "597470647", "guest_notify": false, "form_name": "Self Checkin" } }
Example Response
{ "api_version": "2", "status": "Success", "requests": { "id": 308, "room": "32", "details": null, "property_id": 2, "status_id": 1, "created_at": "2019-01-14 23:26:21", "updated_at": "2019-01-14 23:26:21", "category_id": 21, "completed_at": null, "first_time": 1, "staff_id": null, "guest_id": 13, "booking_id": "1332025-4X", "message_channel": "BookingCenter", "message_thread": "597470647", "assigned": null, "status": { "id": 1, "name": "New", "created_at": "2014-11-14 02:23:46", "updated_at": "2014-11-14 02:23:46" }, "guest": { "id": 13, "name": "Joe Banks", "email": "jchieppa@gmail.com", "phone": "7075551414", "rewards_number": "0", "created_at": "2018-02-07 10:49:28", "updated_at": "2019-01-11 22:09:36" }, "staff": null, "category": { "id": 21, "name": "Self Checkin", "department_id": 7, "created_at": "2019-01-14 22:21:55", "updated_at": "2019-01-14 22:21:55", "identifier": "21" } } }