Guestmeter API

Guestmeter API enables users and partners to send SMS or Email Survey to recent guests, encouraging a review of their experiences.

To use this API, you need to get an apiKey and secretKey. Please sign up or login to Guestmeter. To get your own API key, go to Channels > Integration page. If you did not find your API key or request a test apiKey and secretKey, please contact us at support@guestmeter.com.

Authentication

   HTTP Header Sample

       apiKey: "71e8b143-44a4-4acc-be14-2bef282dbaed"
       secretKey: "112fb4af-fd26-4427-a8a2-1da22a64d095"

All requests must contain 2 mandatory HTTP Header parameter for authentication. These keys are apiKey and secretKey for authorization and authentication.

Test Property Data: You can request a test apiKey and secretKey special for you. To facilitate testing, there are major differences between the test and production keys. Calls with the test apiKey and secretKey will not generate an actual SMS or Email to a guest.

Send Survey

Used to send guest satisfaction survey via SMS or Email. Must be a POST request with a JSON-formatted list of the following parameters as the request body. The ID of the created request(s) will be returned after a successful call - see Response below. You need to make a POST call to the following url :
https://www.guestmeter.com/api/sendSurvey


# Here is a curl example
curl \
-X POST https://www.guestmeter.com/api/sendSurvey \
-F 'guestEmail=test@test.com' \
-F 'guestName=test test' \
-F 'roomNumber=101' \
-F 'languageCode=en'
 
 
 
EXAMPLE EMAIL SURVEY REQUEST :
https://www.guestmeter.com/api/sendSurvey?guestEmail=test@test.com&guestName=test&roomNumber=101&languageCode=en

EXAMPLE SMS SURVEY REQUEST :
https://www.guestmeter.com/api/sendSurvey?guestPhone=+134234234234&guestName=test&languageCode=en
                   
EXAMPLE SUCCESS RESPONSE :
{
    "statusList": [
        {
            "status": "SUCCESS",
            "statusCode": "guestID:4b0da1ba-fd20-4b67-9b3c-6dfe8c7c220d",
            "statusMessage": "Guest satisfaction survey will be sent to test@test.com at 24.03.2020. Monthly SMS & Email usage: 11/5000 (XLARGE Plan)"
        }
    ]
}

EXAMPLE FAILED RESPONSE :
{
    "statusList": [
        {
            "status": "ERROR",
            "statusCode": "BUS0003",
            "statusMessage": "A guest satisfaction survey already been sent to test@test.com in last 30 days! You're allowed to send only 1 survey in one month per guest"
        }
    ]
}

REQUEST PARAMETERS

Field	Type	Description
guestEmail	String	Guest email address.
guestPhone	String	Guest mobile number.
guestName	String	Guest full name
roomNumber	String	Guest room number or table number
integrationID	String	Reference integration value of guest in client system. Ex: customerID...
primarySendMethod	String	(optional) Possible values: "email" or "sms". Default is "sms". If both guestEmail and guestPhone parameters exist you can choose the primary survey send method.
languageCode	String	(optional) You can set survey language. 2 character language codes, ex: "en", "es", "fr", "de", "tr"...
checkoutDate	Date	(optional) You can send survey after guest checkout date. Date format: "DD.MM.YYYY" or "DD-MM-YYYY"

RESPONSE PARAMETERS

Field	Type	Description
status	String	Status of your request. Values: "SUCCESS" or "ERROR"
statusCode	String	If status="SUCCESS" you can get guestID in this parameter. If status="ERROR" you can find error code.
statusMessage	String	Status code description.

Get Guest

Used to get guest and rating details by guestID parameter. Must be a GET request with a JSON-formatted list of the following parameters as the request body. You need to make a GET call to the following url :
https://www.guestmeter.com/api/getGuest


# Here is a curl example
curl \
-X POST https://www.guestmeter.com/api/getGuest \
-F 'guestID=4b0da1ba-fd20-4b67-9b3c-6dfe8c7c220d'
 
 
 
EXAMPLE REQUEST :
https://www.guestmeter.com/api/getGuest?guestID=9d77b4cc-cdaa-4768-9aa9-94a0d772f222
              
EXAMPLE RESPONSE :
[
    {
        "guestID": "9d77b4cc-cdaa-4768-9aa9-94a0d772f222",
        "guestName": "",
        "roomNumber": "101",
        "contactInfo": "+905324681111",
        "contactType": "sms",
        "countryCode": "tr",
        "integrationID": "",
        "propertyName": "Pera Palace Hotel İstanbul",
        "rating": "6",
        "ratingType": "detractors",
        "feedback": "its not a good hotel",
        "mainChannel": "DASHBOARD",
        "status": "SENT",
        "statusDetail": "",
        "languageCode": "en",
        "sentDate": "06.03.2020 00:35:00",
        "clickedDate": "06.03.2020 00:36:00",
        "ratedDate": "06.03.2020 00:36:00",
        "creationDate": "06.03.2020 00:35:00"
    }
]

REQUEST PARAMETERS

Field	Type	Description
guestID	String	Guest ID number in uuid format. Ex: 9d77b4cc-cdaa-4768-9aa9-94a0d772f222

RESPONSE PARAMETERS

Field	Type	Description
guestID	String	Same guestID number in your request.
contactType	String	Guest contact and survey send method. Values: "sms" or "email".
contactInfo	String	If contactType="SMS" value is guest mobile number. If contactType="email" value is guest email address.
guestName	String	Guest full name.
roomNumber	String	Guest room number or table number
integrationID	String	Reference integration value of guest in client system. Ex: customerID...
rating	String	Rating value sent by guest. If ratedDate is not empty you can check this field.
feedback	String	Guest feedback message sent with rating. If ratedDate is not empty you can check this field.
ratingType	String	NPS rating type, possibe values= "detractors", "passives", "promoters". If rating value is between 1-6 value "detractors", between "7-8" value "passives" or between "9-10" value "promoters". If ratedDate is not empty you can check this field.
propertyName	String	Name of your property.
propertyName	String	Name of your property.
languageCode	String	Survey language that guest show. 2 character language code, Ex: "en", "es", "fr", "de", "tr"...
countryCode	String	Detected country code of guest. 2 character country code, Ex: "us", "es", "fr", "de", "tr"...
maiChannel	String	Guest added on this channel. Possible values= "DASHBOARD", "INTEGRATION", "QRCODE", "KIOSK"
status	String	Survey delivery status. Possible values= "SENT", "FAILED", "PLANNED", "QUEUED"
statusMessage	String	Survey delivery status description. If status="FAILED" check this field.
sentDate	DateTime	Survey sent date.
clickedDate	DateTime	Survey clicked date.
ratedDate	DateTime	Survey rated date.
creationDate	DateTime	Guest creation date.

Get Guest List

Used to get guest list of your property. There is no request parameters for this method. Must be a GET request with a JSON-formatted list of the following parameters as the request body. You need to make a GET call to the following url :
https://www.guestmeter.com/api/getGuestList


# Here is a curl example
curl \
-X POST https://www.guestmeter.com/api/getGuestList
 
 
 
EXAMPLE REQUEST :
https://www.guestmeter.com/api/getGuestList
              
EXAMPLE RESPONSE :
[
    
    {
        "guestID": "d426a1e3-7dd3-55e1-b061-46123fb0b06e",
        "guestName": "test",
        "contactInfo": "+1342342342",
        "contactType": "sms",
        "countryCode": "",
        "propertyName": "Pera Palace Hotel İstanbul",
        "rating": "",
        "ratingType": "",
        "feedback": "",
        "mainChannel": "INTEGRATION",
        "status": "PLANNED",
        "statusDetail": "",
        "languageCode": "en",
        "sentDate": "14.04.2020 19:10:00",
        "clickedDate": "",
        "ratedDate": "",
        "creationDate": "14.04.2020 19:10:00"
    },
    {
        "guestID": "4b0da1ba-fd20-4b67-9b3c-6dfe8c72210d",
        "guestName": "test name",
        "contactInfo": "test@test.com",
        "contactType": "email",
        "countryCode": "",
        "propertyName": "Pera Palace Hotel İstanbul",
        "rating": "",
        "ratingType": "",
        "feedback": "",
        "mainChannel": "INTEGRATION",
        "status": "PLANNED",
        "statusDetail": "",
        "languageCode": "es",
        "sentDate": "14.04.2020 19:16:00",
        "clickedDate": "",
        "ratedDate": "",
        "creationDate": "14.04.2020 19:16:00"
    },
    {
        "guestID": "11cc872c-124a-49af-ba41-7124a878c895",
        "guestName": "test 4",
        "roomNumber": "101",
        "contactInfo": "test3@test.com",
        "contactType": "email",
        "countryCode": "",
         "integrationID": "",
        "propertyName": "Pera Palace Hotel İstanbul",
        "rating": "",
        "ratingType": "",
        "feedback": "",
        "mainChannel": "INTEGRATION",
        "status": "PLANNED",
        "statusDetail": "",
        "languageCode": "es",
        "sentDate": "14.04.2020 19:25:00",
        "clickedDate": "",
        "ratedDate": "",
        "creationDate": "14.04.2020 19:25:00"
    }
]

REQUEST PARAMETERS

Field	Type	Description
No request parameter for this method			String	Your API key.

RESPONSE PARAMETERS

Field	Type	Description
guestID	String	Same guestID number in your request.
contactType	String	Guest contact and survey send method. Values: "sms" or "email".
contactInfo	String	If contactType="SMS" value is guest mobile number. If contactType="email" value is guest email address.
guestName	String	Guest full name.
roomNumber	String	Guest room number or table number
integrationID	String	Reference integration value of guest in client system. Ex: customerID...
rating	String	Rating value sent by guest. If ratedDate is not empty you can check this field.
feedback	String	Guest feedback message sent with rating. If ratedDate is not empty you can check this field.
ratingType	String	NPS rating type, possibe values= "detractors", "passives", "promoters". If rating value is between 1-6 value "detractors", between "7-8" value "passives" or between "9-10" value "promoters". If ratedDate is not empty you can check this field.
propertyName	String	Name of your property.
propertyName	String	Name of your property.
languageCode	String	Survey language that guest show. 2 character language code, Ex: "en", "es", "fr", "de", "tr"...
countryCode	String	Detected country code of guest. 2 character country code, Ex: "us", "es", "fr", "de", "tr"...
maiChannel	String	Guest added on this channel. Possible values= "DASHBOARD", "INTEGRATION", "QRCODE", "KIOSK"
status	String	Survey delivery status. Possible values= "SENT", "FAILED", "PLANNED", "QUEUED"
statusMessage	String	Survey delivery status description. If status="FAILED" check this field.
sentDate	DateTime	Survey sent date.
clickedDate	DateTime	Survey clicked date.
ratedDate	DateTime	Survey rated date.
creationDate	DateTime	Guest creation date.

OTA_HotelResNotifRQ / OTA_HotelResNotifRS PUSH ENDPOINT

Every time a reservation / modification / cancellation is made, the entire reservation can be pushed from the booking source, such as Global Distribution System (GDS) or Central Reservation System (CRS) to the Guestmeter. Must be a POST request with a XML-formatted list of the following parameters as the request body. You need to make a POST call to the following url :
https://www.guestmeter.com/api/OTA_HotelResNotifRQ


# Here is a curl example
curl \
-X POST https://www.guestmeter.com/api/OTA_HotelResNotifRQ

Errors

The Guestmeter API uses the following error codes:

Error Code	Meaning
SYS0001	AUTHENTICATION: `apiKey` should not be empty! Check HTTP header authentication keys.
SYS0002	AUTHENTICATION: `secretKey` should not be empty! Check HTTP header authentication keys.
SYS0003	AUTHENTICATION: Wrong `secretKey`! Check HTTP header authentication keys. Login to Guestmeter panel and swith to Channel > Integration from menu to get your secretKey.
SYS0004	AUTHENTICATION: Wrong `apiKey`! Check HTTP header authentication keys. Login to Guestmeter panel and swith to Channel > Integration from menu to get your apiKey.
SYS0005	Your trial end. Please select a plan to continue your service or ask OWNER team member!
SYS0006	Your subscription status is not Active now. Please check Subscription and Payments.
SYS0008	Undefined method! Check your method name. Possible values: "sendSurvey", "getGuest" and "getGuestList"
SYS0011	Request Type should be POST for this method! You may request with GET method.
BUS0001	Monthly SMS & Email survey limit exceeded for your plan! Please upgrade your plan or wait till next month.
BUS0002	A guest satisfaction survey already been sent to mobile number or email in last 30 days! You're allowed to send only 1 survey in one month per guest
DATA0003	Guest mobile number or email address should not be empty!
DATA0002	primarySendMethod must be 'email' or 'sms'!
DATA0004	Email address format is wrong! Ex: xxx@xxx.com.
DATA0006	Guest mobile number is not valid!
DATA0021	No guest exists! Please add some guest from panel or API.

API FAQ

Frequently Asked Questions about Guestmeter API

Q: Which API key should I use?

A: To use this API, you need to get your apiKey and secretKey. Please sign up or login Guestmeter to get your own API key. Go to Channel > Integration page to get your keys. If you did not find your API key, please contact us at support@guestmeter.com.

Q: What is the test environment vs the production environment?

A: You can request a test apiKey and secretKey special for you. To facilitate testing, there are major differences between the test and production keys. Calls with the test apiKey and secretKey will not generate an actual SMS or Email to a guest. The single API environment uses https://www.guestmeter.com/api.

Q: I added a guest, the checkout date has passed but no sms or e-mail has been sent. Why?

A: This could happen for a number of reasons:

1- The SMS or Email recipient has submitted a review for this business within the past 90 days (for accommodations or attractions) or 30 days (for restaurants)
2- A Guestmeter SMS or Email was sent to this guest within the past 30 days
3- The SMS or Email recipient has unsubscribed from Guestmeter <