Survey Response Reporting

Locating your report_id: This method can only be run on saved reports. Once you save your report you can visit the View Survey Visits page, on which you'll see at the top a section labeled “Reporting API URL.” This will be the full URL you will use for survey response reporting via the API.

Survey Response Reporting

GET https://insight.plumvoice.com/api/report/{report_id}

This method allows you to fetch CSV exports of your saved survey reports programmatically (or through your browser, authenticating via http basic). There are a number of optional parameters supplied which will allow for you to paginate responses when working with very large data sets.

Path Parameters

Name	Type	Description
report_id	integer	The report_id for your saved report.

Headers

Name	Type	Description
content-type	string	application/x-www-form-urlencoded

Request Body

Name	Type	Description
start_timestamp	integer	Unix timestamp to filter your survey responses to a specific date range.
end_timestamp	integer	Unix timestamp to filter your survey responses to a specific date range.
offset	integer	Offset when querying for a row range. The offset will indicate at which row in the result set to begin including rows in the response csv. If you set an offset of 25, the first 25 rows will be ignored and row 26 will be the first row included in the response.
limit	integer	Limit the number of rows returned. The limit must be between 1 and 10,000. If no limit is supplied, the limit will be 500.

200 Along with having the new report created in CSV format at 'reports/todays_report.csv', running the above script with proper credentials produces the following output. The returned header values indicate the following: 1.) the request implicitly started at offset 0 (no offset specified, so the default was applied); 2.) the limit of 10 was applied, as supplied in the query string parameters; 3.) we received 10 rows in our response body; 4.) there were 12 total rows available for the report.

HTTP/1.1 200 OK
Date: Thu, 22 Sep 2016 18:41:49 GMT
Server: Apache/2.2.29 (Unix) mod_ssl/2.2.29 OpenSSL/1.0.2d PHP/5.4.45
X-Powered-By: PHP/5.4.45
Content-Disposition: attachment; filename=report.csv
X-Plum-Total-Rows: 12
X-Plum-Returned-Rows: 10
X-Plum-Row-Offset: 0
X-Plum-Row-Limit: 10
Content-Length: 941
Content-Type: text/csv; charset=utf-8


"Survey ID","Survey Name","Visit Type","Caller ID/IP Address","Phone Number",Start,End,Completed,"Was this information helpful?","What is your favorite decimal number?"
19571,"test reporting api",web,192.168.1.1,NA,1473861379,1473861390,1,1,55.5
19571,"test reporting api",web,192.168.1.1,NA,1473861348,1473861376,1,0,3
19571,"test reporting api",web,192.168.1.1,NA,1473861309,1473861318,1,0,67.5
19571,"test reporting api",web,192.168.1.1,NA,1473861298,1473861305,1,0,87.8
19571,"test reporting api",web,192.168.1.1,NA,1473861289,1473861294,1,1,78.8
19571,"test reporting api",web,192.168.1.1,NA,1473861279,1473861286,1,1,5656.66
19571,"test reporting api",web,192.168.1.1,NA,1473861254,1473861261,1,1,45.76
19571,"test reporting api",web,192.168.1.1,NA,1473861234,1473861251,1,1,97.6
19571,"test reporting api",web,192.168.1.1,NA,1473861223,1473861230,1,1,56.45
19571,"test reporting api",web,192.168.1.1,NA,1473861206,1473861212,1,0,45.5

400 Example: the report_id supplied was not valid.

JSON

{"error":"You do not have permission to access this report"}

XML

<?xml version="1.0"?>
<result>
  <error>You do not have permission to access this report</error>
</result>

NOTE: Results will be ordered in descending order by start time, so the most recent response will always be first. The start_timestamp and end_timestamp parameters are dependent on one another; if you supply one, you must supply the other. By default, if no parameters are supplied, the response will contain the full date range of survey responses with an offset of 0 and limit of 500, returning up to 500 of the most recent survey visits.

Possible Response Codes

• 200: success

• 400: parameters supplied were not valid

• 401: authentication headers invalid or the account is inactive

• 403: you do not own the report

• 404: the saved report was not found or no rows were matched for the report

• 405: invalid HTTP method supplied (only GET allowed)

• 500: server error

Response Notes

Headers

Since the payload of a successful request will be the csv data for the report, we've included a number of headers that will act as metadata related to the returned data and the overall data for the report. The following headers will be included:

Header Name	Type	Description
X-Plum-Total-Rows	int	This value indicates the total number of rows that matched the query.
X-Plum-Returned-Rows	int	This value indicates the total number of rows returned in the response.
X-Plum-Row-Offset	int	This value indicates the offset applied to the current response.
X-Plum-Row-Limit	int	This value indicates the limit applied to the current response.

These headers should allow you to paginate your requests, if you're working with a very large data set.

Structure

The return structure differs based on whether rows were matched or not.

A successful response, one in which rows were matched, will always return an http code of 200 and the body of the response will be in text/CSV format, which will be the raw output of your CSV report. A sample of a successful response would be the following:

"Survey ID","Survey Name","Visit Type","Caller ID/IP Address","Phone Number",Start,End,Completed,"Was this information helpful?","What is your favorite decimal number?"
19571,"test reporting api",web,192.168.1.1,NA,1473861379,1473861390,1,1,55.5
19571,"test reporting api",web,192.168.1.1,NA,1473861348,1473861376,1,0,3

NOTE: A successful response will always contain the header fields of the CSV. If you are paginating, be sure to trim this off before appending the rows to an existing CSV.

An unsuccessful request, one in which no csv rows were returned and the http code was not 200, contains the following item(s):

Name	Data Type	Always Present	Description
error	string	yes	Descriptive message indicating what error(s) occurred

Sample Code

This sample PHP code makes a request to fetch the first 10 items of a saved report:

<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://insight.plumvoice.com/api/report/1551?limit=10");
curl_setopt($ch, CURLOPT_USERPWD, 'your_login:your_dev_pin'); // http basic auth credentials
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/x-www-form-urlencoded', 'Accept: application/json'));
curl_setopt($ch, CURLOPT_HEADER, 1); // return headers
$result = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$headers = substr($result, 0, curl_getinfo($ch, CURLINFO_HEADER_SIZE)); // get just the headers
$body = substr($result, curl_getinfo($ch, CURLINFO_HEADER_SIZE)); // get everything after the headers
if ($http_code == 200) {
	// $body will contain the actual csv data
	// you can write this directly to a file
	file_put_contents('reports/todays_report.csv', $body);
	// or output it
	echo $headers."\n";
	echo $body."\n";
	// or whatever you would like..
} else {
	// non 200 indicates we did not get csv data, print the json body
	echo $body;
}