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.

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 <