...
- 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:
...
- 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.
- The Property grants the Partner Application permission to manage access their property account via the API.
...
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 our partners' partner integration to our API platform, please use our support system at our Online Support Portal.
Endpoints:
Forms
...
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. "BookingCenter" or "Booking.com" .
If used message_thread element is required.
...
guest_notify
boolean
required
...
form_name
string
required
...
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",
"errors": {
"status": 404,
"title": "record not found",
"details": "no record 345 found"
},
"request_uuid": "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 |
---|
{
"properties": [
{
"id": 2,
"name": "A MyPMS Demo Hotel",
"site_url": "http://Hotel.bookingcenter.com",
"timezone": "America/Dawson",
"contact_email": "mypms@demohotel.com"
},
{
"id": 3,
"name": "Steves Test Property",
"site_url": "http://Hotel.bookingcenter.com",
"timezone": "Africa/Abidjan",
"contact_email": null
},
{
"id": 10,
"name": "Lava Ridges Test Property",
"site_url": "www.lavaridge.org",
"timezone": "America/Dawson",
"contact_email": "lavaridges@email.com"
}
],
"api_version": 3,
"status": "success",
"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": [
{
|
Staff
...
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. "BookingCenter" or "Booking.com" .
If used message_thread element is required.
...
guest_notify
boolean
required
...
form_name
string
required
...
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. "BookingCenter" or "Booking.com" .
If used message_thread element is required.
...
guest_notify
boolean
required
...
form_name
string
required
...
Example Request
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": "BookingCenter",
"message_thread": "597470647",
"guest_notify": false,
"form_name": "Self Checkin"
}
} |
Example Response
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": "BookingCenter", "message_thread": "597470647", "assigned": null, "status": { "id": 1, "name": "NewDetails", "created_atvalue": "2014-11-14 02:23:46Room Cleaning Required", "updated_atamount": "2014-11-14 02:23:46" null, "type": "text" } ], "comments": { "guest_comments": {[ { "iddetails": 13, "Room is being cleaned", "namecreated_at": "Joe Banks2020-03-02 12:01:24", "emailstaff": "jchieppa@gmail.commary", }, "phone": "7075551414", { "rewards_numberdetails": "0Hi", "created_at": "20182020-03-02-07 1013:4924:2854", "updated_at": "2019-01-11 22:09:36" staff": "tom" }, "staff": null,{ "categorydetails": { "Lets Test This out", "idcreated_at": 21, "2020-03-02 14:26:02", "namestaff": "Self Checkinellen", } ], "departmentstaff_idnotes": 7,[ { "created_atdetails": "2019-01-14 22:21:55Hi", "updatedcreated_at": "20192020-0103-1402 2212:2101:5513", "identifierstaff": "21ellen" } } ] } } |