> For the complete documentation index, see [llms.txt](https://docs.plumvoice.com/dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.plumvoice.com/dev/plum-dev-apis/call-logs.md).

# Call Logs API

{% hint style="success" %}
**- NEW! - Interactive API docs, now live!**

Visit [api-docs.plumvoice.com](https://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.
{% endhint %}

{% hint style="warning" %}
**IMPORTANT: Logging is not available on demo accounts.**

Demo accounts provide only limited access to DEV's product features. You'll need a standard account for full access to logging and more. 

**Using a demo account?** [Contact us](https://www.plumvoice.com/contact-us/) if interested in upgrading to a standard account.
{% endhint %}

## Overview

Plum offers four services for its Call Log REST API:

| Method                                                  | Service                                                        | Description                                                                                                      |
| ------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| [GET](/dev/plum-dev-apis/call-logs.md#recent-call-logs) | [calls/logs](/dev/plum-dev-apis/call-logs.md#recent-call-logs) | [Returns a filtered list of recent calls for which logs exist](/dev/plum-dev-apis/call-logs.md#recent-call-logs) |
| [GET](/dev/plum-dev-apis/call-logs.md#call-log)         | [calls/log](/dev/plum-dev-apis/call-logs.md#call-log)          | [Returns a single call log](/dev/plum-dev-apis/call-logs.md#call-log)                                            |
| [GET](/dev/plum-dev-apis/call-logs.md#session-logs)     | [calls/sessions](/dev/plum-dev-apis/call-logs.md#session-logs) | [Returns a filtered list of session logs](/dev/plum-dev-apis/call-logs.md#session-logs)                          |
| [GET](/dev/plum-dev-apis/call-logs.md#error-logs)       | [calls/errors](/dev/plum-dev-apis/call-logs.md#error-logs)     | [Returns a filtered list of error logs](/dev/plum-dev-apis/call-logs.md#error-logs)                              |

{% hint style="warning" %}
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.
{% endhint %}

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.

### **Sample Responses**

{% tabs %}
{% tab title="JSON (success)" %}

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

{% endtab %}

{% tab title="JSON (failure)" %}

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

{% endtab %}

{% tab title="XML (success)" %}

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

{% endtab %}

{% tab title="XML (failure)" %}

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

{% endtab %}
{% endtabs %}

## Recent Call Logs

<mark style="color:blue;">`GET`</mark> `https://hosting.vxml.sharpencx.com/ws/calls/logs/{start_timestamp}/{end_timstamp}`

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

#### Path Parameters

| Name             | Type    | Description                                                                                                                                                                |
| ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| start\_timestamp | integer | <p>UNIX timestamp filters the list of call logs for all calls starting on or after this timestamp<br><em>Note: The start\_timestamp must be within the last year.</em></p> |
| end\_timestamp   | integer | <p>UNIX timestamp filters the list of call logs for all calls starting before this timestamp<br><em>Note: The end\_timestamp must be after the start\_timestamp.</em></p>  |

#### Query Parameters

| Name   | Type    | Description                                                                                         |
| ------ | ------- | --------------------------------------------------------------------------------------------------- |
| number | string  | Filters the list of call logs for only calls to this phone number.                                  |
| offset | integer | <p>Number of call logs to skip before returning results.<br><em>Default: 0</em></p>                 |
| limit  | integer | <p>Maximum number of call logs to return.<br><em>Default: 1000, Minimum: 1, Maximum: 10000</em></p> |

#### Headers

| Name         | Type   | Description                                 |
| ------------ | ------ | ------------------------------------------- |
| content-type | string | application/x-www-form-urlencoded           |
| accept       | string | application/json (default), application/xml |

{% tabs %}
{% tab title="200 " %}
{% tabs %}
{% tab title="JSON" %}

```javascript
{
  "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"
      }
    ]
  }
}
```

{% endtab %}

{% tab title="XML" %}

```markup
<?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>
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

**Sample Code**

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

{% tabs %}
{% tab title="getlogs.php" %}

```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?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);
?>
```

{% endtab %}

{% tab title="CURL (command line)" %}

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

{% endtab %}
{% endtabs %}

## Call Log

<mark style="color:blue;">`GET`</mark> `https://hosting.vxml.sharpencx.com/ws/calls/log/{log_id}`

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.&#x20;

#### Path Parameters

| Name    | Type    | Description                                                                                                        |
| ------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
| log\_id | integer | The ID of the log we are fetching. The log\_id value is provided in the response from the calls?logs REST service. |

#### Headers

| Name         | Type   | Description                                 |
| ------------ | ------ | ------------------------------------------- |
| content-type | string | application/x-www-form-urlencoded           |
| accept       | string | application/json (default), application/xml |

{% tabs %}
{% tab title="200 " %}
{% tabs %}
{% tab title="JSON" %}

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

```

{% endtab %}

{% tab title="XML" %}

```markup
<?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>
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

**Sample Code**

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

{% tabs %}
{% tab title="getlog.php" %}

```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);
?>
```

{% endtab %}

{% tab title="CURL (command line)" %}

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

{% endtab %}
{% endtabs %}

## Session Logs

<mark style="color:blue;">`GET`</mark> `https://hosting.vxml.sharpencx.com/ws/calls/sessions/{start_timestamp}/{end_timstamp}`

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

#### Path Parameters

| Name             | Type    | Description                                                                                                                                                                |
| ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| start\_timestamp | integer | <p>UNIX timestamp filters the list of call logs for all calls starting on or after this timestamp<br><em>Note: The start\_timestamp must be within the last year.</em></p> |
| end\_timestamp   | integer | <p>UNIX timestamp filters the list of call logs for all calls starting before this timestamp<br><em>Note: The end\_timestamp must be after the start\_timestamp.</em></p>  |

#### Query Parameters

| Name   | Type    | Description                                                                                         |
| ------ | ------- | --------------------------------------------------------------------------------------------------- |
| number | string  | Filters the list of call logs for only calls to this phone number.                                  |
| offset | integer | <p>Number of call logs to skip before returning results.<br><em>Default: 0</em></p>                 |
| limit  | integer | <p>Maximum number of call logs to return.<br><em>Default: 1000, Minimum: 1, Maximum: 10000</em></p> |

#### Headers

| Name         | Type   | Description                                 |
| ------------ | ------ | ------------------------------------------- |
| content-type | string | application/x-www-form-urlencoded           |
| accept       | string | application/json (default), application/xml |

{% tabs %}
{% tab title="200 " %}
{% tabs %}
{% tab title="JSON" %}

```javascript
{
  "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"
    ]
  }
}
```

{% endtab %}

{% tab title="XML" %}

```markup
<?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>
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

**Sample Code**

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.

{% tabs %}
{% tab title="getlogs.php" %}

```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?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);
?>
```

{% endtab %}

{% tab title="CURL (command line)" %}

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

{% endtab %}
{% endtabs %}

## Error Logs

<mark style="color:blue;">`GET`</mark> `https://hosting.vxml.sharpencx.com/ws/calls/errors/{start_timestamp}/{end_timstamp}`

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

#### Path Parameters

| Name             | Type    | Description                                                                                                                                                                |
| ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| start\_timestamp | integer | <p>UNIX timestamp filters the list of call logs for all calls starting on or after this timestamp<br><em>Note: The start\_timestamp must be within the last year.</em></p> |
| end\_timestamp   | integer | <p>UNIX timestamp filters the list of call logs for all calls starting before this timestamp<br><em>Note: The end\_timestamp must be after the start\_timestamp.</em></p>  |

#### Query Parameters

| Name   | Type    | Description                                                                                         |
| ------ | ------- | --------------------------------------------------------------------------------------------------- |
| number | string  | Filters the list of call logs for only calls to this phone number.                                  |
| offset | integer | <p>Number of call logs to skip before returning results.<br><em>Default: 0</em></p>                 |
| limit  | integer | <p>Maximum number of call logs to return.<br><em>Default: 1000, Minimum: 1, Maximum: 10000</em></p> |

#### Headers

| Name         | Type   | Description                                 |
| ------------ | ------ | ------------------------------------------- |
| content-type | string | application/x-www-form-urlencoded           |
| accept       | string | application/json (default), application/xml |

{% tabs %}
{% tab title="200 " %}
{% tabs %}
{% tab title="JSON" %}

```javascript
{
  "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"
    ]
  }
}
```

{% endtab %}

{% tab title="XML" %}

```markup
<?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>
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

**Sample Code**

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

{% tabs %}
{% tab title="getlogs.php" %}

```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?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);
?>
```

{% endtab %}

{% tab title="CURL (command line)" %}

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

{% endtab %}
{% endtabs %}