HappyOrNot Customer API v2 (2.0)
Download OpenAPI specification:Download
HappyOrNot Customer API v2 is designed for
- fetching feedbacks of all type (button, followups, text, demographics, contact details)
- fetching information about experience points, surveys and other metadata related to fetching and displaying feedback
- fetching information about users of HappyOrNot Analytics
- fetching information about smileys, that is the physical devices or digital tokens for feedback gathering
Useful links:
Base URL for API calls:
https://api.happy-or-not.com/v2/
Example:
https://api.happy-or-not.com/v2/experience-points.json
Entities explained
Experience point = Represents a point of interaction for feedback gathering.
Can represent a physical location, e.g. "London Store 1" or a digital location, e.g. "Webshop checkout".
Group = Represents a grouping of experience points. Grouping can be e.g. geographical or organizational.
Examples are countries, cities or organization functions.
Groups and Experience points form a hierarchical tree structure, see example below.
Survey = Time-bounded surveys that contain a question and are associated with one or more experience points.
Question = Localizable questions are associated to surveys, e.g. "How was the service?"
Smiley = Physical or digital "device" that collect feedback. Smiley is associated with an experience point.
Types of smileys are Smiley Terminal, Smiley Touch and Smiley Digital.
User = User account of HappyOrNot Analytics, identified by email address and name. Has an associated role and data access.
Example for group / experience point hierarchy:
* Company X <- this is root group and parent of Finland and Sweden
* Finland <- this group is parent for Helsinki and Tampere store experience points
* Helsinki store <- this is an experience point
* Tampere store <- this is an experience point
* Sweden <- this group is parent for Stockholm and Malmö store experience points
* Stockholm store <- this is an experience point
* Malmö store <- this is an experience point
Feedback types explained
Button Feedback = The feedback type that is always present in surveys.
Visually represented as 4 or 5 smiley faces or NPS scale (0..10).
Followup Feedback = Predefined set of selectable textual values (max 6) to explain the button feedback given.
Text Feedback = Freeform text feedback. Available in Smileys that support keyboard input.
Demographics = AI based estimate on feedback giver's age and gender. Supported by Smiley Touch only.
Contact Details = If a feedback giver wants to get contacted, name and email or phone number can be given.
Entity Relationships Diagrams
Authentication/Authorisation
Authentication and authorisation is based on a token.
You can generate API v2 tokens in your Organization Settings page at HappyOrNot Analytics (you need to have Admin privileges to access that page).
You should provide a token with a request in one of the two ways:
- Request Header X-HON-API-Token. E.g. X-HON-API-Token: your-token-here (Suggested way)
- Query string parameter auth. E.g. /v2/experience-points.json?auth=your-token-here (Ok for testing)
Paging:
Paging of responses is controlled using offset and limit parameters.
HTTP response header X-More-Available (value "true" or "false") can be used to determine if more data is available.
Example:
https://api.happy-or-not.com/v2/alerts.json?offset=0&limit=500
HTTP response header Link is provided (if above described X-More-Available: true) and it includes the link to next page of results.
Example:
Link: https://api.happy-or-not.com/v2/alerts.json?offset=500&limit=500; rel="next"
Terms mapping between API v1 and API v2
API v1 API v2 ----------------------------------------------------------------------- Results/Rawresults Button Feedbacks Results/Rawresults Follow-up Feedbacks Results/Rawresults Text Feedbacks N/A Demographics N/A Contact Details Folders/Children Groups and Experience Points Surveys No direct mapping available, but v1 surveys are mappings of v2 Experience Points to v2 Surveys Questions Surveys N/A Question N/A Follow-up questions N/A Follow-up options Alerts Alerts N/A Alert Specifications N/A Alert Comments N/A Users N/A Smileys N/A Custom Data Fields N/A All localizations
Need help?
Please email support@happy-or-not.com to get more assistance.
List follow-up feedbacks
List follow-up feedbacks that match the given parameters
Authorizations:
path Parameters
| format required | string Enum: "json" "csv" |
query Parameters
| csvSeparator | string = 1 characters Default: "," Applied only for CSV responses |
| surveyId | integer <int64> Survey id that might have been acquired by using the /surveys endpoint |
| experiencePointId | integer <int64> Experience point id that might have been acquired by using the /experience-points endpoint |
| period | string^(today|yesterday|this-week|last-week|this-mo... Example: period=today,last-year,2023-12,2023-q3 If both period parameter and startDate/endDate are given, latter takes precedence. Week start is always Monday. |
| startDate | string <date> Example: startDate=2023-09-26 Inclusive start date. Defaults to current date. NOTE! startDate->endDate max interval is 1 year. |
| endDate | string <date> Example: endDate=2023-09-27 Exclusive end date. Defaults to tomorrow. NOTE! startDate->endDate max interval is 1 year. |
| includeMisuse | boolean Default: false If true, also feedback that has been deemed misuse will be included in the response. |
| offset | integer >= 0 Default: 0 Paging parameter to determine the index of the first item from the whole result set matching the search criteria. |
| limit | integer [ 0 .. 10000 ] Default: 1000 Paging parameter to determine the maximum size of the result set matching the search criteria. |
| order | string Default: "asc" Enum: "desc" "asc" Order parameter to sort feedbacks by time. |
Responses
Response samples
- 200
[- {
- "feedbackId": "8a5fb68c-aae2-438d-9a46-b4d8c8788e0b",
- "smileyId": 0,
- "localTime": "2019-08-24T14:15:22Z",
- "surveyId": 0,
- "experiencePointId": 0,
- "buttonIndex": 10,
- "misuse": true,
- "position": 0,
- "ui": "physical",
- "smileyType": "SMILEY_TERMINAL",
- "followupQuestionId": 0,
- "followupOptionId": 0,
- "followupOptionTextInDefaultLocale": "string"
}
]List text feedbacks
List text feedbacks that match the given parameters
Authorizations:
path Parameters
| format required | string Enum: "json" "csv" |
query Parameters
| csvSeparator | string = 1 characters Default: "," Applied only for CSV responses |
| surveyId | integer <int64> Survey id that might have been acquired by using the /surveys endpoint |
| experiencePointId | integer <int64> Experience point id that might have been acquired by using the /experience-points endpoint |
| period | string^(today|yesterday|this-week|last-week|this-mo... Example: period=today,last-year,2023-12,2023-q3 If both period parameter and startDate/endDate are given, latter takes precedence. Week start is always Monday. |
| startDate | string <date> Example: startDate=2023-09-26 Inclusive start date. Defaults to current date. NOTE! startDate->endDate max interval is 1 year. |
| endDate | string <date> Example: endDate=2023-09-27 Exclusive end date. Defaults to tomorrow. NOTE! startDate->endDate max interval is 1 year. |
| includeMisuse | boolean Default: false If true, also feedback that has been deemed misuse will be included in the response. |
| includeSpam | boolean Default: true If true, also feedback that has been deemed spam will be included in the response. |
| offset | integer >= 0 Default: 0 Paging parameter to determine the index of the first item from the whole result set matching the search criteria. |
| limit | integer [ 0 .. 10000 ] Default: 1000 Paging parameter to determine the maximum size of the result set matching the search criteria. |
| order | string Default: "asc" Enum: "desc" "asc" Order parameter to sort feedbacks by time. |
Responses
Response samples
- 200
[- {
- "feedbackId": "8a5fb68c-aae2-438d-9a46-b4d8c8788e0b",
- "smileyId": 0,
- "localTime": "2019-08-24T14:15:22Z",
- "surveyId": 0,
- "experiencePointId": 0,
- "buttonIndex": 10,
- "misuse": true,
- "position": 0,
- "ui": "physical",
- "smileyType": "SMILEY_TERMINAL",
- "text": "string",
- "textInEnglish": "string",
- "spam": true
}
]List demographics information
List demographics (age, gender) related to feedback that match the given parameters
Authorizations:
path Parameters
| format required | string Enum: "json" "csv" |
query Parameters
| csvSeparator | string = 1 characters Default: "," Applied only for CSV responses |
| surveyId | integer <int64> Survey id that might have been acquired by using the /surveys endpoint |
| experiencePointId | integer <int64> Experience point id that might have been acquired by using the /experience-points endpoint |
| period | string^(today|yesterday|this-week|last-week|this-mo... Example: period=today,last-year,2023-12,2023-q3 If both period parameter and startDate/endDate are given, latter takes precedence. Week start is always Monday. |
| startDate | string <date> Example: startDate=2023-09-26 Inclusive start date. Defaults to current date. NOTE! startDate->endDate max interval is 1 year. |
| endDate | string <date> Example: endDate=2023-09-27 Exclusive end date. Defaults to tomorrow. NOTE! startDate->endDate max interval is 1 year. |
| includeMisuse | boolean Default: false If true, also feedback that has been deemed misuse will be included in the response. |
| offset | integer >= 0 Default: 0 Paging parameter to determine the index of the first item from the whole result set matching the search criteria. |
| limit | integer [ 0 .. 10000 ] Default: 1000 Paging parameter to determine the maximum size of the result set matching the search criteria. |
| order | string Default: "asc" Enum: "desc" "asc" Order parameter to sort feedbacks by time. |
Responses
Response samples
- 200
[- {
- "feedbackId": "8a5fb68c-aae2-438d-9a46-b4d8c8788e0b",
- "smileyId": 0,
- "localTime": "2019-08-24T14:15:22Z",
- "surveyId": 0,
- "experiencePointId": 0,
- "buttonIndex": 10,
- "misuse": true,
- "smileyType": "SMILEY_TERMINAL",
- "gender": "male",
- "age": 0
}
]List contact details information
List contact details (name, email/phone number) related to feedback that match the given parameters
Authorizations:
path Parameters
| format required | string Enum: "json" "csv" |
query Parameters
| csvSeparator | string = 1 characters Default: "," Applied only for CSV responses |
| surveyId | integer <int64> Survey id that might have been acquired by using the /surveys endpoint |
| experiencePointId | integer <int64> Experience point id that might have been acquired by using the /experience-points endpoint |
| period | string^(today|yesterday|this-week|last-week|this-mo... Example: period=today,last-year,2023-12,2023-q3 If both period parameter and startDate/endDate are given, latter takes precedence. Week start is always Monday. |
| startDate | string <date> Example: startDate=2023-09-26 Inclusive start date. Defaults to current date. NOTE! startDate->endDate max interval is 1 year. |
| endDate | string <date> Example: endDate=2023-09-27 Exclusive end date. Defaults to tomorrow. NOTE! startDate->endDate max interval is 1 year. |
| includeMisuse | boolean Default: false If true, also feedback that has been deemed misuse will be included in the response. |
| offset | integer >= 0 Default: 0 Paging parameter to determine the index of the first item from the whole result set matching the search criteria. |
| limit | integer [ 0 .. 10000 ] Default: 1000 Paging parameter to determine the maximum size of the result set matching the search criteria. |
| order | string Default: "asc" Enum: "desc" "asc" Order parameter to sort feedbacks by time. |
Responses
Response samples
- 200
[- {
- "feedbackId": "8a5fb68c-aae2-438d-9a46-b4d8c8788e0b",
- "smileyId": 0,
- "localTime": "2019-08-24T14:15:22Z",
- "surveyId": 0,
- "experiencePointId": 0,
- "buttonIndex": 10,
- "misuse": true,
- "position": 0,
- "smileyType": "SMILEY_TERMINAL",
- "name": "John Doe",
- "email": "test@example.com",
- "phoneNumber": 358401234567
}
]List experience points and groups
Tree of groups and experience points in tabular format
Authorizations:
path Parameters
| format required | string Enum: "json" "csv" |
query Parameters
| csvSeparator | string = 1 characters Default: "," Applied only for CSV responses |
| rootExperiencePointId | integer <int64> Root exp. point id, if omitted, all authorised groups and exp.points are returned |
| type | string Enum: "GROUP" "EXPERIENCE_POINT" Only items of given type are returned, if omitted, all authorised groups and exp.points are returned |
Responses
Response samples
- 200
[- {
- "experiencePointId": 0,
- "name": "string",
- "parent": 0,
- "type": "GROUP"
}
]List surveys
List of all surveys
Authorizations:
path Parameters
| format required | string Enum: "json" "csv" |
query Parameters
| csvSeparator | string = 1 characters Default: "," Applied only for CSV responses |
Responses
Response samples
- 200
[- {
- "surveyId": 0,
- "questionId": 0,
- "defaultLocale": "en_US",
- "questionTextInDefaultLocale": "How was the service?",
- "surveyType": "CUSTOMER",
- "feedbackScale": "four",
- "indexType": "HAPPY",
- "state": "active"
}
]List questions
List of all questions
Authorizations:
path Parameters
| format required | string Enum: "json" "csv" |
query Parameters
| csvSeparator | string = 1 characters Default: "," Applied only for CSV responses |
Responses
Response samples
- 200
[- {
- "questionId": 0,
- "defaultLocale": "en_US",
- "questionTextInDefaultLocale": "How was the service?"
}
]Endpoints and data definitions related to localizations for question used in surveys
List question localizations
List of all question localizations
Authorizations:
path Parameters
| format required | string Enum: "json" "csv" |
query Parameters
| csvSeparator | string = 1 characters Default: "," Applied only for CSV responses |
| questionId | integer <int64> list question localizations only for given question |
Responses
Response samples
- 200
[- {
- "questionId": 0,
- "locale": "en_US",
- "text": "How was the service?"
}
]Endpoints and data definitions related to questions used for follow ups in surveys
List follow-up questions
List of all follow-up questions
Authorizations:
path Parameters
| format required | string Enum: "json" "csv" |
query Parameters
| csvSeparator | string = 1 characters Default: "," Applied only for CSV responses |
Responses
Response samples
- 200
[- {
- "followupQuestionId": 0,
- "surveyId": 0,
- "positive": true,
- "questionTextInDefaultLocale": "What was particularly good?"
}
]Endpoints and data definitions related to localizations for questions used for follow ups in surveys
List follow-up question localizations
List of all follow-up question localizations
Authorizations:
path Parameters
| format required | string Enum: "json" "csv" |
query Parameters
| csvSeparator | string = 1 characters Default: "," Applied only for CSV responses |
| followupQuestionId | integer <int64> list follow-up question localizations only for given follow-up question |
Responses
Response samples
- 200
[- {
- "followupQuestionId": 0,
- "locale": "en_US",
- "text": "string"
}
]Endpoints and data definitions related to selectable options for follow ups in surveys
List follow-up options
List of all follow-up options
Authorizations:
path Parameters
| format required | string Enum: "json" "csv" |
query Parameters
| csvSeparator | string = 1 characters Default: "," Applied only for CSV responses |
Responses
Response samples
- 200
[- {
- "followupOptionId": 0,
- "followupQuestionId": 0,
- "optionTextInDefaultLocale": "string"
}
]Endpoints and data definitions related to localizations for selectable options for follow ups in surveys
List follow-up option localizations
List of all follow-up option localizations
Authorizations:
path Parameters
| format required | string Enum: "json" "csv" |
query Parameters
| csvSeparator | string = 1 characters Default: "," Applied only for CSV responses |
| followupOptionId | integer <int64> list localizations only for given follow-up option |
Responses
Response samples
- 200
[- {
- "followupOptionId": 0,
- "locale": "en_US",
- "text": "string"
}
]Endpoints and data definitions related to alert specifications based on which alerts are triggered
List alert specifications
List of all alert specifications
Authorizations:
path Parameters
| format required | string Enum: "json" "csv" |
query Parameters
| csvSeparator | string = 1 characters Default: "," Applied only for CSV responses |
Responses
Response samples
- 200
[- {
- "alertSpecificationId": 0,
- "surveyId": 0,
- "experiencePointId": 0,
- "alertSpecificationType": "negative",
- "parameters": "key1=value1 key2=value2 key3=value3a,value3b"
}
]Endpoints and data definitions related to alerts which have been triggered by incoming feedback, based on alert specfications
List alerts
List of all alerts
Authorizations:
path Parameters
| format required | string Enum: "json" "csv" |
query Parameters
| csvSeparator | string = 1 characters Default: "," Applied only for CSV responses |
| surveyId | integer <int64> Survey id that might have been acquired by using the /surveys endpoint |
| experiencePointId | integer <int64> Experience point id that might have been acquired by using the /experience-points endpoint |
| period | string^(today|yesterday|this-week|last-week|this-mo... Example: period=today,last-year,2023-12,2023-q3 If both period parameter and startDate/endDate are given, latter takes precedence. Week start is always Monday. |
| startDate | string <date> Example: startDate=2023-09-26 Inclusive start date. Defaults to current date. NOTE! startDate->endDate max interval is 1 year. |
| endDate | string <date> Example: endDate=2023-09-27 Exclusive end date. Defaults to tomorrow. NOTE! startDate->endDate max interval is 1 year. |
| offset | integer >= 0 Default: 0 Paging parameter to determine the index of the first item from the whole result set matching the search criteria. |
| limit | integer [ 0 .. 10000 ] Default: 1000 Paging parameter to determine the maximum size of the result set matching the search criteria. |
Responses
Response samples
- 200
[- {
- "alertId": 0,
- "alertSpecificationId": 0,
- "surveyId": 0,
- "experiencePointId": 0,
- "beginTime": "2019-08-24T14:15:22Z",
- "endTime": "2019-08-24T14:15:22Z",
- "alertSpecificationType": "negative",
- "parameters": "key1=value1 key2=value2 key3=value3a,value3b",
- "acknowledged": true,
- "acknowledgedByUserId": 0,
- "acknowledgedTime": "2019-08-24T14:15:22Z"
}
]Endpoints and data definitions related to alert comments which have been written for alerts
List alert comments
List of all alert comments
Authorizations:
path Parameters
| format required | string Enum: "json" "csv" |
query Parameters
| csvSeparator | string = 1 characters Default: "," Applied only for CSV responses |
| surveyId | integer <int64> Survey id that might have been acquired by using the /surveys endpoint |
| experiencePointId | integer <int64> Experience point id that might have been acquired by using the /experience-points endpoint |
| period | string^(today|yesterday|this-week|last-week|this-mo... Example: period=today,last-year,2023-12,2023-q3 If both period parameter and startDate/endDate are given, latter takes precedence. Week start is always Monday. |
| startDate | string <date> Example: startDate=2023-09-26 Inclusive start date. Defaults to current date. NOTE! startDate->endDate max interval is 1 year. |
| endDate | string <date> Example: endDate=2023-09-27 Exclusive end date. Defaults to tomorrow. NOTE! startDate->endDate max interval is 1 year. |
| offset | integer >= 0 Default: 0 Paging parameter to determine the index of the first item from the whole result set matching the search criteria. |
| limit | integer [ 0 .. 10000 ] Default: 1000 Paging parameter to determine the maximum size of the result set matching the search criteria. |
Responses
Response samples
- 200
[- {
- "alertCommentId": 0,
- "alertId": 0,
- "userId": 0,
- "time": "2019-08-24T14:15:22Z",
- "comment": "string"
}
]List users
List of all users
Authorizations:
path Parameters
| format required | string Enum: "json" "csv" |
query Parameters
| csvSeparator | string = 1 characters Default: "," Applied only for CSV responses |
Responses
Response samples
- 200
[- {
- "userId": 0,
- "email": "test@example.com",
- "firstName": "Jane",
- "lastName": "Doe",
- "rootExperiencePointId": 0,
- "role": "USER",
- "locale": "en_US",
- "loginAllowed": true,
- "loginMethod": "EMAIL_PASSWORD",
- "lastLogin": "2019-08-24T14:15:22Z",
- "created": "2019-08-24T14:15:22Z"
}
]List smileys
List of all smileys
Authorizations:
path Parameters
| format required | string Enum: "json" "csv" |
query Parameters
| csvSeparator | string = 1 characters Default: "," Applied only for CSV responses |
Responses
Response samples
- 200
[- {
- "smileyId": 0,
- "name": "string",
- "serialNumber": "string",
- "token": "string",
- "smileyType": "SMILEY_TERMINAL"
}
]List custom data fields for experience point
Experience point's or tree of experience point's custom data fields in list format
Authorizations:
path Parameters
| format required | string Enum: "json" "csv" |
query Parameters
| csvSeparator | string = 1 characters Default: "," Applied only for CSV responses |
| experiencePointId | integer <int64> Exp. point id, if omitted, uses rootExperiencePointId |
| rootExperiencePointId | integer <int64> Root exp. point id, if omitted and no experiencePoint id is provided returns every custom data field |
Responses
Response samples
- 200
[- {
- "experiencePointId": 0,
- "label": "string",
- "value": "string"
}
]