Plum Insight Documentation
api

Insight API

Overview

The Insight API provides a programmatic access to, and supports the following functionality within the Insight interface:

Base URL

The base url for all requests should be made to:

https://insight.plumvoice.com/api

Authentication

All API requests are authenticated using HTTP Basic Authentication. The username value will be the email address users use to log in to their Insight account and the password will be their Developer Key, located within the Account Settings interface.

Depending on the HTTP libraries available in one's chosen programming language, users may be able to use built-in HTTP Basic Authentication. If this is not available, users can build the header manually by base64 encoding their username and developer key concatenated with a colon and then prefixing it with 'Basic'. Manually built HTTP Basic Authentication in this instance should look like:

"Authentication: Basic your_base64_encoded_string"

Any requests made without this header or with invalid credentials will return HTTP 401 Unauthorized and the body will provide details about what went wrong with the request.

Supported Accept Headers

The API methods honor the following Accept header values to determine the Content-Type and representation for the response:

  • application/json
  • application/xml

Specifying a different Accept header will return a Content-Type 'application/json' by default.

Locating your survey_id and instance_id

Your survey_id and instance_id values are utilized in many areas of the Insight API. To locate these values for your survey, you'll need to visit the Outbound Queue. At the top you will see “Outbound API Values” which displays the survey_id and instance_id for your survey.

Checking Total Responses for a Survey

URL:

https://insight.plumvoice.com/api/surveys/{survey_id}/{instance_id}/responses

HTTP method: GET

Content-Type: application/x-www-form-urlencoded

Possible Response Codes:

  • 200: success
  • 401: authentication headers invalid or the account is inactive
  • 404: deployment or survey was not found
  • 405: invalid HTTP method supplied (only GET allowed)
  • 415: unsupported media type (Content-Type value in request)
  • 500: database error

The return structure contains the following item(s):

NameData TypeAlways PresentDescription
successbooleanyesIndicates the outcome of the request
errorstringnoIf the success value is false this provides a message indicating what error(s) occurred
total_reponsesintnoThe total number of times the survey has been taken. This will be present when the success value is true

Sample Code

This sample PHP code makes a request to a deployed survey that returns the total number of responses:

<?php
$ch = curl_init();
$url = 'https://insight.plumvoice.com/api/surveys/{survey_id}/{instance_id}/responses';
$username = 'you@yourdomain.com';
$password = 'your_developer_key';
curl_setopt($ch, CURLOPT_USERPWD, $username.":".$password);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Accept: application/json", "Content-Type: application/x-www-form-urlencoded"));
$result = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($result);
var_dump($http_code);

Sample Response

On success:

JSON response:
HTTP Code 200

{'success':true,'total_responses':'25'}

The same value with an Accept header of 'application/xml' set in the request would be:

XML response:
HTTP Code 200

<result>
  <success>true</success>
  <total_responses>25</total_responses>
</result>

On Failure (this example provides an invalid survey_id or instance_id):

JSON response:
HTTP Code 404

{'success':false,'error':'No deployment was found for that survey and instance id combination.'}

The same response with an Accept header of 'application/xml' set in the request would be:

XML response:
HTTP Code 404

<result>
  <success>false</success
  <error>No deployment was found for that survey and instance id combination.</error>
</result>

Queuing an Outbound Call

URL:

https://insight.plumvoice.com/api/surveys/{survey_id}/{instance_id}/queue

HTTP method: POST

Content-Type: application/x-www-form-urlencoded

Request Parameters:

NameData TypeRequiredDescription
phone_numberstringyesThe phone number to which the outbound call should be placed. There are multiple ways to format phone numbers. They can include the 'tel:' prefix. ANI and postd suffixes are also valid, e.g. ani=1234567890 and/or postd=1234. Examples of valid numbers include: 6175551234, tel:+16175551234, tel:16175551234;ani=2125551234 (this determines the number the recipient sees), tel:16175551234;ani=2125551234;postd=2 (this determines the number the recipient sees and enters the dtmf tone “2” after the call connects).
start_timestampstringnoUnix timestamp for when to make the outbound call
end_timestampstringnoUnix timestamp for when to stop attempting to make the outbound call
max_attemptsint (between 1-10)noNumber of attempts to be made (if previous attempts are not completed successfully)
reattempt_waitintnoInterval (in seconds) to wait before retrying the outbound call after a failure. This is only required when you set an max_attempts value greater than one, indicating additional retry attempts.
metadatamixednoArray of key⇒value pairs of metadatabase columns and their associated values.
result_urlurlnoCallback URL to your REST service that processes the call status results when the call is completed, canceled, or all attempts have been exhausted. The POST body will match the format of the 'call_details' attribute from the outbound call status API response, shown here .

Possible Response Codes:

  • 200: success
  • 400: supplied data improperly formatted or invalid
  • 401: authentication headers invalid or the account is inactive
  • 403: the account attempting to queue the outbound call for the survey does not have appropriate permissions
  • 404: deployment, user or survey was not found
  • 405: invalid HTTP method supplied (only POST allowed)
  • 409: survey has been marked as deleted, survey deployment has expired, no TTS engine or metadatbase set for the survey, instance_id supplied did not match the current deployment, the number of survey responses has exceeded the max responses set in the survey's deployment settings
  • 415: unsupported media type (Content-Type value in request)
  • 500: database error

The return structure will contain the following item(s):

NameData TypeAlways PresentDescription
successbooleanyesIndicates the outcome of the request
errorstringnoIf the success value is false this provides a message indicating what error(s) occurred
call_idintnoThe unique identifier for the outbound call when the request is successful. This is the 'call id' value that can be used to look up the call details in the call details API method outlined below.

Note: The returned 'Link' header provides the URI for checking the status of the most recent outbound call.

Sample Code

This sample PHP code makes a request to queue a new outbound call. This triggers an outbound call that goes out immediately and makes a single attempt to connect:

<?php
$ch = curl_init();
$url = 'https://insight.plumvoice.com/api/surveys/{survey_id}/{instance_id}/queue';
$params = array(
	'phone_number'=>'desintation_phone_number',
	);
$username = 'you@yourdomain.com';
$password = 'your_developer_key';
curl_setopt($ch, CURLOPT_USERPWD, $username.":".$password);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Accept: application/json", "Content-type: application/x-www-form-urlencoded"));
$result = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($result);
var_dump($http_code);

Sample Responses

On success (Note the 'Link' header. This URI can be used to check the status of the outbound call):

JSON response:
HTTP Code 200
HTTP Headers:

HTTP/1.1 200 OK
Date: Wed, 06 May 2015 18:19:13 GMT
Server: Apache/2.2.29 (Unix) mod_ssl/2.2.29 OpenSSL/0.9.8e-fips-rhel5 PHP/5.4.40
X-Powered-By: PHP/5.4.40
Link: https://insight.plumvoice.com/api/outbound/155761
Content-Length: 33
Content-Type: application/json

Response Body:

{'success':true,'call_id':155761}

The same response with an Accept header of 'application/xml' in the request looks like:

XML response:
HTTP Code 200 Headers:

HTTP/1.1 200 OK
Date: Wed, 06 May 2015 18:24:41 GMT
Server: Apache/2.2.29 (Unix) mod_ssl/2.2.29 OpenSSL/0.9.8e-fips-rhel5 PHP/5.4.40
X-Powered-By: PHP/5.4.40
Link: https://insight.plumvoice.com/api/outbound/155761
Content-Length: 88
Content-Type: application/xml

Response Body:

<result>
  <success>true</success>
  <call_id>155761</call_id>
</result>

On Failure (too many attempts were supplied):

JSON Response:
HTTP Code 400

{'success':false,'error':'attempts can only be an integer between 1 and 10.'}

The same response with an Accept header of 'application/xml' in the request looks like:

XML Response:
HTTP Code 400

<result>
  <success>false</success>
  <error>attempts can only be an integer between 1 and 10.</error>
</result>

Queuing Multiple Outbound Calls

URL:

https://insight.plumvoice.com/api/surveys/{survey_id}/{instance_id}/bulk_queue

HTTP method: POST

Content-Type: multipart/form-data

Request Parameters:

NameData TypeRequiredDescription
csvfileyesCSV file of contacts to receive the outbound calls. For a description of how to format this file, see Bulk Queue Calls Formatting.
start_timestampstringnoUnix timestamp for when to make the outbound call
end_timestampstringnoUnix timestamp for when to stop attempting to make the outbound call
max_attemptsint (between 1-10)noNumber of attempts to be made(if previous attempts are not completed successfully)
reattempt_waitintnoInterval (in seconds) to wait before retrying the outbound call after a failure. This is only required when you set a max_attempts value greater than one, indicating additional retry attempts.
result_urlurlnoCallback URL to your REST service that processes the call status results when the call is completed, canceled, or all attempts have been exhausted. The callback will be sent the result for every queued outbound call that was queued successfully. The POST body will match the format of the 'call_details' attribute from the 'outbound call status' API response, shown here .

Possible Response Codes:

  • 200: success
  • 400: supplied data improperly formatted or invalid, uploaded CSV was invalid or not supplied
  • 401: authentication headers were invalid or the account is inactive
  • 403: the account attempting to queue the outbound call for the survey does not have appropriate permissions
  • 404: deployment, user or survey was not found
  • 405: invalid HTTP method supplied (only POST allowed)
  • 409: survey has been marked as deleted, survey deployment has expired, no TTS engine or metadatbase set for the survey, instance_id supplied did not match the current deployment, the number of survey responses has exceeded the max responses set in the survey's deployment settings
  • 415: unsupported media type (Content-Type value in request)
  • 500: database error

The return structure will contain the following item(s):

NameData TypeAlways PresentDescription
successbooleanyesIndicates the outcome of the request
errorstringnoIf the success value is false this provides a message indicating what error(s) occurred

Sample Code

This sample PHP code makes a request to queue multiple outbound calls:

<?php
$ch = curl_init();
$url = 'https://insight.plumvoice.com/api/surveys/{survey_id}/{instance_id}/bulk_queue';
$params = array(
	'csv'=>'@/path/to/csv/on/your/pc.csv',
	'start_timestamp'=>strtotime('+1 minutes'),
	'end_timestamp'=>strtotime('+1 hour'),
	'attempts'=>1
	);
$username = 'you@yourdomain.com';
$password = 'your_developer_key';
curl_setopt($ch, CURLOPT_USERPWD, $username.":".$password);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Accept: application/json", "Content-type: multipart/form-data"));
$result = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($result);
var_dump($http_code);

Sample Responses

On success:

JSON Response:
HTTP Code 200

{'success':true}

The same response with an Accept header of 'application/xml' in the request looks like:

XML Response:
HTTP Code 200

<result>
  <success>true</success>
</result>

On Failure (too many attempts were supplied):

JSON Response:
HTTP Code 400

{'success':false,'error':'attempts can only be an integer between 1 and 10.'}

The same response with an Accept header of 'application/xml' in the request looks like:

XML Response:
HTTP Code 400

<result>
  <success>false</success>
  <error>attempts can only be an integer between 1 and 10.</error>
</result>

Checking Status for an Outbound Call

URL:

https://insight.plumvoice.com/api/outbound/{call_id}

HTTP method: GET

Content-Type: application/x-www-form-urlencoded

Possible Response Codes:

  • 200: success
  • 401: authentication headers invalid or the account is inactive
  • 403: the account attempting to view the outbound call details does not have appropriate permissions
  • 404: outbound call was not found
  • 405: invalid HTTP method supplied (only GET allowed)
  • 415: unsupported media type (Content-Type value in request)
  • 500: database error

The return structure will contain the following item(s):

NameData TypeAlways PresentDescription
successbooleanyesIndicates the outcome of the request
errorstringnoIf the success value is false this provides a message indicating what error(s) occurred
call_detailsmixednoAll call data for the outbound call. See the table below for all of the data required therein.

Call Details Data:

NameData TypeValue
statusstringCurrent status for the outbound call.
attemptsintTotal number of attempts made
max_attemptsintMaximum number of attempts to be made
queued_timestampintUnix timestamp of when the call was queued
last_attempt_timestampintUnix timestamp of when the last event for the outbound call occurred
start_TimestampintUnix timestamp of when the call was scheduled to start outbound call attempts
end_timestampintUnix timestamp of when the outbound call was scheduled to stop outbound attempts
reattempt_waitintTime, in seconds, to wait between retrying the outbound call after a failure
eventsmixedNumerically indexed array of outbound call events, each row with the indices 'event' and 'timestamp' indicating the event and its duration

Sample Code

This sample PHP code makes a request to this method:

<?php
$ch = curl_init();
$url = 'https://insight.plumvoice.com/api/outbound/{call_id}';
$username = 'you@yourdomain.com';
$password = 'you_developer_key';
curl_setopt($ch, CURLOPT_USERPWD, $username.":".$password);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Accept: application/json", "Content-Type: application/x-www-form-urlencoded"));
$result = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($result);
var_dump($http_code);

Sample Response

On success (this outbound call was queued and then canceled):

JSON Response:
HTTP Code 200

{
  'success':true,
  'call_details': {
  'status':'canceled',
  'attempts':'1',
  'max_attempts':'1',
  'queued_timestamp':'1429214458',
  'last_attempt_timestamp':'1429214474',
  'start_timestamp':'1429214400',
  'end_timestamp':'1429218000',
  'reattempt_wait':'0',
  'events': [
    {
      'event':'queued',
      'timestamp':'1429214465'
    },
    {
       'event':'canceled',
       'timestamp':'1429214474'
    }
    ]
  }
}

The same response with an Accept header of 'application/xml' in the request looks like:

XML Response:
HTTP Code 200

<result>
  <success>true</success>
  <call_details>
    <status>canceled</status>
    <attempts>1</attempts>
    <max_attempts>1</max_attempts>
    <queued_timestamp>1429214458</queued_timestamp>
    <last_attempt_timestamp>1429214474</last_attempt_timestamp>
    <start_timestamp>1429214400</start_timestamp>
    <end_timestamp>1429218000</end_timestamp>
    <reattempt_wait>0</reattempt_wait>
    <events>
      <item><event>queued</event><timestamp>1429214465</timestamp></item>
      <item><event>canceled</event><timestamp>1429214474</timestamp></item>
    </events>
  </call_details>
</result>

On Failure (no outbound id was found):

JSON Response:
HTTP Code 404

{'success':false,'error':'An outbound call was not found by that id.'}

The same response with an Accept header of 'application/xml' in the request looks like:

XML Response:
HTTP Code 404

<result>
  <success>false</success>
  <error>An outbound call was not found by that id.</error>
</result>

Cancelling All Pending Outbound Calls

URL:

https://insight.plumvoice.com/api/surveys/{survey_id}/{instance_id}/cancel

HTTP method: DELETE

Content-Type: application/x-www-form-urlencoded

Possible Response Codes:

  • 202: calls successfully marked for deletion
  • 401: authentication headers invalid or the account is inactive
  • 403: the account attempting to cancel calls does not have appropriate permissions
  • 404: deployment was not found by the supplied survey and instance id
  • 405: invalid HTTP method supplied (only DELETE allowed)
  • 415: unsupported media type (Content-Type value in request)
  • 500: database error

The return structure will contain the following item(s):
Note: On a successful response (HTTP code 202), no body will be returned.

NameData TypeAlways PresentDescription
successbooleannoIndicates the outcome of the request. This will only be present when the response http code is something other than HTTP 202, indicating a failure.
errorstringnoIf the success value is false this provides a message indicating what error(s) occurred. This will only be present when the response http code is something other than HTTP 202, indicating a failure.

Sample Code

This sample PHP code that makes a request to this method:

<?php
$ch = curl_init();
$url = 'https://insight.plumvoice.com/api/surveys/{survey_id}/{instance_id}/cancel';
$username = 'you@yourdomain.com';
$password = 'your_developer_key';
curl_setopt($ch, CURLOPT_USERPWD, $username.":".$password);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Accept: application/json", "Content-Type: application/x-www-form-urlencoded"));
$result = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($result);
var_dump($http_code);

Sample Response

On success:

JSON/XML Response:
HTTP Code 202
No response body returned

On Failure (invalid deployment):

JSON Response:
HTTP Code 404

{'success':false,'error':'The specified deployment was not found for this survey.'}

The same response with an Accept header of 'application/xml' in the request looks like:

XML Response:
HTTP Code 404

<result>
  <success>false</success>
  <error>The specified deployment was not found for this survey.</error>.
</result>

Adding Metadatabase Records

URL:

https://insight.plumvoice.com/api/metadatabase_push

HTTP method: POST

Content-Type: application/x-www-form-urlencoded

Request Parameters:

NameData TypeRequiredDescription
metadatabasestringyesThe name of the metadatabase. This is case-insensitive.
recordstringyesjson encoded associative array of the column names and column values to be added. Example: {'column1': 'value1', 'column2': 'value2'} This need not include all columns, you can leave out columns in your metadatabase you do not wish to populate.

Possible Response Codes:

  • 200: success
  • 400: invalid data supplied
  • 401: authentication headers invalid or the account is inactive
  • 404: metadatabase was not found
  • 405: invalid HTTP method supplied (only POST allowed)
  • 415: unsupported media type (Content-Type value in request)
  • 500: database error

The return structure contains the following item(s):

NameData TypeAlways PresentDescription
successbooleanyesIndicates the outcome of the request
errorstringnoIf the success value is false this provides a message indicating what error(s) occurred

Sample Code

This sample PHP code makes a request to push a new record into the 'test' metadatabase and sets values for columns column1 and column2:

<?php

$params = array(
	'metadatabase' => 'test',
	'record' => json_encode(array('column1' => 'value1', 'column2' => 'value2')),
	);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://insight.plumvoice.com/api/metadatabase_push");
curl_setopt($ch, CURLOPT_USERPWD, 'your_login:your_dev_pin'); // http basic auth credentials
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/x-www-form-urlencoded', 'Accept: application/json'));
$result = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
var_dump($http_code, $result);

Sample Response

On success:

JSON response:
HTTP Code 200

{'success':true}

The same value with an Accept header of 'application/xml' set in the request would be:

XML response:
HTTP Code 200

<result>
  <success>true</success>
</result>

On Failure (In this example the metadatabase specified did not exist):

JSON response:
HTTP Code 404

{'success':false,'error':'No metadatabase by that name exists.'}

The same response with an Accept header of 'application/xml' set in the request would be:

XML response:
HTTP Code 404

<result>
  <success>false</success
  <error>No metadatabase by that name exists.</error>
</result>

Survey Response Reporting

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.

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.

URL:

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

HTTP method: GET

Content-Type: application/x-www-form-urlencoded

Request Parameters:

NameData TypeRequiredDepends OnDescription
report_idintyesN/AThe report_id for your saved report.
start_timestampintnoend_timestampUnix timestamp to filter your survey responses to a specific date range.
end_timestampintnostart_timestampUnix timestamp to filter your survey responses to a specific date range.
offsetintnoN/AOffset 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.
limitintnoN/ALimit the number of rows returned. The limit must be between 1 and 10,000. If no limit is supplied, the limit will be 500.

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 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 NameTypeDescription
X-Plum-Total-RowsintThis value indicates the total number of rows that matched the query.
X-Plum-Returned-RowsintThis value indicates the total number of rows returned in the response.
X-Plum-Row-OffsetintThis value indicates the offset applied to the current response.
X-Plum-Row-LimitintThis 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.

Response:
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):

NameData TypeAlways PresentDescription
errorstringyesDescriptive 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;
}

Sample Response

Here's the output of running the above script with proper credentials:

On success:

Along with having the new report created in csv format at 'reports/todays_report.csv', the following would be output:

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

Note the headers returned. These values indicate the following:

  • our request implicitly started at offset 0 (we did not specify an offset, so the default was applied)
  • the limit of 10 was applied, as supplied in the query string parameters
  • we received 10 rows in our response body
  • there were 12 total rows available for the report

On Failure (the report_id supplied was not valid):

JSON response:

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

The same response with an Accept header of 'application/xml' set in the request would be:

XML response:

<?xml version="1.0"?>
<result>
  <error>You do not have permission to access this report</error>
</result>
api.txt · Last modified: 2018/05/02 15:48 by admin