››

The REST Reporting API

The REST Reporting API helps you retrieve your reporting data and integrate Qualaroo with other applications you use in your business.

Benefits of using REST Reporting API:

Get efficient reporting and analysis of data
Extract valuable data to optimize business and boost user satisfaction

200 - Success - all good - the HTTP response body will contain the list of records you requested.
400 - Bad Request - some of your parameters are wrong. See the specific error message in the body of the HTTP response.
404 - Not Found - the survey you request data from does not exist.
500 - Internal Server Error - you did nothing wrong (“it’s not you, it’s us”). We will get right to it and fix the problem.

Endpoint

https://api.qualaroo.com/api/v1

You MUST all requests over SSL.

Retrieve Responses for a Survey

You must send a GET request to the URL in this form:

https://api.qualaroo.com/api/v1/nudges/SURVEY_ID/responses.json

SURVEY_ID is the id of the survey. You can find this in the URL when you edit the survey on your Qualaroo dashboard.

The API will return a list of objects in JSON format, where each object represents one respondent’s response to the survey. The object contains the respondent’s metadata (IP address, user agent, the page where the survey was presented, etc. - see the example below), their answers to the survey questions, and the custom attributes you tagged that respondent with. The records are sorted by the time the answer was submitted, in descending order.

(for ascending order, add a parameter at the end of the requested URL &order=asc)

https://api.qualaroo.com/api/v1/nudges/SURVEY_ID/responses.json?order=asc

Here is a sample object along with an explanation of each field:

{"id":32580126, -- id of the record

"time":"2013-08-20 06:29:50 -0700", -- Date and time when the response was recorded, including the timezone offset.

"token":"031e489c-409a-bd39-96b4-0884b8a8ee59", -- anonymous identifier of the respondent

"ip_address":"111.222.333.444", -- IP address of the respondent

"identity":"bob@somedomain.com", -- the identity that you tagged the respondent with

“page”: “https://mydomain.com/cool_page,” -- the page of your website where the respondent interacted with the survey

"referrer":"http://google.com/q=coolness", -- the URL of the referrer page (if there was one)

"user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_8_4) AppleWebKit/537.36 (KTML, like Gecko) Chrome/28.0.1500.95 Safari/537.36", -- info about the respondent's browser (also known as the User-Agent)

“answered_questions”: -- map of all the survey questions that the respondent answered. The keys in the map should not be assumed to have any special meaning.

{“142776”: -- this is an example of a radio button question

{"question_id":142776, -- record id of the question in Qualaroo system

“question_title”: “How well do you understand the real goals of people who visit your website?”, -- the text of the question

“answer”: “I have an obvious understanding,” -- the text of the selected answer.

"selected_option_id": 391235, -- record id of the chosen answer

“comment”: “This is my feedback...” -- text entered in the freeform comment area.

“properties”: -- if you tagged the respondent with custom name/value properties, these would appear here.

{ "plan": "Gold," "engagement_level": "High" }}

Date Range Parameters

You can request records for a particular date range. To do this, add start_date and/or end_date parameters to the URL. The value of these parameters must be an integer representing “UNIX time” in seconds. For example, the date/time “2013-07-15 17:47:24 -0700” must be represented as 1373935644.

Use this website to convert your date/time values into UNIX time.

Note that all response dates and times are recorded in the time zone setting you have selected in your account.

For more information on finding or changing this setting, please see this article from our Help Center.

If the date parameters are not provided, the API will assume you want to get responses starting at the time when you received your first response.

Pagination Parameters

The API returns up to 500 records at a time. If your survey has more than 500 responses for the entered date range, you must paginate your request, which means requesting one 500-response section at a time.

The two parameters that control pagination are

Offset -- a non-negative integer. For example, offset=1000 implies that the API will return records that match your query, starting with response number 1001. If offset is not provided, the API will start from the beginning, response number 1.
Limit -- the number of records you want to get in one response. The number must be between 0 and 500. The API will retrieve up to 500 responses if a limit is not provided.

How to Test It

You can test accessing the API using curl in your Terminal or Command Line program:

curl -u API_KEY: API_SECRET https://api.qualaroo.com/api/v1/nudges/SURVEY_ID/responses.json?start_date=1372207644&end_date=1373935644&offset=1000&limit=300

or simply in the address bar of your browser:

https://API_KEY:API_SECRET@api.qualaroo.com/api/v1/nudges/SURVEY_ID/responses.json?start_date=1372207644&end_date=1373935644&offset=1000&limit=300

Remember to use HTTPS in the URL, or the browser will prompt you to log in with your API key and secret.

All your responses will show up in plain text form on your screen:

But you will be able to find the beginning of each response by searching on the page for “id:”

Hint: Using the start_date, end_date, offset, and limit parameters that you see in the examples above is optional.

You can’t delete, change or otherwise break your response data just by looking at it in the browser :)

Caveats

If your survey has a question with checkboxes and the respondent checks more than one answer option, the answered_questions structure will have one record per selected checkbox.
This API call does not return records for clicks on buttons on message screens.

And that's it! If you encounter any issues or have any questions, don't hesitate to reach out to our support team.

Related Articles:

The REST Reporting API

Table of contents:

Here's How to Find Your API Key and API Secret:

Authentication

HTTP Status Codes

Endpoint

Retrieve Responses for a Survey

Date Range Parameters

Pagination Parameters

How to Test It

Caveats