The Data Export feature provides the ability to export non-aggregated survey answers out of the Peakon system. Administrators can enable it at the Company level (i.e. it is not possible to turn it on for a subset of employees only), and is designed for enterprise companies with the appropriate safeguards and people analytics teams who wish to have access to raw Peakon data. The feature is best suited for large companies and can be enabled by request.
This article contains:
The feature is designed to be used by developers to feed data automatically from Peakon into third party tools. It contains survey scores and responses (across question sets including Value and Custom Questions) and identifying email or employee ID.
The survey experience
Once the Data Export feature is switched on, Peakon will automatically adjust the survey landing for employees. This ensures that it is clear and transparent to survey participants on how their information will be managed and protected.
- A new updated survey disclaimer that is displayed when administering the survey on the Survey Landing Page
- Customizable text on the survey landing page that can be inserted by organizations to provide more information to employees before they start their survey. This can be customized at a schedule level once the Data Export feature is enabled. See the Configuration section for more on this.
What data can be exported
The following fields are included in the Data Export API:
|accountEmail||the email of the employee|
|answerComment||the comment entered for this survey answer (if entered)|
|answerId||a unique id for this answer|
|answerLocale||the language used by the employee|
|answerScore||the score given to the question|
|answerSkipReason||if the employee skipped the question, which reason did they select|
|categoryGroup||the type of question set the category|
|categoryId||a unique id for the category|
|categoryStandard||if this is a question was a standard question, this will be an identifier for that standard|
|companyId||a unique id for the company|
||a custom id that can be assigned to an employee|
|employeeId||a unique id for the employee|
|questionId||a unique id for the question|
|questionText||the text presented to the user|
|questionType||can be one of “scale”, “text” or “value”|
|responseId||a unique id for the response. A survey response is the collection of answers that was given by an employee for a given survey round. Each employee can make one response per round.|
|roundEnd||the date for which the round ends|
|roundId||a unique id for the round|
|roundOpensAt||the date for which the round opens|
|roundType||can be one of “automatic” or “test”. Automatic rounds are regular rounds, whereas test rounds are created using the test round feature in the dashboard.|
|scheduleContextName||The name of the schedule|
|scheduleId||a unique id for the schedule|
The below process must be completed before you enable the Data Export API feature. This ensures that this feature is right for your organization.
- Before switching on this feature, we recommend you consider the potential impact on survey participation and responses in light of these changes, and any other engagement activities you are working on. Implementing a fully transparent survey requires a great deal of trust from your employees. We believe data quality is important in driving change and improving employee experiences, so ensuring this is maintained for your organization is vital.
- Survey answers will only be exported from the date the feature was enabled. Answers prior to this date are not exportable.
To enable the feature, please speak to your Customer Success Consultant and follow the process below:
|1||Review the information provided in the Data Export Customer Guide document (available on request).|
|2||Speak to your Privacy / Legal / DPO counsel and Analytics teams (including any other key stakeholders involved in the Engagement survey) to understand the requirements of enabling this feature and ensure group sign-off.|
|3||Provide the API Documentation to your development team to ensure that survey answers can be inputted into your preferred analytics tool.|
|4||Set a date to enable the Data Export feature. We recommend the feature is not turned on while there are active rounds, since the experience will change for the surveyed employees. Turning on the feature in the middle of a survey round will mean that some survey results will be included in the export while others within the same round, but submitted prior to the enablement date, will be excluded.|
|5||We strongly encourage you to communicate the update in your pre-launch communications to employees to let them know of the change and explain why you are analysing their results in this matter. For example, provide information that individual survey responses/engagement data will be brought into in-house business intelligence systems for the purpose of improving the employee experience, and providing insight to drive engagement.|
|6||Once you have decided on a date for launch, your Customer Success Consultant will be able to switch this feature on your preferred date.|
|7||If needed, update the customisable text on the survey landing page.|
To get started, reach out to your Customer Success Consultant to get the functionality enabled.
How to set up API and request token
- Go to Administration > Integrations
- Click on the Custom apps tab
- Set a name
- Pick the 'answer' option in the Permissions drop down (the 'answer' option will only appear if the functionality has been enabled by Peakon)
- Make a copy of the access token, and store in a safe, secret location
Upon creation you will see the newly created integration listed in the overview, and can at any time revoke the access permission by clicking 'Remove'.
Authentication with the Peakon API
As referenced in https://developer.peakon.com/reference#authentication-1 the access token can be used to get a JWT authorization token that can be used to query the GET end-points in the Peakon API. For instance, in order to retrieve the scores in the user's account you can make a GET call to https://api.peakon.com/v1/engagement/overview. Please see the authentication documentation above for a full description of all existing possibilities.
Calling the Endpoint
After acquiring a JWT authorization token, the client is ready to call the answer export endpoint with a GET request to https://api.peakon.com/v1/answers/export
Adjusting the Page Size
The amount of answers returned can be adjusted using the per_page parameter, like this https://api.peakon.com/v1/answers/export?per_page=50
The maximum amount of records that can be returned is 20,000 in a single request.
How to customise survey landing page text
- Go to Administration > Schedules
- Click View on the relevant schedule
- Click on the Email tab
- Customize the Confidentiality disclaimer
- Add any translations, if needed
- Click Save settings
The confidentiality disclaimer is only visible for customers using the Data Export functionality.