Table of Contents | ||
---|---|---|
|
MyGuest Api
Version 2 of the MyGuest API has been created to allow for interconnecting of our existing services into the MyGuest application by creating endpoints to support the creation, updating and retrieval of requests and can be further expanded as scope requires. Currently the API is designed for internal consumption from other BC services, however endpoints and calls are being written in such a way that they could opened up to third party developers at a later date.
Test and Production
In test, a chron job will run every 5 min if it's not commented out. You can watch the queue at https://adminonline-test.bookingcenter.com/myguest_queue.phtml?port=2. You can see the history at https://adminonline-test.bookingcenter.com/myguest_history.phtml?port=2
...
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.
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
User Agent
andX-BookingCenter-API-Key
headers on your requests.
API Level Rate Limiting
If an API endpoint has a specific limit, you will receive a 405 Method Not Allowed
or 429 Too Many Requests
error if you exceed it. Endpoint rate limits are included in that API’s documentation.
Technical Support
When a system (System Trigger, MyBooking, AirBnBBookingCenter, etc) places a message to be processed by the API, we view these in the Que | MyGuest Que where we can see about any errors or pending messages. This is the place to verify whether a System placed the correct message in or not.
...
All endpoints and calls require authentication in the form of a login and key pair that are defined in the MyGuest app under Connected Apps. The api_login can be defined as either a string, or an integer, however the api_key must always be in UUID format.
If the call method is GET it needs to be included in the url string as shown in the following example
Code Block |
---|
https://manage.bookingcenter.com/api/v2/requests/show/2/281?api_login=1123457&api_key=f4f7ca6c-72b7-4b1c-921e-f31243c2b5ce |
For all other call methods, it must be included in the request headers
...
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. Mappedto form name and category in MyGuests. If not found a new form will be created |
...
Code Block |
---|
{ "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": "AirbnbBookingCenter", "message_thread": "597470647", "guest_notify": false, "form_name": "Self Checkin" } } |
...
Code Block |
---|
{ "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": "AirbnbBookingCenter", "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" } } } |
...
Type | Action | Service | Request Message Text (<2000 ctrs) | Parent System | MyGuest Action. *note: If Request status was closed, an update will re-open the Request. If there is no Request the API finds, the API creates a new Request. If multiple BKs have open Req Tix, API updates the last one and ignores prior Req tickets of same Type. |
---|---|---|---|---|---|
1 | New Request | Self Checkin Letter Generated | "SMS Self Checkin message queued" | System Triggers for all Arriving Self Checkin BKs and where new BK arrival = today | Create or Update (if multiple 'edits' occur, the Request might already exist) MyBookings has no role in this step. |
2 | Request Updated | Self Checkin Letter Signed | Self Checkin Letter Signed" | MyBooking | Update (what was created in Type=1) |
3 | Request Completed | Self Checkin Booking Checked In | "Self Checkin Booking Checked In" | MyBooking | Set Complete (what was created in Type=1) |
4 | Request Completed | Self Checkin Booking Cancelled | "Self Checkin Booking Cancelled" | MyBooking | Update (what was created in Type=1) |
5 | Request Updated | Self Checkin Booking Edited | Guest Details: "Self Checkin Guest Details Updated" Payment Details: "Self Checkin Booking Edited (CC Info)" | MyBooking | Update (what was created in Type=1) |
6 | Request Updated | Self Checkin Credit Card Declined | MyBooking | Update (what was created in Type=1) | |
7 | New Request | e-Sign Letter Generated | Auto Letters (won't capture same day BK=arrival 'today') | Create | |
8 | Request Completed | e-Sign Letter Signed | MyBooking | Set Complete (what was created in Type=7) | |
9 | Airbnb BookingCenter Incoming Message | Whatever AirBnB BookingCenter sends and the API | Airbnb BookingCenter API | Create or Update | |
10 | Airbnb BookingCenter Outgoing Message | What is placed in the Guest Notes section of the Request | MyGuest | Reply via Airbnb BookingCenter API | |
20 | New Request | Housekeeping Scheduled | Note that Booking: (href to Booking ID) has been booked, prepare for | Auto Letters (won't capture same day BK=arrival 'today') | Create |
21 | Request Updated | Housekeeping Cancelled | The booking was cancelled | Auto Letters (won't capture same day BK=arrival 'today') | Set Complete (what was created in Type=20) |
22 | New Request | Housekeeping Requested | Note that Room: (insert Room ID and Description) needs to be cleaned. | MyPMS | Create |
23 | Request Updated | Housekeeping Request Cancelled | Note that Room: (insert Room ID and Description) needs to be cleaned. | MyPMS | Set Complete (what was created in Type=22) |
24 | Request Updated | Housekeeping Request Completed | Note that Room: (insert Room ID and Description) has been cleaned. | MyPMS | Set Complete (what was created in Type=22) |
30 | New Request | Booking Made | Note the new booking created, Booking: (href to Booking ID) | Auto Letters (won't capture same day BK=arrival 'today') | Create |
31 | Request Updated | Booking Cancelled | Note that Booking: (href to Booking ID) was cancelled. | Auto Letters (won't capture same day BK=arrival 'today') | Create or Update |
32 | Request Updated | Booking Dates Edited | Note that Booking: (href to Booking ID) has edited their stay dates. | Auto Letters (won't capture same day BK=arrival 'today') | Update (what was created in Type=30) |
...