# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.plumvoice.com/dev/plum-dev-apis/call-logs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.