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

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 (where UPPERCASE goes before lowercase): apiKey, checkin, checkout, email, firstName, lastName, pmsId, surveyId, etc. The secret key can be obtained from your Mashery account settings. Please note that although the parameters will need to be URLENCODE in the final URL, they are not URLENCODE to calculate the sig.

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, where UPPERCASE goes before lowercase, the parameters overall and nps are never included in this string) to encode is:

2344523675469989xxhy02014-01-012014-01-02aaa@bbb.comJohnDoe53770UtjT-oSiRJoMGL-k

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

fa5bd997dfadd787b6bc673233cbbc1ef6a4cb121332821b047ec36e90f1c639

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=fa5bd997dfadd787b6bc673233cbbc1ef6a4cb121332821b047ec36e90f1c639

Encryption of the link

For security or privacy reasons you can decide to encrypt the link, to hide the parameters passed on in the URL. The default encryption is done with tripledes (Ryndael), with an IV of only NULLs. The part to be encrypted is from the first till the last parameter, not including the API-key. For encrypte links no signature needs to be calculated. Please be aware that in case of encryption a special combination of API-key and secret needs to be created. For this you can contact integrations@reviewpro.com.

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, but the signature ("sig" param) must be generated WITHOUT this new param as in https://survey.reviewpro.com/feedback/mail?apiKey=<apiKey>&<...params>&nps=2&sig=<sig> 


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.