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
Troubleshooting
When a system (System Trigger, MyBooking, AirBnB, 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.
Once the message is processed, and thus we can verify what took place, we view these in the Logging | MyGuest History.
Authentication:
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 |
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.
- Partner completes development and testing against development environment.
- Partner Manager provides credentials for production environment.
- Property grants the Partner Application permission to access 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.
For all other call methods, it must be included in the request headers
...
Failure to include valid credentials as described will return a http status code 401 with a response Unauthorized.
Endpoint Routes:
All endpoints are based off the core url of https://manage.bookingcenter.com/api/
Message Structure
Create Request
Code Block |
---|
POST v2/requests/create/{hotelid} |
Request Body Parameters within
...
room
string
required
...
booking_id
string
required
...
details
string
required
...
email
string
required
...
name
string
required
...
phone
string
required
...
rewards_number
string
optional
...
Optional field for supporting a hotels rewards or loyalty program. Can be sent as null or omitted if not used.
...
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 name of the related OTA Channel i.e. "Airbnb" or "Booking.com" .
If used message_thread element is required.
...
guest_notify
boolean
required
...
form_name
string
required
...
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.
Code Block |
---|
{
"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"
} |
Validation:
Technical Support
To assist partner integration to our API platform, please use our support system at our Online Support Portal. Every API call response contains meta information including the status of the response, api_version and the request_uuid. When requesting technical support please provide the endpoint you are making the call, your formatted request and the full response from the api including the request_uuid.
Sample Success meta information:
Code Block |
---|
"api_version": 3,
"status": "success",
"request_uuid": "35f52462-a3e6-4a37-aaed-c7326932fb3a" |
Sample Error meta information:
Code Block |
---|
{
"api_version": 3,
"status": "failed |
Example Request
Code Block |
---|
{ "request": { "room": "32", "booking_iderrors": "1332025-4X", { "detailsstatus": "credit card declined", 404, "emailtitle": "jchieppa@gmail.comrecord not found", "namedetails": "Joe Banks",no record 345 found" "phone": "7075551414"}, "rewardsrequest_numberuuid": null, "message_channel": "Airbnb", "message_thread": "597470647", "guest_notify": false, "form_name": "Self Checkin" } } |
Example Response
"b0370ef0-3c83-40af-a993-0201f37c33dc"
} |
Endpoints
Properties
Anchor | ||||
---|---|---|---|---|
|
Retrieve All Properties
This call returns all of a properties that have authorized the provider access via the API.
Fetch all Properties as Properties Object array.
Code Block |
---|
GET v3/property |
Request URL Parameters
Parameter | Description |
---|---|
hotel_id | Property Numerical identifier Cannot be null |
Example Response
Code Block |
---|
{ |
Code Block |
{ "api_version": "2", "statusproperties": "Success", [ "requests": { "id": 3082, "roomname": "32A MyPMS Demo Hotel", "details": null, "property_id"site_url": 2"http://Hotel.bookingcenter.com", "status_idtimezone": 1"America/Dawson", "createdcontact_atemail": "2019-01-14 23:26:21",mypms@demohotel.com" "updated_at": "2019-01-14 23:26:21", }, { "category_id": 21, "completed_atid": null3, "first_timename": 1 "Steves Test Property", "staffsite_idurl": null, "http://Hotel.bookingcenter.com", "guest_idtimezone": 13"Africa/Abidjan", "booking_id": "1332025-4X", "message_channel": "Airbnb", "message_thread": "597470647", "contact_email": null "assigned": null}, "status": { "id": 110, "name": "NewLava Ridges Test Property", "createdsite_aturl": "2014-11-14 02:23:46www.lavaridge.org", "updated_attimezone": "2014-11-14 02:23:46" America/Dawson", }, "contact_email": "guest": {lavaridges@email.com" } "id": 13], "nameapi_version": "Joe Banks"3, "emailstatus": "jchieppa@gmail.comsuccess", "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" } } } |
MyGuest Message Queue
While the Api endpoints can be called directly (and may eventually be by third party developers) we will be utilizing a queue to process actions and keep a history.
MG_MESSAGES Table Schema
MG_PKEY is a sequence MG_PKEY_SEQ
...
Name
...
Status Codes
...
Create or Update (if multiple 'edits' occur, the Request might already exist)
MyBookings has no role in this step.
...
Guest Details: "Self Checkin Guest Details Updated"
Payment Details: "Self Checkin Booking Edited (CC Info)"
...
e-Sign Letter Generated
...
Create or Update
...
"request_uuid": "74ec482c-5a37-416b-820e-0c0e52f0a6e7"
} |
Retrieve Single Property
This call returns all of a properties that have authorized the provider access via the API. Properties are returned in a paginated collection which provides a Meta Array with pagination information.
Fetch all Properties as Properties Object array.
Code Block |
---|
GET v3/property/:id |
Request URL Parameters
Parameter | Description |
---|---|
id | The id of the property being retrieved |
Forms
Anchor | ||||
---|---|---|---|---|
|
Retrieve All Forms
This call returns all of a properties forms and the fields associated with each form. Forms are returned in a paginated collection which provides a Meta Array with pagination information.
Fetch a Properties forms as Form Object array.
Code Block |
---|
GET v3/forms |
Request URL Parameters
Parameter | Description |
---|---|
hotel_id | Property Numerical identifier Cannot be null |
limit | The maximum number of forms to return, up to 50. |
Retrieve Single Form
Anchor | ||||
---|---|---|---|---|
|
This call returns a specific form and the form fields associated for the requested.
Fetch a specific form as Form Object array.
Code Block |
---|
GET v3/forms/:form_id |
Request URL Parameters
Parameter | Description |
---|---|
id integer required | The id of the form |
hotel_id |
|
Staff
Anchor | ||||
---|---|---|---|---|
|
Retrieve All Staff
This call returns all available staff by property and their roles. Forms are returned in a paginated collection which provides a Meta Array with pagination information.
Fetch a Properties staff as Staff Object array.
Code Block |
---|
GET v3/staff |
Request URL Parameters
Parameter | Description |
---|---|
hotel_id | Property Numerical identifier Cannot be null |
Retrieve Specific Staff
This call returns all available staff by property and their roles.
Fetch a Properties staff as Staff Object array.
Code Block |
---|
GET v3/staff/:username |
Request URL Parameters
Parameter | Description |
---|---|
username string required | Specific staff username obtained from the retrieve all staff call |
hotel_id | Property Numerical identifier Cannot be null |
Categories
Anchor | ||||
---|---|---|---|---|
|
Retrieve All Categories
This call returns all available form categories including their respective department. Categories are returned in a paginated collection which provides a Meta Array with pagination information.
Fetch a Properties categories as categories Object array.
Code Block |
---|
GET v3/categories |
Request URL Parameters
Parameter | Description |
---|---|
hotel_id |
|
limit | The maximum number of categories to return, up to 50. |
Retrieve Specific Categories
This call returns all available form categories including their respective department.
Fetch a Properties categories as categories Object array.
Code Block |
---|
GET v3/categories/:category_id |
Request URL Parameters
Parameter | Description |
---|---|
id integer required | The category id |
hotel_id |
|
Requests
Anchor | ||||
---|---|---|---|---|
|
Retrieve All Requests
This call returns all requests for property and their roles. Requests are returned in a paginated collection which provides a Meta Array with pagination information.
Fetch a Properties requests as request Object array.
Code Block |
---|
GET v3/requests |
Request URL Parameters
Parameter | Description |
---|---|
hotel_id | Property Numerical identifier Cannot be null |
limit | The maximum number of requests to return, up to 50. |
offset integer optional, default is 0 | The number of requests to skip over, where the ordering is consistent but unspecified. |
status string optional, default is 0 | Filter Requests that match a specific status. Use Unresolved to retrieve all requests that have any status other than completed or cancelled. |
room string optional |
|
rooms array optional |
|
category string optional |
|
Retrieve Single Request
This call returns a specific request for property.
Fetch a Properties request as request Object array.
Code Block |
---|
GET v3/requests/:request_id |
Request URL Parameters
Parameter | Description |
---|---|
id | The request id |
hotel_id | Property Numerical identifier Cannot be null |
Create a Request
This call creates a new request and returns a request object.
Code Block |
---|
POST v3/requests |
Request URL Parameters
Parameter | Description |
---|---|
hotel_id | Property Numerical identifier Cannot be null |
Guest | see list of supported strings |
Category string required | form category name from the categories endpoint |
room string optional | Guest room for their booking |
booking_id string optional | The reservation identifier for the guests stay with the property, if applicable. |
guest_notify boolean required | Should an email be sent to the guest notifying them of this requests creation? Recommended false |
staff_username string optional |
|
status string optional default "New" |
|
form_name string required | Name of the form we are creating this request for from the forms endpoint |
form_fields array required | details of the form request. Needs to match any required form_fields for the specified form_name from the forms forms endpoint |
Example Request
Code Block |
---|
{
"hotel_id": 2,
"room": "32",
"booking_id": "1332025-4X",
"guest": {
"email": "joeb@banks.com",
"name": "Joe Banks",
"phone": "7075551414"
},
"guest_notify": false,
"form_category": "Treatment",
"form_name": "Spa Menu",
"form_fields": {
"Notes": "We'd like hot towels and a room to meditate in",
"swedish1": 2,
"pregnancy2": 1
}
} |
Example Response
Code Block |
---|
{
"requests": {
"id": 878,
"booking_id": "1332025-4X",
"room": "32",
"guest": {
"name": "Joe Banks",
"email": "joeb@banks.com",
"phone_number": "7075551414"
},
"created_at": "2020-02-12 15:43:15",
"updated_at": "2020-02-12 15:43:15",
"length_open": "1 second",
"status": "New",
"assigned": null,
"category": {
"id": 8,
"name": "Treatment"
},
"request_details": [
{
"name": "Notes",
"value": "We'd like hot towels and a room to meditate in",
"amount": null,
"type": "text"
},
{
"name": "Swedish1",
"value": "2",
"amount": "80",
"type": "amount"
},
{
"name": "Pregnancy2",
"value": "1",
"amount": "140",
"type": "amount"
}
],
"comments": {
"guest_comments": [],
"staff_notes": []
}
},
"api_version": 3,
"status": "success",
"request_uuid": "a25a7d79-ba8a-40a3-92a6-02862f7a16c2"
}
|
Update a Request
This call creates a new request and returns a request object.
Code Block |
---|
PUT/PATCH v3/requests/:request_id |
Request URL Parameters
Parameter | Description |
---|---|
id integer required | The ID of the request resource being managed |
hotel_id | Property Numerical identifier Cannot be null |
Guest | see list of supported strings |
Category string required | form category name from the categories endpoint |
room string optional | Guest room for their booking |
booking_id string optional | The reservation identifier for the guests stay with the property, if applicable. |
guest_notify boolean required | Should an email be sent to the guest notifying them of this requests update? Recommended false |
staff_username string optional |
|
status string optional |
|
form_name string required | Name of the form we are creating this request for from the forms endpoint |
form_fields array required | details of the form request. Needs to match any required form_fields for the specified form_name from the forms forms endpoint |
Requests Guest Array
Anchor | ||||
---|---|---|---|---|
|
Parameter | Description |
---|---|
name | Guest fullname i.e. "John Doe" |
email | guest email |
phone string optional | guests preferred phone number |
Webhooks
Properties can enable a webhook notification url at the property level. If enabled we will send a json request object to the notification url every time a request is created or updated. The property has control over if they wish to use a notification url or not, and may turn it on or off by editing their property details as shown below.
Requirements
- The webhook url must support HTTPS. We will automatically convert any http or non defined url to https upon saving the webhook url.
- The webhook url must support POST method.
- The webhook url must support BASIC Authentication and the username and password.
- If enabled MyGuests will send a json request object to the webhook url for every request that is created or updated. The partner should use filtering logic as appropriate to capture/discard messages based upon their desired needs.
Sample Webhook Json Request Object
Code Block |
---|
{
"id": 881,
"booking_id": "1796110W",
"room": "32",
"guest": {
"name": "Joe Banks",
"email": "joeb@banks.com",
"phone_number": null
},
"created_at": "2020-02-26 14:48:08",
"updated_at": "2020-03-10 15:28:34",
"length_open": "1 week",
"status": "Completed",
"assigned": "John Doe - BookingCenter",
"category": {
"id": 24,
"name": "Housekeeping"
},
"request_details": [
{
"name": "Details",
"value": "Room Cleaning Required",
"amount": null,
"type": "text"
}
],
"comments": {
"guest_comments": [
{
"details": "Room is being cleaned",
"created_at": "2020-03-02 12:01:24",
"staff": "mary"
},
{
"details": "Hi",
"created_at": "2020-03-02 13:24:54",
"staff": "tom"
},
{
"details": "Lets Test This out",
"created_at": "2020-03-02 14:26:02",
"staff": "ellen"
}
],
"staff_notes": [
{
"details": "Hi",
"created_at": "2020-03-02 12:01:13",
"staff": "ellen"
}
]
}
} |
MyGuest / BookDB Request to Booking Mapping Table
Table Schema
...