Skip to content
HappyOrNot Documentation

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

CodeURL
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
NameDescription
keyThe identifier of the survey
questionObject of the question in default locale.
folderObject of the folder where survey is located.
timeZoneThe time zone of survey in “Area/Location”-format.
activePeriodsAn 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.
surveyTypeA 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.
indexType1A string representing the index type. Possible values currently are: HAPPY, NPS or AVERAGE.
feedbackScale1A string representing the feedback scale. Possible values currently are: FOUR, FIVE or FIVE_REVERSED.

1 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.

Properties
NameDescription
tsTimestamp in survey time zone
rIndex. 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.
relevanceoptional Float from 0.0 (worst) to 1.0 (best). Automatically analyzed quality value for the open feedback text.
spamoptional, true or false. true if feedback is marked as spam.
fOptional, 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.
textThe 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.

Properties
NameDescription
keyUnique id of the follow-up option
nameFollow-up text in question’s default locale

Example JSON objects

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

FollowUpResult

JSON presentation of follow-up option results.

FollowUp object appended with results:

Properties
NameDescription
dataResponses. 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
percentagesRelative 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.

FollowUp object appended with results:

Properties
NameDescription
tsTimestamp in survey time zone
roptional 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.
dataoptional 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/
/rawresults
foptional FollowUp object. The follow-up that was chosen when feedback was given, if any.
ooptional

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
NameDescription
keyrequired, 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
NameDescription
SuccessSurvey
ErrorHTTP status code 404 when no survey is found.

GET /v1/surveys/:key/results

Retrieves feedback results for specific survey.

Parameters
NameDescription
keyrequired, identifier of the survey
date_startoptional, 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_endoptional, timestamp

Timestamp of returned feedback data is sooner than the value. For default values, see date_start

truncateoptional, 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.

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
NameDescription
SuccessArray 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.
ErrorHTTP 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
NameDescription
keyrequired, identifier of the survey
date_startoptional, timestamp

Timestamp of returned survey open feedback data is equal or later than the value.

date_endoptional, 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
NameDescription
SuccessA 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”.

ErrorHTTP 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
NameDescription
keyrequired, identifier of the survey
date_startoptional, timestamp

Timestamp of returned survey follow-up result data is equal or later than the value.

date_endoptional, 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
NameDescription
SuccessObject 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.

ErrorHTTP 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
NameDescription
keyrequired, identifier of the survey
date_startoptional, 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_endoptional, timestamp

Timestamp of returned feedback data is sooner than the value. If the parameter is not present, data is returned to the end.

followupoptional, 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.

openfeedbackoptional, 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
NameDescription
SuccessA 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.”

ErrorEmpty 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.