> ## Documentation Index
> Fetch the complete documentation index at: https://www.agentvoice.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Calls

## List All Calls

```http theme={null}
GET https://api.agentvoice.com/api/calls
```

Retrieves calls for your organization with pagination and filtering options.

**Query Parameters**:

| Parameter      | Type     | Default      | Description                                                                                    |
| -------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------- |
| `limit`        | integer  | 50           | Number of results per page (max: 100)                                                          |
| `offset`       | integer  | 0            | Number of results to skip for pagination                                                       |
| `order`        | string   | `desc`       | Sort direction: `asc` or `desc`                                                                |
| `order_by`     | string   | `started_at` | Sort field: `started_at`, `ended_at`, or `created_at`                                          |
| `fields`       | string   | `light`      | Payload size: `light` or `full`                                                                |
| `phone_number` | string   | -            | Filter by customer phone number                                                                |
| `contact_id`   | uuid     | -            | Filter by contact ID                                                                           |
| `agent_id`     | uuid     | -            | Filter by agent ID                                                                             |
| `campaign_id`  | uuid     | -            | Filter by campaign ID                                                                          |
| `status`       | string   | -            | Filter by call status                                                                          |
| `call_type`    | string   | -            | Filter by type: `inbound` or `outbound`                                                        |
| `from`         | ISO 8601 | -            | Filter calls starting after this date                                                          |
| `to`           | ISO 8601 | -            | Filter calls starting before this date                                                         |
| `most_recent`  | boolean  | false        | Return only the most recent matching call                                                      |
| `include`      | string   | -            | Comma-separated list of additional fields to include (see [Include Options](#include-options)) |

**Example Request**:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.agentvoice.com/api/calls?limit=10&order=desc" \
    -H "x-api-key: your-api-key" \
    -H "x-organization-id: your-org-id"
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    "https://api.agentvoice.com/api/calls?limit=10&order=desc",
    {
      method: "GET",
      headers: {
        "x-api-key": "your-api-key",
        "x-organization-id": "your-org-id",
      },
    }
  );

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

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.agentvoice.com/api/calls",
      params={"limit": 10, "order": "desc"},
      headers={
          "x-api-key": "your-api-key",
          "x-organization-id": "your-org-id",
      },
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

**Example Response**:

```json theme={null}
{
  "data": [
    {
      "id": "a7e85eef-65b6-4311-b8f2-7d8bb7abd0ea",
      "agent_id": "95cb3cab-de23-48ee-89c4-7341398f5cec",
      "agent_name": "Sales Agent",
      "contact_id": "123e4567-e89b-12d3-a456-426614174000",
      "contact_first_name": "John",
      "contact_last_name": "Doe",
      "contact_email": "john@example.com",
      "phone_number": "+14155551234",
      "phone_number_called_from": "+17375551234",
      "call_type": "outbound",
      "status": "completed",
      "call_success": true,
      "went_to_voicemail": false,
      "call_duration": 245,
      "started_at": "2024-01-15T10:30:00.000Z",
      "ended_at": "2024-01-15T10:34:05.000Z",
      "ended_reason": "customer-ended-call",
      "recording_url": "https://storage.example.com/recordings/abc123.mp3",
      "campaign_id": "456e7890-e89b-12d3-a456-426614174000",
      "campaign_name": "January Outreach",
      "created_at": "2024-01-15T10:29:55.000Z"
    }
  ],
  "pagination": {
    "total": 1901,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}
```

## Get a Specific Call

```http theme={null}
GET https://api.agentvoice.com/api/calls/:id
```

Retrieves a specific call by ID.

**Query Parameters**:

| Parameter | Type   | Default | Description                                                                                    |
| --------- | ------ | ------- | ---------------------------------------------------------------------------------------------- |
| `fields`  | string | `light` | Payload size: `light` or `full`                                                                |
| `include` | string | -       | Comma-separated list of additional fields to include (see [Include Options](#include-options)) |

**Example Request**:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.agentvoice.com/api/calls/a7e85eef-65b6-4311-b8f2-7d8bb7abd0ea?fields=full" \
    -H "x-api-key: your-api-key" \
    -H "x-organization-id: your-org-id"
  ```

  ```typescript TypeScript theme={null}
  const callId = "a7e85eef-65b6-4311-b8f2-7d8bb7abd0ea";

  const response = await fetch(
    `https://api.agentvoice.com/api/calls/${callId}?fields=full`,
    {
      method: "GET",
      headers: {
        "x-api-key": "your-api-key",
        "x-organization-id": "your-org-id",
      },
    }
  );

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

  ```python Python theme={null}
  import requests

  call_id = "a7e85eef-65b6-4311-b8f2-7d8bb7abd0ea"

  response = requests.get(
      f"https://api.agentvoice.com/api/calls/{call_id}",
      params={"fields": "full"},
      headers={
          "x-api-key": "your-api-key",
          "x-organization-id": "your-org-id",
      },
  )

  call = response.json()
  print(call)
  ```
</CodeGroup>

## Get Most Recent Call

To retrieve only the most recent call matching your filters, use the `most_recent=true` parameter. This returns a single call object instead of an array.

**Example Request**:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.agentvoice.com/api/calls?phone_number=%2B14155551234&most_recent=true" \
    -H "x-api-key: your-api-key" \
    -H "x-organization-id: your-org-id"
  ```

  ```typescript TypeScript theme={null}
  const phoneNumber = "+14155551234";

  const response = await fetch(
    `https://api.agentvoice.com/api/calls?phone_number=${encodeURIComponent(phoneNumber)}&most_recent=true`,
    {
      method: "GET",
      headers: {
        "x-api-key": "your-api-key",
        "x-organization-id": "your-org-id",
      },
    }
  );

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

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.agentvoice.com/api/calls",
      params={
          "phone_number": "+14155551234",
          "most_recent": "true",
      },
      headers={
          "x-api-key": "your-api-key",
          "x-organization-id": "your-org-id",
      },
  )

  most_recent_call = response.json()
  print(most_recent_call)
  ```
</CodeGroup>

**Example Response**:

```json theme={null}
{
  "id": "a7e85eef-65b6-4311-b8f2-7d8bb7abd0ea",
  "agent_id": "95cb3cab-de23-48ee-89c4-7341398f5cec",
  "agent_name": "Sales Agent",
  "contact_id": "123e4567-e89b-12d3-a456-426614174000",
  "contact_first_name": "John",
  "contact_last_name": "Doe",
  "phone_number": "+14155551234",
  "call_type": "outbound",
  "status": "completed",
  "call_success": true,
  "call_duration": 245,
  "started_at": "2024-01-15T10:30:00.000Z",
  "ended_at": "2024-01-15T10:34:05.000Z",
  "created_at": "2024-01-15T10:29:55.000Z"
}
```

## Payload Modes

The API supports two payload modes to optimize response size based on your needs.

### Light Payload (Default)

Returns essential call information suitable for listings and summaries.

**Fields included**:

* `id` - Unique call identifier
* `agent_id` - Agent that handled the call
* `agent_name` - Agent display name
* `contact_id` - Associated contact ID (if linked)
* `contact_first_name` - Contact first name
* `contact_last_name` - Contact last name
* `contact_email` - Contact email
* `phone_number` - Customer phone number
* `phone_number_called_from` - Originating phone number
* `call_type` - `inbound` or `outbound`
* `status` - Call status
* `call_success` - Whether the call was successful
* `went_to_voicemail` - Whether call went to voicemail
* `call_duration` - Duration in seconds
* `started_at` - Call start timestamp
* `ended_at` - Call end timestamp
* `ended_reason` - Reason the call ended
* `recording_url` - URL to call recording (if available)
* `campaign_id` - Associated campaign ID
* `campaign_name` - Campaign name
* `created_at` - Record creation timestamp

### Full Payload

Returns all light fields plus detailed analysis and transcript data. Use `fields=full` to enable.

**Additional fields**:

* `transcript` - Raw transcript text
* `transcript_formatted` - Structured transcript with speaker labels and timestamps
* `post_call_analysis` - AI-generated call analysis
* `call_description` - Summary description of the call
* `custom_analysis` - Custom analysis results
* `structured_data_results` - Extracted structured data from the call
* `notes` - Array of notes added to the call
* `action_executions` - Actions triggered by the call
* `action_summary` - Summary of executed actions
* `quality_metrics` - Call quality measurements
* `enhanced_context` - Additional contextual information

## Include Options

Instead of using `fields=full` which returns everything, you can selectively include specific field groups using the `include` parameter. This allows you to get the light payload plus only the additional data you need.

Use comma-separated values to include multiple groups: `include=transcript,metrics`

| Include       | Fields Added                                          | Description                                   |
| ------------- | ----------------------------------------------------- | --------------------------------------------- |
| `transcript`  | `transcript`, `transcript_formatted`                  | Conversation transcript data                  |
| `metrics`     | `quality_metrics`, `latency_metrics`, `audio_metrics` | Performance and quality measurements          |
| `diagnostics` | `turn_events`, `interruptions`, `tool_usage`          | Detailed call diagnostics for troubleshooting |
| `actions`     | `action_executions`, `action_summary`                 | Actions triggered during the call             |

### Include Examples

Get light payload with just the transcript:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.agentvoice.com/api/calls?include=transcript" \
    -H "x-api-key: your-api-key" \
    -H "x-organization-id: your-org-id"
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    "https://api.agentvoice.com/api/calls?include=transcript",
    {
      method: "GET",
      headers: {
        "x-api-key": "your-api-key",
        "x-organization-id": "your-org-id",
      },
    }
  );

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

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.agentvoice.com/api/calls",
      params={"include": "transcript"},
      headers={
          "x-api-key": "your-api-key",
          "x-organization-id": "your-org-id",
      },
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

Get light payload with transcript and performance metrics:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.agentvoice.com/api/calls?include=transcript,metrics" \
    -H "x-api-key: your-api-key" \
    -H "x-organization-id: your-org-id"
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    "https://api.agentvoice.com/api/calls?include=transcript,metrics",
    {
      method: "GET",
      headers: {
        "x-api-key": "your-api-key",
        "x-organization-id": "your-org-id",
      },
    }
  );

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

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.agentvoice.com/api/calls",
      params={"include": "transcript,metrics"},
      headers={
          "x-api-key": "your-api-key",
          "x-organization-id": "your-org-id",
      },
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

Get a specific call with all diagnostic data:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.agentvoice.com/api/calls/abc-123?include=transcript,metrics,diagnostics,actions" \
    -H "x-api-key: your-api-key" \
    -H "x-organization-id: your-org-id"
  ```

  ```typescript TypeScript theme={null}
  const callId = "abc-123";

  const response = await fetch(
    `https://api.agentvoice.com/api/calls/${callId}?include=transcript,metrics,diagnostics,actions`,
    {
      method: "GET",
      headers: {
        "x-api-key": "your-api-key",
        "x-organization-id": "your-org-id",
      },
    }
  );

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

  ```python Python theme={null}
  import requests

  call_id = "abc-123"

  response = requests.get(
      f"https://api.agentvoice.com/api/calls/{call_id}",
      params={"include": "transcript,metrics,diagnostics,actions"},
      headers={
          "x-api-key": "your-api-key",
          "x-organization-id": "your-org-id",
      },
  )

  call = response.json()
  print(call)
  ```
</CodeGroup>

<Note>
  The `include` parameter works with both `fields=light` (default) and `fields=full`. When used with `fields=full`, any duplicate fields are automatically handled.
</Note>

## Filtering Examples

### Filter by Contact

Get all calls for a specific contact:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.agentvoice.com/api/calls?contact_id=123e4567-e89b-12d3-a456-426614174000" \
    -H "x-api-key: your-api-key" \
    -H "x-organization-id: your-org-id"
  ```

  ```typescript TypeScript theme={null}
  const contactId = "123e4567-e89b-12d3-a456-426614174000";

  const response = await fetch(
    `https://api.agentvoice.com/api/calls?contact_id=${contactId}`,
    {
      method: "GET",
      headers: {
        "x-api-key": "your-api-key",
        "x-organization-id": "your-org-id",
      },
    }
  );

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

  ```python Python theme={null}
  import requests

  contact_id = "123e4567-e89b-12d3-a456-426614174000"

  response = requests.get(
      "https://api.agentvoice.com/api/calls",
      params={"contact_id": contact_id},
      headers={
          "x-api-key": "your-api-key",
          "x-organization-id": "your-org-id",
      },
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

### Filter by Phone Number

Get all calls to/from a specific phone number:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.agentvoice.com/api/calls?phone_number=%2B14155551234" \
    -H "x-api-key: your-api-key" \
    -H "x-organization-id: your-org-id"
  ```

  ```typescript TypeScript theme={null}
  const phoneNumber = "+14155551234";

  const response = await fetch(
    `https://api.agentvoice.com/api/calls?phone_number=${encodeURIComponent(phoneNumber)}`,
    {
      method: "GET",
      headers: {
        "x-api-key": "your-api-key",
        "x-organization-id": "your-org-id",
      },
    }
  );

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

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.agentvoice.com/api/calls",
      params={"phone_number": "+14155551234"},
      headers={
          "x-api-key": "your-api-key",
          "x-organization-id": "your-org-id",
      },
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

<Note>
  Phone numbers should be URL-encoded when using cURL. The `+` character becomes `%2B`. Python's `requests` library handles this automatically.
</Note>

### Filter by Date Range

Get calls from a specific time period:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.agentvoice.com/api/calls?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z" \
    -H "x-api-key: your-api-key" \
    -H "x-organization-id: your-org-id"
  ```

  ```typescript TypeScript theme={null}
  const from = "2024-01-01T00:00:00Z";
  const to = "2024-01-31T23:59:59Z";

  const response = await fetch(
    `https://api.agentvoice.com/api/calls?from=${from}&to=${to}`,
    {
      method: "GET",
      headers: {
        "x-api-key": "your-api-key",
        "x-organization-id": "your-org-id",
      },
    }
  );

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

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.agentvoice.com/api/calls",
      params={
          "from": "2024-01-01T00:00:00Z",
          "to": "2024-01-31T23:59:59Z",
      },
      headers={
          "x-api-key": "your-api-key",
          "x-organization-id": "your-org-id",
      },
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

### Filter by Agent and Status

Get completed calls for a specific agent:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.agentvoice.com/api/calls?agent_id=95cb3cab-de23-48ee-89c4-7341398f5cec&status=completed" \
    -H "x-api-key: your-api-key" \
    -H "x-organization-id: your-org-id"
  ```

  ```typescript TypeScript theme={null}
  const agentId = "95cb3cab-de23-48ee-89c4-7341398f5cec";

  const response = await fetch(
    `https://api.agentvoice.com/api/calls?agent_id=${agentId}&status=completed`,
    {
      method: "GET",
      headers: {
        "x-api-key": "your-api-key",
        "x-organization-id": "your-org-id",
      },
    }
  );

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

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.agentvoice.com/api/calls",
      params={
          "agent_id": "95cb3cab-de23-48ee-89c4-7341398f5cec",
          "status": "completed",
      },
      headers={
          "x-api-key": "your-api-key",
          "x-organization-id": "your-org-id",
      },
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

### Filter by Campaign

Get all calls from a specific campaign:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.agentvoice.com/api/calls?campaign_id=456e7890-e89b-12d3-a456-426614174000&order_by=started_at&order=desc" \
    -H "x-api-key: your-api-key" \
    -H "x-organization-id: your-org-id"
  ```

  ```typescript TypeScript theme={null}
  const campaignId = "456e7890-e89b-12d3-a456-426614174000";

  const response = await fetch(
    `https://api.agentvoice.com/api/calls?campaign_id=${campaignId}&order_by=started_at&order=desc`,
    {
      method: "GET",
      headers: {
        "x-api-key": "your-api-key",
        "x-organization-id": "your-org-id",
      },
    }
  );

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

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.agentvoice.com/api/calls",
      params={
          "campaign_id": "456e7890-e89b-12d3-a456-426614174000",
          "order_by": "started_at",
          "order": "desc",
      },
      headers={
          "x-api-key": "your-api-key",
          "x-organization-id": "your-org-id",
      },
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

### Combine Multiple Filters

Get recent inbound calls for a contact with full details:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.agentvoice.com/api/calls?contact_id=123e4567-e89b-12d3-a456-426614174000&call_type=inbound&order=desc&limit=5&fields=full" \
    -H "x-api-key: your-api-key" \
    -H "x-organization-id: your-org-id"
  ```

  ```typescript TypeScript theme={null}
  const contactId = "123e4567-e89b-12d3-a456-426614174000";

  const params = new URLSearchParams({
    contact_id: contactId,
    call_type: "inbound",
    order: "desc",
    limit: "5",
    fields: "full",
  });

  const response = await fetch(
    `https://api.agentvoice.com/api/calls?${params}`,
    {
      method: "GET",
      headers: {
        "x-api-key": "your-api-key",
        "x-organization-id": "your-org-id",
      },
    }
  );

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

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.agentvoice.com/api/calls",
      params={
          "contact_id": "123e4567-e89b-12d3-a456-426614174000",
          "call_type": "inbound",
          "order": "desc",
          "limit": 5,
          "fields": "full",
      },
      headers={
          "x-api-key": "your-api-key",
          "x-organization-id": "your-org-id",
      },
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

## Pagination

For large result sets, use `limit` and `offset` to paginate through results.

**Example - Page 2 with 25 results per page**:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.agentvoice.com/api/calls?limit=25&offset=25" \
    -H "x-api-key: your-api-key" \
    -H "x-organization-id: your-org-id"
  ```

  ```typescript TypeScript theme={null}
  const pageSize = 25;
  const page = 2; // 1-indexed for human readability

  const response = await fetch(
    `https://api.agentvoice.com/api/calls?limit=${pageSize}&offset=${(page - 1) * pageSize}`,
    {
      method: "GET",
      headers: {
        "x-api-key": "your-api-key",
        "x-organization-id": "your-org-id",
      },
    }
  );

  const data = await response.json();
  console.log(`Page ${page}:`, data.data);
  console.log(`Total calls: ${data.pagination.total}`);
  console.log(`Has more: ${data.pagination.has_more}`);
  ```

  ```python Python theme={null}
  import requests

  page_size = 25
  page = 2  # 1-indexed for human readability

  response = requests.get(
      "https://api.agentvoice.com/api/calls",
      params={
          "limit": page_size,
          "offset": (page - 1) * page_size,
      },
      headers={
          "x-api-key": "your-api-key",
          "x-organization-id": "your-org-id",
      },
  )

  data = response.json()
  print(f"Page {page}:", data["data"])
  print(f"Total calls: {data['pagination']['total']}")
  print(f"Has more: {data['pagination']['has_more']}")
  ```
</CodeGroup>

The response includes pagination metadata:

```json theme={null}
{
  "data": [...],
  "pagination": {
    "total": 1901,
    "limit": 25,
    "offset": 25,
    "has_more": true
  }
}
```

Use `has_more` to determine if additional pages exist.

## Common Error Responses

| Status             | Error                                | Description                                                    |
| ------------------ | ------------------------------------ | -------------------------------------------------------------- |
| `400 Bad Request`  | `"Invalid order_by parameter"`       | order\_by must be `started_at`, `ended_at`, or `created_at`    |
| `401 Unauthorized` | `"Authentication failed"`            | Invalid or missing API key or organization ID                  |
| `404 Not Found`    | `"Call not found"`                   | Call ID does not exist or does not belong to your organization |
| `404 Not Found`    | `"No calls found matching criteria"` | No calls match filters when using `most_recent=true`           |