The REST Reporting API

Access to the REST API is part of our Premium Plan. 

Getting Started

The REST API allows customers to retrieve the data from their Qualaroo account. Here is where to find your API Key and Secret:

1. Log into Qualaroo
2. Click on "Account"
3. Scroll to the bottom of the page
4. There you will find your API Key and see the option to generate your API Secret.

Authentication

You need two pieces of information to authenticate with the API - API Key and API Secret. You will find this info on your account page.

The REST API supports HTTP Basic Authentication.

Since requests to the API can be made only over SSL, your API Key and API secret are encrypted.

HTTP Status Codes

• 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 are requesting data for 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

All requests MUST be issued over SSL.

Retrieve Responses for a survey

A GET request must be sent to a URL of 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 are editing the survey in your Qualaroo dashboard.

The API will return a list of objects in JSON format, where each object represents one respondent's response on the survey. The object contains the respondent's metadata (IP address, user agent, page where the survey was presented, etc. - see the example below), her 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 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?", -- text of the question

"answer":"I have a very clear understanding", -- text of the selected answer

"selected_option_id": 391235, -- record id of the selected 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 will 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 a integer representing "UNIX time" in seconds. For example, the date/time "2013-07-15 17:47:24 -0700" must be represented as 1373935644.

You can use this website to quickly 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 how to find or change 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 date range you are requesting, you must paginate your request, which means request it one 500-response section at a time.

The two parameters that control pagination are:

• offset -- a non-negative integer. For example, offset=1000 means 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. If limit is not provided, the API will retrieve up to 500 responses.

How to try 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 plaintext 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.

Don't be afraid to give this a try! All you are doing is viewing your responses in a different format from the CSV file, or the web interface. 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 checked more than one checkbox, the answered_questions structure will have one record per each selected checkbox.
• This API call does not return records for clicks on buttons on message screens.