Surveys - Generating personalized links

Client hotel can send the link to the survey themselves.

The link has the following format:

https://survey.reviewpro.com/feedback/mail?<query-params>

Request Type: GET

Instead of survey.reviewpro.com client can use any host name, as long as all the request to that host name are forwarded to survey.reviewpro.com.

Parameters

Param Value Required
apiKey <your api key> Yes
surveyId  <id of the survey> Yes
pmsId id of the hotel in external id mapping section of account settings Yes
email guest email Yes
firstName guest's first name Yes
lastName guest's last name Yes
checkin guest checkin date in yyyy-MM-dd format. Interpreted as date string in UTC Yes
checkout guest checkout date in yyyy-MM-dd format. Interpreted as date string in UTC Yes
... any other extra guest data, each as separate parameter distinct from the mentioned above No
sig HMAC using a secret key and SHA256 message digest algorithm Yes

Including NPS or Overall in invitation emails 

ReviewPro supports having either an NPS or Overall question directly in the invitation email to increase the response ratio. The chosen score from the email wll be prefilled in the survey when opening the survey in the webbrowser. The score of NPS or Overall are specific parameters which should be passed in the links in the invitation mail.

We have two types of urls, encrypted and not encrypted :

  • Encrypted

In this case the "nps" or "overall" must be explicitly in the url as in https://survey.reviewpro.com/feedback/mail?encryption=tripledes&apiKey=<apiKey>&key=<key>&nps=2

  • Not Encrypted

In this case the "nps" or "overall" must be explicitly in the url and the signature ("sig" param) must be generated including this new param as in https://survey.reviewpro.com/feedback/mail?apiKey=<apiKey>&<...params>&nps=2&sig=<sig>

Signature generation 

sig is a HMAC using a secret key and SHA256 message digest algorithm. It takes as an input all query parameters concatenated in the alphabetical order by key: apiKey, checkin, checkout, email, firstName, lastName, pmsId, surveyId, etc. The secret key can be obtained from your Mashery account settings.

Example

Assuming that the url has parameters:

  • apiKey = "23675469989xxhy0"
  • checkin = "2014-01-01"
  • checkout = "2014-01-02"
  • email = "aaa@bbb.com"
  • firstName = "John"
  • lastName = "Doe"
  • LoyaltyNumber = "23445"
  • pmsId = "53770"
  • surveyId = "UtjT-oSiRJoMGL-k"

The concatenated string (all the parameters in alphabetical order) to encode is:

23675469989xxhy02014-01-012014-01-02aaa@bbb.comJohnDoe53770UtjT-oSiRJoMGL-k23445

If you example shared key is "ABC", the sig will be:

0ceb065d7dbe776ba8196ce26feafe38cd42550f42de727aad46e3011fb953a1

You can test HMAC + HA256 generation via online tools like http://www.freeformatter.com/hmac-generator.html.

The final URL with sig appended will read:

https://survey.reviewpro.com/feedback/mail?apiKey=23675469989xxhy0&checkin=2014-01-01&checkout=2014-01-02&email=aaa@bbb.com&firstName=John&lastName=Doe&pmsId=53770&surveyId=UtjT-oSiRJoMGL-k&LoyaltyNumber=23445&sig=0ceb065d7dbe776ba8196ce26feafe38cd42550f42de727aad46e3011fb953a1

The following Python script can be used to calculate sig. It accepts two parameters: api shared secret and the survey url without the sig parameter, and outputs sig to the console.

import hmac
import hashlib
from urlparse 
import urlparse, parse_qs
import sys

o = urlparse(sys.argv[2])
params = parse_qs(o.query)

s = ''.join(''.join(sorted(v)) for _, v in sorted(params.items()))

sig = hmac.new(sys.argv[1], msg=s, digestmod=hashlib.sha256).hexdigest()

print sig

Another example of sig generation in Java

String key = "whatever"
TreeMap<String, String> sortedParams = new TreeMap<>();
sortedParams.put("surveyId", "45fa3453g");

StringBuilder sb = new StringBuilder();
for (Map.Entry<String, String> param : sortedParams.entrySet()) {    
	sb.append(param.getValue());
}

 String algorithm = "HmacSHA256";
Charset charset = Charset.forName("UTF-8");
Mac hmac = Mac.getInstance(algorithm);
SecretKey secretKey = new SecretKeySpec(key.getBytes(charset), algorithm);
hmac.init(secretKey);
 
byte[] b = sb.toString().getBytes(charset);
String sig = Hex.encodeHexString(hmac.doFinal(b));

Testing

Parameters can be tested using the following url: 

https://survey.reviewpro.com/feedback/mail/testParams?<query-params>

Request Type: GET

It takes the same query parameters as the survey url.