Plum DEV Documentation
You are here: start » plumdevguide » calllogs

Sidebar

Developer Reference

VoiceXML

Plum DEV Guide

Plum DEV APIs

plumdevguide:calllogs

Table of Contents

Call Logs Guide


Call Logs API Description

Plum offers four services for its Call Log REST API:

Method Service Description
GET calls/logs Returns a filtered list of recent calls for which logs exist
GET calls/log Returns a single call log
GET calls/sessions Returns a filtered list of session logs
GET calls/errors Returns a filtered list of error logs

Please note that each of these Call Log REST APIs use HTTP AUTH for authentication. The username/password to be used for authentication are the same as your standard Plum DEV login credentials.

All of the Call Log REST APIs have the same return format that includes a status (success or failure), error message and the result data.

Example Responses:

JSON (success): 

{
  "status":"success",
  "error":"",
  "result": {
    // SAMPLE RESULT DATA
  }
}

XML (success): 

<sample>
  <status>success</status>
  <error/>
  <result>
    <!-- SAMPLE RESULT DATA -->
  </result>
</sample>

JSON (failure): 

{
  "status":"failure",
  "error":"Unauthorized access to sample service",
}

XML (failure): 

<sample>
  <status>failure</status>
  <error>Unauthorized access to sample service</error>
</sample>


Call Logs REST API (GET calls/logs)

Returns a filtered list of recent calls for which logs exist. Call logs are only retained for the previous 5 days.

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

Response Formats: JSON, XML

Requires HTTP Basic Authentication? Yes

Resource URL: https://hosting.plumvoice.com/ws/calls/logs/{start_timestamp}/{end_timstamp}

Supported Accept Headers: application/json (default), application/xml

Required URL Parameters:

Parameter Type Description
start_timestamp integer UNIX timestamp filters the list of call logs for all calls starting on or after this timestamp
Note: The start_timestamp must be within the last 5 days.
end_timestamp integer UNIX timestamp filters the list of call logs for all calls starting before this timestamp
Note: The end_timestamp must be after the start_timestamp.

Optional GET Parameters:

Parameter Type Description
number string Filters the list of call logs for only calls to this phone number.
offset integer Number of call logs to skip before returning results.
Default: 0
limit integer Maximum number of call logs to return
Default: 1000, Minimum: 1, Maximum: 10000

Example Responses:

JSON: 

{
  "status":"success",
  "error":"",
  "result":{
    "total_logs":"1234",
    "logs":[
      {
        "log_id":"421752831",
        "session_id":"400050;000;1510159646",
        "dest":"6177123000",
        "type":"inbound",
        "src":"2125551234",
        "start":"1510159657",
        "end":"1510159689"
      },
      {
        "log_id":"421627729",
        "session_id":"300025;000;1510142108",
        "dest":"6177123000",
        "type":"inbound",
        "src":"7185551234",
        "start":"1510142148",
        "end":"1510142215"
      }
    ]
  }
}

XML: 

<?xml version="1.0"?>
<logs>
  <status>success</status>
  <error></error>
  <result>
    <total_logs>1234</total_logs>
    <logs>
      <log>
        <log_id>421752831</log_id>
        <session_id>400050;000;1510159646</session_id>
        <dest>6177123000</dest>
        <type>inbound</type>
        <src>2125551234</src>
        <start>1510159657</start>
        <end>1510159689</end>
      </log>
      <log>
        <log_id>421627729</log_id>
        <session_id>300025;000;1510142108</session_id>
        <dest>6177123000</dest>
        <type>inbound</type>
        <src>7185551234</src>
        <start>1510142148</start>
        <end>1510142215</end>
      </log>
    </logs>
  </result>
</logs>

Code Example:
The following code sample is written in PHP but any language that can connecting to a JSON or XML REST service can utilize this API.

getlogs.php 

<?php
header("Content-type: text/xml");

// initialize curl
$ch = curl_init();

// set necessary curl options
curl_setopt($ch, CURLOPT_URL, "https://hosting.plumvoice.com/ws/calls/logs/1509681600/1510203600?phone_number=6177123000&offset=0&limit=2");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Accept: application/xml'));
curl_setopt($ch, CURLOPT_USERPWD, "username:password");

echo(curl_exec($ch));

curl_close($ch);
?>

CURL Example from the command line: 

curl -u username:password -H"Accept: application/xml" "https://hosting.plumvoice.com/ws/calls/logs/1509681600/1510203600?phone_number=6177123000&offset=0&limit=2"


Call Log REST API (GET calls/log)

Returns a recent call log using a log_id returned in the calls/logs response. To fetch all logs for your account you should call calls/logs to get the list of calls then loop through those results calling calls/log/{log_id} to fetch each individual call log.

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

Response Formats: JSON, XML

Requires HTTP Basic Authentication? Yes

Resource URL: https://hosting.plumvoice.com/ws/calls/log/{log_id}

Supported Accept Headers: application/json (default), application/xml

Required URL Parameters:

Parameter Type Description
log_id integer The ID of the log we are fetching. The log_id value is provided in the response from teh calls?logs REST service.

Example Responses:

JSON: 

{
  "status":"success",
  "error":"",
  "result":{
    "dest":"6177123000",
    "src":"2125551234",
    "type":"inbound",
    "timestamp":"1510142148",
    "location":"Boston",
    "log":"...log data string..."
  }
}

XML: 

<?xml version="1.0"?>
<log>
  <status>success</status>
  <error></error>
  <result>
    <dest>6177123000</dest>
    <src>2125551234</src>
    <type>inbound</type>
    <timestamp>1510142148</timestamp>
    <location>Boston</location>
    <log>...log data string...</log>
  </result>
</log>

Code Example:
The following code sample is written in PHP but any language that can connecting to a JSON or XML REST service can utilize this API.

getlog.php 

<?php
header("Content-type: text/xml");

// initialize curl
$ch = curl_init();

// set necessary curl options
curl_setopt($ch, CURLOPT_URL, "https://hosting.plumvoice.com/ws/calls/log/421627729");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Accept: application/xml'));
curl_setopt($ch, CURLOPT_USERPWD, "username:password");

echo(curl_exec($ch));

curl_close($ch);
?>

CURL Example from the command line: 

curl -u username:password -H"Accept: application/xml" "https://hosting.plumvoice.com/ws/calls/log/421627729"


Session Logs REST API (GET calls/sessions)

Returns a filtered list of session logs. Unlike call logs, session logs are stored for up to 1 year.

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

Response Formats: JSON, XML

Requires HTTP Basic Authentication? Yes

Resource URL: https://hosting.plumvoice.com/ws/calls/sessions/{start_timestamp}/{end_timstamp}

Supported Accept Headers: application/json (default), application/xml

Required URL Parameters:

Parameter Type Description
start_timestamp integer UNIX timestamp filters the list of session logs for all calls starting on or after this timestamp
end_timestamp integer UNIX timestamp filters the list of session logs for all calls starting before this timestamp
Note: The end_timestamp must be after the start_timestamp.

Optional GET Parameters:

Parameter Type Description
number string Filters the list of session logs for only sessions on this phone number.
offset integer Number of call logs to skip before returning results.
Default: 0
limit integer Maximum number of call logs to return
Default: 1000, Minimum: 1, Maximum: 10000

Example Responses:

JSON: 

{
  "status":"success",
  "error":"",
  "result":{
    "total_sessions":"8",
    "sessions":[
      "outbound 12125551234 26 [03\/Nov\/2017:00:10:42 -0500] test@login.com 300024;026;1509673023 1509682242 1509682255 00:00:13",
      "inbound 7185551234 3 [03\/Nov\/2017:14:38:30 -0500] 6177123000 200035;003;1509734279 1509734310 1509734339 00:00:29",
      "inbound 6175551234 1 [03\/Nov\/2017:18:11:07 -0500] 8009957586 400050;001;1509747051 1509747067 1509747180 00:01:53"
    ]
  }
}

XML: 

<?xml version="1.0"?>
<sessions>
  <status>success</status>
  <error></error>
  <result>
    <total_sessions>8</total_sessions>
    <sessions>
      <session>outbound 12125551234 26 [03\/Nov\/2017:00:10:42 -0500] test@login.com 300024;026;1509673023 1509682242 1509682255 00:00:13</session>
      <session>inbound 7185551234 3 [03\/Nov\/2017:14:38:30 -0500] 6177123000 200035;003;1509734279 1509734310 1509734339 00:00:29</session>
      <session>inbound 6175551234 1 [03\/Nov\/2017:18:11:07 -0500] 8009957586 400050;001;1509747051 1509747067 1509747180 00:01:53</session>
    </sessions>
  </result>
</sessions>

Code Example:
The following code sample is written in PHP but any language that can connecting to a JSON or XML REST service can utilize this API.

getlogs.php 

<?php
header("Content-type: text/xml");

// initialize curl
$ch = curl_init();

// set necessary curl options
curl_setopt($ch, CURLOPT_URL, "https://hosting.plumvoice.com/ws/calls/sessions/1509681600/1510203600?phone_number=6177123000&offset=0&limit=2");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Accept: application/xml'));
curl_setopt($ch, CURLOPT_USERPWD, "username:password");

echo(curl_exec($ch));

curl_close($ch);
?>

CURL Example from the command line: 

curl -u username:password -H"Accept: application/xml" "https://hosting.plumvoice.com/ws/calls/sessions/1509681600/1510203600?phone_number=6177123000&offset=0&limit=2"


Error Logs REST API (GET calls/errors)

Returns a filtered list of error logs. Error logs are stored for up to 1 year.

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

Response Formats: JSON, XML

Requires HTTP Basic Authentication? Yes

Resource URL: https://hosting.plumvoice.com/ws/calls/errors/{start_timestamp}/{end_timstamp}

Supported Accept Headers: application/json (default), application/xml

Required URL Parameters:

Parameter Type Description
start_timestamp integer UNIX timestamp filters the list of error logs for all calls starting on or after this timestamp
end_timestamp integer UNIX timestamp filters the list of error logs for all calls starting before this timestamp
Note: The end_timestamp must be after the start_timestamp.

Optional GET Parameters:

Parameter Type Description
number string Filters the list of error logs for only errors on this phone number.
offset integer Number of call logs to skip before returning results.
Default: 0
limit integer Maximum number of call logs to return
Default: 1000, Minimum: 1, Maximum: 10000

Example Responses:

JSON: 

{
  "status":"success",
  "error":"",
  "result":{
    "total_errors":"3",
    "errors":[
      "error 2125551234 6 [17\/Nov\/2016:14:40:46 -0400] 6177123000 100025;006;1479411625 Max Disconnect Count Exceeded",
      "error 7185551234 1 [20\/Nov\/2016:21:28:46 -0400] 8009957586 100037;001;1479692314 errno: 210 message Maximum loop count exceeded",
      "error 6175551234 0 [09\/Jan\/2017:08:33:31 -0400] 8009957586 000020;000;1483968637 ReferenceError: d is not defined line 1"
    ]
  }
}

XML: 

<?xml version="1.0"?>
<errors>
  <status>success</status>
  <error></error>
  <result>
    <total_errors>3</total_errors>
    <errors>
      <error>error 2125551234 6 [17\/Nov\/2016:14:40:46 -0400] 6177123000 100025;006;1479411625 Max Disconnect Count Exceeded</error>
      <error>error 7185551234 1 [20\/Nov\/2016:21:28:46 -0400] 8009957586 100037;001;1479692314 errno: 210 message Maximum loop count exceeded</error>
      <error>error 6175551234 0 [09\/Jan\/2017:08:33:31 -0400] 8009957586 000020;000;1483968637 ReferenceError: d is not defined line 1</error>
    </errors>
  </result>
</errors>

Code Example:
The following code sample is written in PHP but any language that can connecting to a JSON or XML REST service can utilize this API.

getlogs.php 

<?php
header("Content-type: text/xml");

// initialize curl
$ch = curl_init();

// set necessary curl options
curl_setopt($ch, CURLOPT_URL, "https://hosting.plumvoice.com/ws/calls/errors/1509681600/1510203600?phone_number=6177123000&offset=0&limit=2");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Accept: application/xml'));
curl_setopt($ch, CURLOPT_USERPWD, "username:password");

echo(curl_exec($ch));

curl_close($ch);
?>

CURL Example from the command line: 

curl -u username:password -H"Accept: application/xml" "https://hosting.plumvoice.com/ws/calls/errors/1509681600/1510203600?phone_number=6177123000&offset=0&limit=2"
© 2019 The Plum Group, Inc. All Rights Reserved.