# Calls

Phone calls your AI receptionist, GH Live agents and team handled. Needs `calls:read`.

Base URL: `https://vocenya.com/api/public/v1`. Authenticate with `Authorization: Bearer $VOCENYA_API_KEY`.

- [List calls](#list-calls): `GET /calls`
- [Get a call](#get-call): `GET /calls/{call}`

## List calls

`GET https://vocenya.com/api/public/v1/calls`

Required scope: `calls:read`

Your calls, newest first.

### Query parameters

- `direction` (string, optional): One of: `inbound`, `outbound`.
- `status` (string, optional): | | |---| | `ringing` <br/>  | | `in_progress` <br/>  | | `completed` <br/>  | | `missed` <br/>  | | `failed` <br/>  | | `blocked` <br/> The caller's number is on the client's blocked callers list: turned away before anyone answered. | One of: `ringing`, `in_progress`, `completed`, `missed`, `failed`, `blocked`.
- `since` (string (date-time), optional): Calls that started at or after this time (ISO 8601).
- `until` (string (date-time), optional): Calls that started before this time (ISO 8601).
- `spam` (string, optional): `true` for only spam and blocked calls, `false` to leave them out. Without it, every call is listed. One of: `true`, `false`, `1`, `0`.
- `per_page` (integer, optional): How many items per page, 1 to 100. Minimum 1. Maximum 100.
- `cursor` (string or null, optional): The `meta.next_cursor` (or `meta.prev_cursor`) of the previous page. Up to 1024 characters.

### Responses

- `200`: Paginated set of `CallResource`
- `401`: The API key is missing, invalid, expired or revoked.
- `403`: The key does not have the `calls:read` scope.
- `422`: Validation error
- `429`: Too many requests for this key. Wait for the `Retry-After` seconds.

### Response attributes (200)

- `data` (array of objects, required)
  - `id` (integer, required)
  - `livemode` (boolean, required): `true` for live data, `false` for test data (created with a `vk_test_` key).
  - `direction` (string, required): Whether the call came in to, or went out from, your number. One of: `inbound`, `outbound`.
  - `status` (string, required): | | |---| | `ringing` <br/>  | | `in_progress` <br/>  | | `completed` <br/>  | | `missed` <br/>  | | `failed` <br/>  | | `blocked` <br/> The caller's number is on the client's blocked callers list: turned away before anyone answered. | One of: `ringing`, `in_progress`, `completed`, `missed`, `failed`, `blocked`.
  - `from_number` (string, required)
  - `caller_name` (string or null, required): The caller's name as the carrier reported it (CNAM), when known.
  - `to_number` (string, required)
  - `spam` (boolean, required): Whether the call was judged spam: by the receptionist, or because the number is on your blocked callers list (`status` is then `blocked`).
  - `routed_to` (string or null, required): Where the call was routed: the AI receptionist, a GH Live agent, your phone or voicemail. One of: `ai_agent`, `human_queue`, `forward_number`, `voicemail`.
  - `started_at` (string, required)
  - `answered_at` (string or null, required)
  - `ended_at` (string or null, required)
  - `duration_seconds` (integer or null, required)
  - `disposition` (string or null, required)
  - `summary` (string or null, optional): The AI's summary of the call. Not included for HIPAA-mode accounts.
  - `handoff_summary` (string or null, optional): What the AI told the person it handed the call to. Not included for HIPAA-mode accounts.
  - `transcript` (array of objects or null, optional): The conversation, turn by turn. Only on `GET /calls/{id}`, and never for HIPAA-mode accounts.
    - `role` (string, required)
    - `text` (string, required)
  - `lead_ids` (array of anys, optional): Leads the AI captured on this call. Only on `GET /calls/{id}`.
  - `created_at` (string or null, required)
- `links` (object, required)
  - `first` (string or null, required)
  - `last` (string or null, required)
  - `prev` (string or null, required)
  - `next` (string or null, required)
- `meta` (object, required)
  - `path` (string or null, required): Base path for paginator generated URLs.
  - `per_page` (integer, required): Number of items shown per page. Minimum 0.
  - `next_cursor` (string or null, required): The "cursor" that points to the next set of items.
  - `prev_cursor` (string or null, required): The "cursor" that points to the previous set of items.

### Example request

```bash
curl https://vocenya.com/api/public/v1/calls \
  -H "Authorization: Bearer $VOCENYA_API_KEY"
```

```javascript
const response = await fetch('https://vocenya.com/api/public/v1/calls', {
  headers: {
    Authorization: `Bearer ${process.env.VOCENYA_API_KEY}`,
  },
});

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

```php
$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://vocenya.com/api/public/v1/calls', [
    'headers' => ['Authorization' => 'Bearer '.getenv('VOCENYA_API_KEY')],
]);

$data = json_decode((string) $response->getBody(), true);
print_r($data);
```

```python
import os

import requests

response = requests.get(
    "https://vocenya.com/api/public/v1/calls",
    headers={"Authorization": f"Bearer {os.environ['VOCENYA_API_KEY']}"},
)

print(response.json())
```

### Example response (200)

```json
{
  "data": [
    {
      "id": 1,
      "livemode": true,
      "direction": "inbound",
      "status": "ringing",
      "from_number": "+15125550123",
      "caller_name": "string",
      "to_number": "+15125550100",
      "spam": true,
      "routed_to": "ai_agent",
      "started_at": "2026-10-02T14:03:11+00:00",
      "answered_at": "2026-10-02T14:03:11+00:00",
      "ended_at": "2026-10-02T14:03:11+00:00",
      "duration_seconds": 1,
      "disposition": "string",
      "summary": "string",
      "handoff_summary": "string",
      "transcript": [
        {
          "role": "string",
          "text": "string"
        }
      ],
      "lead_ids": [],
      "created_at": "2026-10-02T14:03:11+00:00"
    }
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "path": "string",
    "per_page": 1,
    "next_cursor": "string",
    "prev_cursor": "string"
  }
}
```


## Get a call

`GET https://vocenya.com/api/public/v1/calls/{call}`

Required scope: `calls:read`

One call with its transcript and the ids of the leads captured on it. HIPAA-mode accounts get
the call's ids, numbers, statuses and times only: no summary, handoff summary or transcript.

### Path parameters

- `call` (integer, required): The call id.

### Responses

- `200`: `CallResource`
- `401`: The API key is missing, invalid, expired or revoked.
- `403`: The key does not have the `calls:read` scope.
- `404`: No record with that id belongs to your account.
- `429`: Too many requests for this key. Wait for the `Retry-After` seconds.

### Response attributes (200)

- `data` (object, required)
  - `id` (integer, required)
  - `livemode` (boolean, required): `true` for live data, `false` for test data (created with a `vk_test_` key).
  - `direction` (string, required): Whether the call came in to, or went out from, your number. One of: `inbound`, `outbound`.
  - `status` (string, required): | | |---| | `ringing` <br/>  | | `in_progress` <br/>  | | `completed` <br/>  | | `missed` <br/>  | | `failed` <br/>  | | `blocked` <br/> The caller's number is on the client's blocked callers list: turned away before anyone answered. | One of: `ringing`, `in_progress`, `completed`, `missed`, `failed`, `blocked`.
  - `from_number` (string, required)
  - `caller_name` (string or null, required): The caller's name as the carrier reported it (CNAM), when known.
  - `to_number` (string, required)
  - `spam` (boolean, required): Whether the call was judged spam: by the receptionist, or because the number is on your blocked callers list (`status` is then `blocked`).
  - `routed_to` (string or null, required): Where the call was routed: the AI receptionist, a GH Live agent, your phone or voicemail. One of: `ai_agent`, `human_queue`, `forward_number`, `voicemail`.
  - `started_at` (string, required)
  - `answered_at` (string or null, required)
  - `ended_at` (string or null, required)
  - `duration_seconds` (integer or null, required)
  - `disposition` (string or null, required)
  - `summary` (string or null, optional): The AI's summary of the call. Not included for HIPAA-mode accounts.
  - `handoff_summary` (string or null, optional): What the AI told the person it handed the call to. Not included for HIPAA-mode accounts.
  - `transcript` (array of objects or null, optional): The conversation, turn by turn. Only on `GET /calls/{id}`, and never for HIPAA-mode accounts.
    - `role` (string, required)
    - `text` (string, required)
  - `lead_ids` (array of anys, optional): Leads the AI captured on this call. Only on `GET /calls/{id}`.
  - `created_at` (string or null, required)

### Example request

```bash
curl https://vocenya.com/api/public/v1/calls/1042 \
  -H "Authorization: Bearer $VOCENYA_API_KEY"
```

```javascript
const response = await fetch('https://vocenya.com/api/public/v1/calls/1042', {
  headers: {
    Authorization: `Bearer ${process.env.VOCENYA_API_KEY}`,
  },
});

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

```php
$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://vocenya.com/api/public/v1/calls/1042', [
    'headers' => ['Authorization' => 'Bearer '.getenv('VOCENYA_API_KEY')],
]);

$data = json_decode((string) $response->getBody(), true);
print_r($data);
```

```python
import os

import requests

response = requests.get(
    "https://vocenya.com/api/public/v1/calls/1042",
    headers={"Authorization": f"Bearer {os.environ['VOCENYA_API_KEY']}"},
)

print(response.json())
```

### Example response (200)

```json
{
  "data": {
    "id": 1,
    "livemode": true,
    "direction": "inbound",
    "status": "ringing",
    "from_number": "+15125550123",
    "caller_name": "string",
    "to_number": "+15125550100",
    "spam": true,
    "routed_to": "ai_agent",
    "started_at": "2026-10-02T14:03:11+00:00",
    "answered_at": "2026-10-02T14:03:11+00:00",
    "ended_at": "2026-10-02T14:03:11+00:00",
    "duration_seconds": 1,
    "disposition": "string",
    "summary": "string",
    "handoff_summary": "string",
    "transcript": [
      {
        "role": "string",
        "text": "string"
      }
    ],
    "lead_ids": [],
    "created_at": "2026-10-02T14:03:11+00:00"
  }
}
```