Surveys & Results

Surveys determine when a certain question is used and how the collected feedback is displayed. The results are available via the survey resource.

Summary of available resource patterns

Code	URL
GET	/v1/surveys/:key
GET	/v1/surveys/:key/results
GET	/v1/surveys/:key/openfeedback
GET	/v1/surveys/:key/followup
GET	/v1/surveys/:key/rawresults

---

Survey

JSON presentation of survey.

Properties

Name	Description
key	The identifier of the survey
question	Object of the question in default locale.
folder	Object of the folder where survey is located.
timeZone	The time zone of survey in “Area/Location”-format.
activePeriods	An array of objects with two properties, start and end, describing time periods when the survey is active. Start timestamp is inclusive and end is exclusive. If survey does not have any periods, this property is not included.
surveyType	A string representing the survey’s type. Possible values are: TERMINAL, TABLET and WEB. surveyType is TERMINAL for surveys collecting feedback using Smiley Terminals, TABLET for surveys collecting feedback using Smiley Touch and WEB for surveys collecting feedback using Smiley Digital.
indexType1	A string representing the index type. Possible values currently are: HAPPY, NPS or AVERAGE.
feedbackScale1	A string representing the feedback scale. Possible values currently are: FOUR, FIVE or FIVE_REVERSED.

¹ Some values require a premium feature to be enabled for account.

Example JSON objects

Survey with two active periods.

{
  "key": 1,
  "question": {
    "key": 2,
    "name": "How was your day?",
    "locale": "en-US"
  },
  "folder": {
    "key": 5,
    "name": "Tampere"
  },
  "timeZone": "Europe/Helsinki",
  "activePeriods": [
    {
      "start": "2013-01-01T00:00:00.000+0200",
      "end": "2013-02-01T00:00:00.000+0200"
    },
    {
      "start": "2013-03-01T00:00:00.000+0200",
      "end": "2013-04-01T00:00:00.000+0300"
    }
  ],
  "surveyType": "TERMINAL",
  "indexType": "HAPPY",
  "feedbackScale": "FOUR"
}

---

OpenFeedback

JSON presentation of open feedback.

Note

HappyOrNot might append more properties to this object in the future without api version increase. Consider implementing your API integration to allow this object to have more properties (or nested properties) than listed below.

Properties

Name	Description
ts	Timestamp in survey time zone
r	Index. Smiley button used when feedback was given. Number from 0 (Very Unhappy) to 3 (Very Happy) for 4 scale and from 0 (Very Unhappy) to 4 (Very Happy) for 5 scale.
relevance	optional Float from 0.0 (worst) to 1.0 (best). Automatically analyzed quality value for the open feedback text.
spam	optional, true or false. true if feedback is marked as spam.
f	Optional, FollowUp object. The follow-up that was chosen when feedback was given. Will not be present if follow-ups are disabled, user did not choose any or if device does not support them.
text	The open feedback text

Example JSON objects

Positive feedback given after pressing the green button and choosing a follow-up

{
  "ts": "2018-11-27T17:09:34.421+02:00",
  "r": 3,
  "relevance": 1,
  "spam": false,
  "f": {
    "key": 4,
    "name": "Taste of food"
  },
  "text": "The dish was prepared perfectly!"
}

Negative feedback given after pressing the red button and choosing a follow-up

{
  "ts": "2018-11-27T17:10:45.123+02:00",
  "r": 0,
  "relevance": 0.92,
  "spam": false,
  "f": {
    "key": 1,
    "name": "Something else"
  },
  "text": "Too expensive :("
}

Negative feedback given after pressing the red button without choosing a follow-up

{
  "ts": "2018-11-27T19:12:01.965+02:00",
  "r": 0,
  "relevance": 1,
  "spam": false,
  "text": "Restaurant is one of the best in this area. I hope it would be open also on Sundays."
}

Feedback categorized as spam

{
  "ts": "2018-11-27T22:10:22.735+02:00",
  "r": 3,
  "relevance": 0.1,
  "spam": true,
  "text": "sdhfksjdhf"
}

---

FollowUp

JSON presentation of follow-up option.

Note

HappyOrNot might append more properties to this object in the future without api version increase. Consider implementing your API integration to allow this object to have more properties (or nested properties) than listed below.

Properties

Name	Description
key	Unique id of the follow-up option
name	Follow-up text in question’s default locale

Example JSON objects

{
  "key": 4,
  "name": "Taste of food"
}

---

FollowUpResult

JSON presentation of follow-up option results.

Note

HappyOrNot might append more properties to this object in the future without api version increase. Consider implementing your API integration to allow this object to have more properties (or nested properties) than listed below.

FollowUp object appended with results:

Properties

Name	Description
data	Responses. An array indexed from Very Unhappy (red button, index 0) to Very Happy (green button, index 3) for 4 scale and from Very Unhappy (red button, index 0) to Very Happy (green button, index 4) for five scale
percentages	Relative amount compared to other follow-ups during the requested time period. Percentages are calculated separately for highlights and pain points.

Example JSON objects

{
  "key": 4,
  "name": "Taste of food",
  "data": [17, 1, 0, 0],
  "percentages": [0.447, 0.026, 0.0, 0.0]
}

---

RawResult

JSON presentation of raw result.

Note

HappyOrNot might append more properties to this object in the future without api version increase. Consider implementing your API integration to allow this object to have more properties (or nested properties) than listed below.

FollowUp object appended with results:

Properties

Name	Description
ts	Timestamp in survey time zone
r	optional index. Smiley button used when feedback was given. Number from 0 (Very Unhappy) to 3 (Very Happy) for 4 scale and from 0 (Very Unhappy) to 4 (Very Happy) for 5 scale. Not present for older Smiley Digital open feedback, see the o property below for more info.
data	optional index array. Alternative to r. Hourly summed up results. The indexes in the array run from 0 (Very Unhappy) to 3 (Very Happy) for 4 scale and from 0 (Very Unhappy) to 4 (Very Happy) for 5 scale. See more when this is returned under /v1/surveys/:key/rawresults
f	optional FollowUp object. The follow-up that was chosen when feedback was given, if any.
o	optional Partial OpenFeedback object. Always includes the text property. Older (prior March 2020) Smiley Digital open feedback will also include the r button index as context what button response user gave when leaving the open feedback using Smiley Digital. For Smiley Digital, this nested r is provided instead of a root level r. This is because older Smiley Digital button response and open feedback were gathered separately and the actual button response r is also returned as own RawResult object. Calculating them both as button responses would double the response. Having the nested r makes it possible to separate them when handling the results but still provides the important response context for the open feedback. Newer (after March 2020) Smiley Digital feedback consists of both button response and open feedback and is returned as one standard raw result that has only the root level r and no nested r.

Example JSON objects

Basic raw result

{
  "ts": "2018-07-12T11:49:33.182-02:00",
  "r": 3
}

Hourly summed raw result

{
  "ts": "2018-07-13T11:00:00.000-02:00",
  "data": [4, 8, 12, 16]
}

Raw result with follow-up

{
  "ts": "2018-04-21T12:06:42.343+01:00",
  "r": 2,
  "f": {
    "key": 3,
    "name": "Service"
  }
}

Raw result with follow-up and open feedback

{
  "ts": "2018-04-21T13:06:43.162+01:00",
  "r": 0,
  "f": {
    "key": 3,
    "name": "Service"
  },
  "o": {
    "text": "Not enough shop clerks. Did not get any service"
  }
}

Raw result with open feedback

{
  "ts": "2020-02-26T14:38:12.738Z",
  "r": 3,
  "o": {
    "text": "Wide variety of selection!"
  }
}

Prior March 2020 raw open feedback result from Smiley Digital

{
  "ts": "2016-11-18T12:15:43.362Z",
  "o": {
    "r": 1,
    "text": "The website is hard to navigate!"
  }
}

---

GET /v1/surveys/:key

Retrieves information for a specific survey.

Parameters

Name	Description
key	required, identifier of the survey

Example requests and responses

GET /v1/surveys/1

{
  "key": 1,
  "question": {
    "key": 2,
    "name": "How was your day?",
    "locale": "en-US"
  },
  "folder": {
    "key": 5,
    "name": "Tampere"
  },
  "timeZone": "Europe/Helsinki",
  "activePeriods": [
    {
      "start": "2013-01-01T00:00:00.000+0200",
      "end": "2013-02-01T00:00:00.000+0200"
    },
    {
      "start": "2013-03-01T00:00:00.000+0200",
      "end": "2013-04-01T00:00:00.000+0300"
    }
  ],
  "surveyType": "TERMINAL",
  "indexType": "HAPPY",
  "feedbackScale": "FOUR"
}

Result

Name	Description
Success	Survey
Error	HTTP status code 404 when no survey is found.

---

GET /v1/surveys/:key/results

Retrieves feedback results for specific survey.

Parameters

Name	Description
key	required, identifier of the survey
date_start	optional, timestamp Timestamp of returned feedback data is equal or later than the value. When precision is day or greater then date_start is exclusive. The default value depends on date_end and truncate parameters. truncate defines the length of the default period by the following rules: da year returns all results month returns results for the current year week returns results for the previous 2 months day returns previous 14 days hour returns previous 24 hours
date_end	optional, timestamp Timestamp of returned feedback data is sooner than the value. For default values, see date_start
truncate	optional, year | month | week | day | hour Case-insensitive value from one of the above. Truncates and sums the feedback to required precision. By default it is day. Maximum values are none for year, 7 days for hour and 12 months for the rest. To fetch more data, use additional requests.

Known bug

If truncate = day is used or no truncate value given (defaults to day) the date_start will be exclusive. Therefore, one day must be subtracted from the value to get the expected result. This will be fixed for the next version of the API, but left as is in the current version.

Example requests and responses

GET /v1/surveys/3/results?truncate=hour&date_start=2013-05-03T00:00:00.000Z&date_end=2013-05-04T00:00:00.000Z

[
  {
    "ts": "2013-05-03T00:00:00.000Z",
    "data": [4, 8, 12, 16]
  },
  {
    "ts": "2013-05-03T01:00:00.000Z",
    "data": [4, 8, 12, 16]
  },
  {
    "ts": "2013-05-03T22:00:00.000Z",
    "data": [4, 8, 12, 16]
  },
  {
    "ts": "2013-05-03T23:00:00.000Z",
    "data": [4, 8, 12, 16]
  },
  {
    "ts": "2013-05-03T00:00:00.000Z",
    "data": [4, 8, 12, 16]
  }
]

Result

Name	Description
Success	Array of objects with ts for result timestamp and data for array of feedback. The array is indexed from Very Unhappy (red button, index 0) to Very Happy (green button, index 3) for 4 scale and from Very Unhappy (red button, index 0) to Very Happy (green button, index 4) for 5 scale. The actual indexes are dependent on how many active buttons the device has.
Error	HTTP status code 400 when date_end is before date_start or unknown value given for truncate. HTTP status code 404 when no survey is found.

---

GET /v1/surveys/:key/openfeedback

Retrieves open feedback for specific survey.

Parameters

Name	Description
key	required, identifier of the survey
date_start	optional, timestamp Timestamp of returned survey open feedback data is equal or later than the value.
date_end	optional, timestamp Timestamp of returned open feedback data is sooner than the value.

Example requests and responses

GET /v1/surveys/3/openfeedback?&date_start=2018-11-27T14:00:00.000Z&date_end=2018-11-27T23:00:00.000Z

{
  "meta": {},
  "data": [
    {
      "ts": "2018-11-27T17:09:34.421+02:00",
      "relevance": 1.0,
      "spam": false,
      "r": 3,
      "f": {
        "key": 4,
        "name": "Taste of food"
      },
      "text": "The dish was prepared perfectly!"
    },
    {
      "ts": "2018-11-27T17:10:45.123+02:00",
      "relevance": 0.92,
      "spam": false,
      "r": 0,
      "f": {
        "key": 1,
        "name": "Something else"
      },
      "text": "Too expensive :("
    },
    {
      "ts": "2018-11-27T19:12:01.965+02:00",
      "r": 0,
      "relevance": 1.0,
      "spam": false,
      "text": "Restaurant is one the best in this area. I hope it would be open also on Sundays."
    },
    {
      "ts": "2018-11-27T22:10:22.735+02:00",
      "r": 3,
      "relevance": 0.1,
      "spam": true,
      "text": "sdhfksjdhf"
    }
  ]
}

GET /v1/surveys/3/openfeedback?&date_start=2018-01-01T00:00:00.000Z&date_end=2019-01-01T00:00:00.000Z

{
  "meta": {
    "moreResultsAfter": "2018-10-03T10:20:18.000Z"
  },
  "data": []
}

Result

Name	Description
Success	A single JSON object that contains meta and data keys. The data key contains an array of OpenFeedback objects. The meta key contains paging information, if the response does not contain all the results. If there is so much feedback that some of it does not fit in the same HTTP response, the response will contain the feedback with the earliest timestamps. The maximum amount of open feedback returned in single response is 10 000. If there is more feedback available, then inside the meta key will be a moreResultsAfter key that will give you the timestamp from which to request more results with this same endpoint. This way you can retrieve any amount of feedback in several “pages”.
Error	HTTP status code 400 in case of invalid parameters. HTTP status code 404 when no survey is found.

---

GET /v1/surveys/:key/followup

Retrieves follow-up results for a specific survey.

Parameters

Name	Description
key	required, identifier of the survey
date_start	optional, timestamp Timestamp of returned survey follow-up result data is equal or later than the value.
date_end	optional, timestamp Timestamp of returned follow-up result data is sooner than the value.

Example requests and responses

GET /v1/surveys/3/followup&date_start=2018-05-03T00:00:00.000Z&date_end=2018-05-13T00:00:00.000Z

{
  "meta": {},
  "data": {
    "painPoints": [
      {
        "key": 2,
        "name": "Waiting time",
        "data": [17, 1, 0, 0],
        "percentages": [0.447, 0.026, 0.0, 0.0]
      },
      {
        "key": 20,
        "name": "Cleanliness",
        "data": [6, 1, 0, 0],
        "percentages": [0.158, 0.026, 0.0, 0.0]
      },
      {
        "key": 1,
        "name": "Something else",
        "data": [4, 1, 0, 0],
        "percentages": [0.105, 0.026, 0.0, 0.0]
      },
      {
        "key": 5,
        "name": "Food quality",
        "data": [4, 1, 0, 0],
        "percentages": [0.105, 0.026, 0.0, 0.0]
      },
      {
        "key": 11,
        "name": "Accessibility",
        "data": [1, 2, 0, 0],
        "percentages": [0.026, 0.053, 0.0, 0.0]
      }
    ],
    "highlights": [
      {
        "key": 42,
        "name": "Staff attitude",
        "data": [0, 0, 12, 94],
        "percentages": [0.0, 0.0, 0.069, 0.54]
      },
      {
        "key": 4,
        "name": "Taste of food",
        "data": [0, 0, 4, 16],
        "percentages": [0.0, 0.0, 0.023, 0.092]
      },
      {
        "key": 20,
        "name": "Cleanliness",
        "data": [0, 0, 9, 9],
        "percentages": [0.0, 0.0, 0.052, 0.052]
      },
      {
        "key": 5,
        "name": "Food quality",
        "data": [0, 0, 6, 10],
        "percentages": [0.0, 0.0, 0.034, 0.057]
      },
      {
        "key": 1,
        "name": "Something else",
        "data": [0, 0, 3, 11],
        "percentages": [0.0, 0.0, 0.017, 0.063]
      }
    ]
  }
}

Result

Note

HappyOrNot might append more properties to this respons in the future without api version increase. Consider implementing your API integration to allow the result to have more properties (or nested properties) than mentioned above.

Name	Description
Success	Object containing two properties: meta for any additional information and data for the follow-up results. data contains two arrays: painPoints for negative (red buttons) follow-ups and highlights for positive (green buttons) follow-ups. Each array item is a FollowUpResult object In the case where no follow-up responses were given during the requested period, empty painPoints and highlights arrays are returned. Either painPoints or highlights array can also be empty if there are no follow-up options configured for them, or if there are no negative or positive results during the requested period.
Error	HTTP status code 400 in case of invalid parameters. HTTP status code 404 when no survey is found.

---

GET /v1/surveys/:key/rawresults

Retrieves raw feedback results for a specific survey.

Description

It is possible to get raw results instead of summed up results. Raw results have a separate timestamp for each feedback. This allows getting the time of the feedback as accurately as possible. Raw data does not use the misuse filtering that the normal results use: if you compare the raw results to the normal results, they will not exactly match.

Most terminals are able to report the time of feedback at the accuracy of one second. Some Smiley Terminals can only report results summed up by the hour due to more limited technical capabilities or poor local network connectivity.

Also, in some situations some older devices might need to batch multiple results to the same timestamp, therefore it is possible that in some conditions there are multiple results that appear to be exactly the same, but are actually separate button presses given inside a short time period.

The accurate raw results are returned in JSON Objects like this:

{ "ts": "2013-05-03T06:15:43.000Z", "r": 3 }

The Object represents one feedback. The individual response is returned as a number from 0 (Very Unhappy) to 3 (Very Happy) for 4 scale and from 0 (Very Unhappy) to 4 (Very Happy) for 5 scale.

The hourly summed up results are returned in a JSON Object like this:

{ "ts": "2013-05-03T06:00:0.000Z", "data": [4, 8, 12, 16] }

The four numbers in the array are the counts of four types of feedback on a Smiley Terminal for 4 scale. The indexes in the array run from 0 (Very Unhappy) to 3 (Very Happy) for 4 scale.

The five numbers in the array are the counts of five types of feedback on all types of devices, except Smiley Terminal, for 5 scale. The indexes in the array run from 0 (Very Unhappy) to 4 (Very Happy).

The response from this endpoint may contain both types of data objects in the same array of results returned.

If your terminals are not reporting the feedback times with sufficient accuracy, please contact HappyOrNot support or your HappyOrNot sales contact to see what can be done.

Parameters

Name	Description
key	required, identifier of the survey
date_start	optional, timestamp Timestamp of returned feedback data is equal or later than the value. If the parameter is not present, data is returned from the beginning.
date_end	optional, timestamp Timestamp of returned feedback data is sooner than the value. If the parameter is not present, data is returned to the end.
followup	optional, boolean If true returns also the follow-up that was selected if the survey has follow-ups (e.g. survey with Smiley Touch). Default value is false.
openfeedback	optional, boolean If true returns also the open feedback that was given if the survey supports open feedback (e.g. survey Smiley Touch and Smiley Digital). Default value is false. Note: enabling open feedback has an effect on the maximum number of feedback returned (see below).

Example requests and responses

GET /v1/surveys/3/rawresults?date_start=2013-05-03T00:00:00.000Z&date_end=2013-05-04T00:00:00.000Z&openfeedback=true&followup=true

{
  "meta": {},
  "data": [
    {
      "ts": "2013-05-03T00:15:43.000Z",
      "r": 3
    },
    {
      "ts": "2013-05-03T01:00:00.000Z",
      "data": [4, 8, 12, 16]
    },
    {
      "ts": "2013-05-03T11:01:04.000Z",
      "r": 2
    },
    {
      "ts": "2013-05-03T12:14:03.122Z",
      "r": 0,
      "f": {
        "key": 3,
        "name": "Service"
      },
      "o": {
        "text": "Bad service :("
      }
    },
    {
      "ts": "2013-05-03T12:18:01.456Z",
      "o": {
        "r": 1,
        "text": "The website is hard to navigate!"
      }
    }
  ]
}

GET /v1/surveys/3/rawresults?date_start=2016-01-01T00:00:00.000Z&date_end=2017-01-01T00:00:00.000Z

{
  "meta": {
    "moreResultsAfter": "2016-05-03T11:02:18.000Z"
  },
  "data": [
    {
      "ts": "2016-01-01T00:15:43.000Z",
      "r": 3
    },
    /* ... over 100000 result objects  */
    {
      "ts": "2016-05-03T11:02:17.000Z",
      "r": 2
    }
  ]
}

Result

Name	Description
Success	A single JSON object that contains meta and data keys. The data key contains an array of RawResult objects. The meta key contains paging information, if the response does not contain all the results. If there is so much feedback that some of it does not fit in the same HTTP response, the response will contain the feedback with the earliest timestamps. The maximum amount of feedback returned in a single response will vary, but should always be over 100 000 if results do not contain any open feedback. If open feedback is requested, the amount of feedback returned in a single response is limited to 10 000. Inside the meta key will be a moreResultsAfter key that will give you the timestamp from which to request more results with this same endpoint. This way you can retrieve any amount of feedback in several “pages.”
Error	Empty result data array when date_end is before date_start or if the dates are the same. HTTP status code 404 when no survey is found.

---