About the HEART Analytics API
Userlane offers an HTTP REST API that allows you to export HEART analytics data in JSON format for your internal reporting needs.
This article covers
Requirements
It requires technical knowledge so the assistance of a developer is recommended.
Why use it
Use the data to:
send data from Userlane HEART to your BI tool of choice for deeper analysis and to enrich other data you gather internally
bring Userlane HEART data to a wider audience of stakeholders at your organization
Overview of exported data
When you export data using the Userlane HEART API, you will get a breakdown of HEART data for all dates in the request. This means that for each date you will receive the overall HEART score as well as the individual letter scores, plus the number of users and number of sessions.
The results are exported to a JSON format which you can process for your needs with the help of a developer.
Here is a sample result in JSON format:
Export the data
Prerequisites
This type of data export is protected and requires authentication by an Authorization Token. You can generate your token under Settings/Your Profile/API Token in the Userlane Portal.
💡 The token is generated for each Userlane Manager individually. You can generate a new token at any time using the same button in your Portal.
To perform the API export, navigate to https://dev.userlane.com/reference/heartdata and follow the steps outlined below.
Preparing a request
For the request to be successful, you will need to fill out the tool with the required data in the required format.
This is the general view of the export page. We will go through all the required fields below:
Parameters
In order to target the data for your application and for a specific time span, you will need to enter search parameters:
Application ID: the individual Userlane ID of your application
Start + End: here you can select a time span for the data you want to export. Use the following time format: 2023-04-01T00:00:00+00:00 (the bold section sets the date, here, it is 1 April 2023, you can leave the rest like in the example)
Page and Limit options: the maximum number of elements per page is 1000, if your result is bigger, you will need to request the data for each page separately by changing the page number and running the query again
Below is an example with parameters:
Authentication
The request is only possible if authenticated with the correct token. Please paste it into the Authentication field:
Run the request
Once all the parameters are set, you can run the query by clicking on the “Try it” button in the CURL section and you will see the results in the Response section below.
You can copy the results by clicking on the Copy icon.
The request code can be copied as well and used in another tool.
Troubleshooting
If the request is not successful, you will see an error message in the result section. You may look for possible issues based on the message it contains.
The most common errors relate to the wrong date format or incorrect/ invalid token being used, like in this example:
If you see any errors, please revise all the data based on the article. If the issue still occurs, please reach out to us.
