Call Volume

- NEW! - Interactive API docs, now live!

Visit api-docs.plumvoice.com to read Plum API documentation, build and test requests in our interactive API sandbox, review the responses, and share it all with your team.

Get Call Volume Data

GET https://voicetrends.plumvoice.com/api/volume/{start}/{end}/{period}/{phone}

This service fetches any of the available data in the Call Volume section in VoiceTrends. To use this service, provide your temporary authentication credentials and several GET parameters, which function as filters for this data. This API is rate-limited in a group with all other raw data resources to 150 requests per 15-minute window.

Path Parameters

Name	Type	Description
start	integer	The start date (inclusive) for this request in YYYYMMDD format.
end	integer	The end date (inclusive) for this request in YYYYMMDD format.
period	string	The period that the data will be grouped into (day, week, month).
phone	string	The single phone number for this report or “ALL” to merge data across all numbers.

200

JSON

HTTP/1.1 200 OK
X-RateLimit-Limit: 150
X-RateLimit-Remaining: 149
X-RateLimit-Reset: 1519659000
Content-Length: 690
Content-Type: application/json

{
  "calls":{"1517461200":0,"1517547600":0,"1517634000":0,"1517720400":0,"1517806800":0,"1517893200":0,"1517979600":1,"1518066000":0},
  "call_minutes":{"1517461200":0,"1517547600":0,"1517634000":0,"1517720400":0,"1517806800":0,"1517893200":0,"1517979600":2.1,"1518066000":0},
  "transfers":{"1517461200":0,"1517547600":0,"1517634000":0,"1517720400":0,"1517806800":0,"1517893200":0,"1517979600":1,"1518066000":0},
  "transfer_rate":{"1517461200":0,"1517547600":0,"1517634000":0,"1517720400":0,"1517806800":0,"1517893200":0,"1517979600":100,"1518066000":0},
  "average_call_length":{"1517461200":0,"1517547600":0,"1517634000":0,"1517720400":0,"1517806800":0,"1517893200":0,"1517979600":126,"1518066000":0}
}

XML

HTTP/1.1 200 OK
X-RateLimit-Limit: 150
X-RateLimit-Remaining: 148
X-RateLimit-Reset: 1519659000
Content-Length: 1667
Content-Type: application/xml

<?xml version="1.0"?>
<result>
  <calls>
    <item timestamp="1517461200">0</item>
    <item timestamp="1517547600">0</item>
    <item timestamp="1517634000">0</item>
    <item timestamp="1517720400">0</item>
    <item timestamp="1517806800">0</item>
    <item timestamp="1517893200">0</item>
    <item timestamp="1517979600">1</item>
    <item timestamp="1518066000">0</item>
  </calls>
  <call_minutes>
    <item timestamp="1517461200">0</item>
    <item timestamp="1517547600">0</item>
    <item timestamp="1517634000">0</item>
    <item timestamp="1517720400">0</item>
    <item timestamp="1517806800">0</item>
    <item timestamp="1517893200">0</item>
    <item timestamp="1517979600">2.1</item>
    <item timestamp="1518066000">0</item>
  </call_minutes>
  <transfers>
    <item timestamp="1517461200">0</item>
    <item timestamp="1517547600">0</item>
    <item timestamp="1517634000">0</item>
    <item timestamp="1517720400">0</item>
    <item timestamp="1517806800">0</item>
    <item timestamp="1517893200">0</item>
    <item timestamp="1517979600">1</item>
    <item timestamp="1518066000">0</item>
  </transfers>
  <transfer_rate>
    <item timestamp="1517461200">0</item>
    <item timestamp="1517547600">0</item>
    <item timestamp="1517634000">0</item>
    <item timestamp="1517720400">0</item>
    <item timestamp="1517806800">0</item>
    <item timestamp="1517893200">0</item>
    <item timestamp="1517979600">100</item>
    <item timestamp="1518066000">0</item>
  </transfer_rate>
  <average_call_length>
    <item timestamp="1517461200">0</item>
    <item timestamp="1517547600">0</item>
    <item timestamp="1517634000">0</item>
    <item timestamp="1517720400">0</item>
    <item timestamp="1517806800">0</item>
    <item timestamp="1517893200">0</item>
    <item timestamp="1517979600">126</item>
    <item timestamp="1518066000">0</item>
  </average_call_length>
</result>

400

JSON

HTTP/1.1 400 Bad Request
X-RateLimit-Limit: 150
X-RateLimit-Remaining: 149
X-RateLimit-Reset: 1519659000
Content-Length: 90
Content-Type: application/json

{"error":"Invalid start parameter."}

XML

HTTP/1.1 400 Bad Request
X-RateLimit-Limit: 150
X-RateLimit-Remaining: 149
X-RateLimit-Reset: 1519659000
Content-Length: 120
Content-Type: application/json

<?xml version="1.0"?>
<result>
  <error>Invalid start parameter.</error>
</result>

Possible Response Codes

• 200: success, data successfully returned.

• 400: supplied data improperly formatted or invalid

• 401: authentication parameters invalid or the account is inactive

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

• 429: rate limit exceeded

• 500: unknown error

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

Name	Data Type	Always Present	Description
error	string	no	Indicates what went wrong when an HTTP code other than 200 is returned.
calls	array	no	A 200 HTTP code returns this value, the list of call counts grouped by period timestamp.
call_minutes	array	no	A 200 HTTP code returns this value, the list of call minutes grouped by period timestamp.
transfers	array	no	A 200 HTTP code returns this value, the list of transfer counts grouped by period timestamp.
transfer_minutes	array	no	A 200 HTTP code returns this value, the list of transfer minutes grouped by period timestamp.
transfer_rate	array	no	A 200 HTTP code returns this value, the list of transfer rate percentages grouped by period timestamp.
average_call_length	array	no	A 200 HTTP code returns this value, the list of average call lengths in seconds grouped by period timestamp.

Sample Code

This sample code makes a request to authenticate an account using PHP, but any language capable of integrating with a REST API works for this type of request:

<?php
// authentication and filter settings
$login = '<your_temporary_login>';
$password = '<your_temporary_password>';
$start = '<start_date>';
$end = '<end_date>';
$period = '<selected_period>';
$phone = '<selected_phone_number>';

// build the URL
$url = 'https://voicetrends.plumvoice.com/api/volume/'.$start.'/'.$end.'/'.$period.'/'.$phone;

$ch = curl_init();
curl_setopt($ch, CURLOPT_USERPWD, $login.':'.$password);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Accept: application/json"));
$result = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($result);
var_dump($http_code);