# List Incoming Calls

`GET /api/incoming-calls`

Inbound IVR calls to your numbers on a single calendar day, each with the legs it was forwarded to (agent number, status, duration, recording). This is the API version of the dashboard's **Incoming Calls** page. Re-fetch the same `date` to pick up end times, durations, and recordings after hangup. Poll **today** and **yesterday** for a few hours after midnight; older days do not change.

Requires a Bearer API token (from [Authentication](/api-docs/authentication) / dashboard **API Tokens**) and the **access-incoming-call** permission. Accounts without it get `403` — contact support to enable it.

Rate limit: 60 requests per hour per account. Page size is fixed at 100.

## Query Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| date | string | Yes | Calendar day `YYYY-MM-DD` in `Asia/Dhaka`. The day is call **start** (`created_at`), not hangup time. |
| page | number | No | Page number (default 1). Size is always 100. |

## Request Example

```bash
curl -X GET "https://api.awajdigital.com/api/incoming-calls?date=2026-09-07&page=1" \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Accept: application/json"
```

```javascript
// Browser JavaScript (Fetch API)
const date = '2026-09-07';
const response = await fetch(
  `https://api.awajdigital.com/api/incoming-calls?date=${date}&page=1`,
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer your_api_token_here',
      'Accept': 'application/json'
    }
  }
);

const data = await response.json();
console.log(data);
```

```javascript
// Node.js with axios
const axios = require('axios');

async function listIncomingCalls(date, page = 1) {
  try {
    const response = await axios.get('https://api.awajdigital.com/api/incoming-calls', {
      params: { date, page },
      headers: {
        'Authorization': 'Bearer your_api_token_here',
        'Accept': 'application/json'
      }
    });

    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

listIncomingCalls('2026-09-07');
```

```python
# Python with requests
import requests

def list_incoming_calls(date, page=1):
    url = 'https://api.awajdigital.com/api/incoming-calls'
    headers = {
        'Authorization': 'Bearer your_api_token_here',
        'Accept': 'application/json'
    }
    params = {
        'date': date,
        'page': page
    }

    try:
        response = requests.get(url, headers=headers, params=params)
        print(response.json())
    except requests.exceptions.RequestException as e:
        print(f'Error: {e}')

list_incoming_calls('2026-09-07')
```

```php
<?php
// PHP with cURL
$date = '2026-09-07';
$url = 'https://api.awajdigital.com/api/incoming-calls?date=' . urlencode($date) . '&page=1';
$token = 'your_api_token_here';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPGET, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Accept: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>
```

## Success Response Example

```json
{
  "meta": {
    "total": 1,
    "per_page": 100,
    "current_page": 1,
    "last_page": 1
  },
  "data": [
    {
      "id": 5012,
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "ivr_id": 7,
      "caller_number": "01712345678",
      "called_number": "09612345678",
      "started_at": "2026-09-07T10:12:00.000+06:00",
      "ended_at": "2026-09-07T10:14:05.000+06:00",
      "created_at": "2026-09-07T10:12:00.000+06:00",
      "legs": [
        {
          "id": 881,
          "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
          "agent_number": "01812345678",
          "status": "completed",
          "duration": 63,
          "recording_status": "uploaded",
          "recording": "https://cdn.example.com/recordings/leg.wav",
          "started_at": "2026-09-07T10:12:40.000+06:00",
          "ended_at": "2026-09-07T10:13:43.000+06:00"
        }
      ]
    }
  ]
}
```

| Field | Type | Description |
| --- | --- | --- |
| meta.total | integer | Calls that started on this Dhaka day. |
| meta.per_page | integer | Always 100. |
| meta.current_page | integer | Current page. |
| meta.last_page | integer | Last page. |
| data[] | array | Calls ordered by `created_at` ascending. Empty array if none. |
| id | integer | Call id. Upsert on this when re-fetching the day. |
| uuid | string\|null | Call UUID. |
| ivr_id | integer\|null | IVR flow that handled the call. |
| caller_number | string | Number that called you. |
| called_number | string | Your number that was dialled. |
| started_at | string\|null | When the IVR answered. |
| ended_at | string\|null | Hangup time (`null` while the call is live). |
| created_at | string | Call start, ISO 8601 with `Asia/Dhaka` offset. |
| legs[] | array | Forwards to agent numbers, ordered by `started_at`. Empty if the call was never forwarded. |
| legs[].id | integer | Leg id. |
| legs[].uuid | string\|null | Leg call UUID. |
| legs[].agent_number | string | Number the call was forwarded to. |
| legs[].status | string | `active`, `completed`, `failed`, or `transferred`. |
| legs[].duration | integer\|null | Seconds (`null` until the leg ends). |
| legs[].recording_status | string | `pending`, `recording`, `uploaded`, `completed`, `no_recording`, `upload_failed`, or `failed`. |
| legs[].recording | string\|null | Recording URL once uploaded (`null` until then). |
| legs[].started_at | string | Leg start, ISO 8601 with `Asia/Dhaka` offset. |
| legs[].ended_at | string\|null | Leg end (`null` while the leg is live). |

A call that starts at 23:50 and hangs up after midnight still belongs to yesterday.

## Error Responses

| Status | Description |
| --- | --- |
| 401 | Missing or invalid access token |
| 403 | Account does not have the access-incoming-call permission |
| 422 | Missing or invalid `date` (`YYYY-MM-DD`) or `page` |
| 429 | Rate limit exceeded (60 requests/hour) |