Geographic

get
Caller Profile Data

https://voicetrends.plumvoice.com/api/profile/{start}/{end}/{phone}
This service fetches any of the available data in the Caller Profile/Geographic page 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.
Request
Response
Request
Path Parameters
start
required
integer
The start date (inclusive) for this request in YYYYMMDD format.
end
required
integer
The end date (inclusive) for this request in YYYYMMDD format.
phone
required
string
The single phone number for this report or “ALL” to merge data across all numbers.
Response
200: OK
JSON
XML
JSON
HTTP/1.1 200 OK
X-RateLimit-Limit: 150
X-RateLimit-Remaining: 146
X-RateLimit-Reset: 1519671600
Content-Length: 394
Content-Type: application/json
{
"US":{
"AL":0,
"AK":0,
"AZ":0,
"AR":0,
"CA":0,
"CO":0,
"CT":0,
"DC":0,
"DE":0,
"FL":0,
"GA":0,
"HI":0,
"ID":0,
"IL":0,
"IN":0,
"IA":0,
"KS":0,
"KY":0,
"LA":0,
"ME":0,
"MD":0,
"MA":0,
"MI":0,
"MN":0,
"MS":0,
"MO":0,
"MT":0,
"NE":0,
"NV":0,
"NH":0,
"NJ":0,
"NM":0,
"NY":0,
"NC":0,
"ND":0,
"OH":0,
"OK":0,
"OR":0,
"PA":0,
"RI":0,
"SC":0,
"SD":0,
"TN":0,
"TX":0,
"UT":0,
"VT":0,
"VA":0,
"WA":0,
"WV":0,
"WI":0,
"WY":0,
"US Toll-Free":1
},
"NON_US":[]
}
XML
< HTTP/1.1 200 OK
< Date: Mon, 26 Feb 2018 18:54:45 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
< X-RateLimit-Limit: 150
< X-RateLimit-Remaining: 145
< X-RateLimit-Reset: 1519671600
< Content-Length: 2772
< Content-Type: application/xml
<
<?xml version="1.0"?>
<result>
<US>
<item><location>AL</location><count>0</count></item>
<item><location>AK</location><count>0</count></item>
<item><location>AZ</location><count>0</count></item>
<item><location>AR</location><count>0</count></item>
<item><location>CA</location><count>0</count></item>
<item><location>CO</location><count>0</count></item>
<item><location>CT</location><count>0</count></item>
<item><location>DC</location><count>0</count></item>
<item><location>DE</location><count>0</count></item>
<item><location>FL</location><count>0</count></item>
<item><location>GA</location><count>0</count></item>
<item><location>HI</location><count>0</count></item>
<item><location>ID</location><count>0</count></item>
<item><location>IL</location><count>0</count></item>
<item><location>IN</location><count>0</count></item>
<item><location>IA</location><count>0</count></item>
<item><location>KS</location><count>0</count></item>
<item><location>KY</location><count>0</count></item>
<item><location>LA</location><count>0</count></item>
<item><location>ME</location><count>0</count></item>
<item><location>MD</location><count>0</count></item>
<item><location>MA</location><count>0</count></item>
<item><location>MI</location><count>0</count></item>
<item><location>MN</location><count>0</count></item>
<item><location>MS</location><count>0</count></item>
<item><location>MO</location><count>0</count></item>
<item><location>MT</location><count>0</count></item>
<item><location>NE</location><count>0</count></item>
<item><location>NV</location><count>0</count></item>
<item><location>NH</location><count>0</count></item>
<item><location>NJ</location><count>0</count></item>
<item><location>NM</location><count>0</count></item>
<item><location>NY</location><count>0</count></item>
<item><location>NC</location><count>0</count></item>
<item><location>ND</location><count>0</count></item>
<item><location>OH</location><count>0</count></item>
<item><location>OK</location><count>0</count></item>
<item><location>OR</location><count>0</count></item>
<item><location>PA</location><count>0</count></item>
<item><location>RI</location><count>0</count></item>
<item><location>SC</location><count>0</count></item>
<item><location>SD</location><count>0</count></item>
<item><location>TN</location><count>0</count></item>
<item><location>TX</location><count>0</count></item>
<item><location>UT</location><count>0</count></item>
<item><location>VT</location><count>0</count></item>
<item><location>VA</location><count>0</count></item>
<item><location>WA</location><count>0</count></item>
<item><location>WV</location><count>0</count></item>
<item><location>WI</location><count>0</count></item>
<item><location>WY</location><count>0</count></item>
<item><location>US Toll-Free</location><count>1</count>
</item>
</US>
<NON_US/>
</result>
400: Bad Request
JSON
XML
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.

US

array

no

A 200 HTTP code returns this value, the list of US locations and their associated call count.

NON_US

array

no

A 200 HTTP code returns this value, the list of non-US locations and their associated call count.

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>';
$phone = '<selected_phone_number>';
// build the URL
$url = 'https://voicetrends.plumvoice.com/api/performance/'.$start.'/'.$end.'/'.$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);