Calls

List All Calls

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)

Example Request:

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"

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

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)

Example Response:

{
  "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

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)

Example Request:

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"

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

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)

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:

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"

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

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)

Example Response:

{
  "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

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:

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"

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

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)

Get light payload with transcript and performance metrics:

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"

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

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)

Get a specific call with all diagnostic data:

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"

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

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)

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

Filtering Examples

Filter by Contact

Get all calls for a specific contact:

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"

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

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)

Filter by Phone Number

Get all calls to/from a specific phone number:

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"

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

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)

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

Filter by Date Range

Get calls from a specific time period:

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"

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

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)

Filter by Agent and Status

Get completed calls for a specific agent:

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"

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

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)

Filter by Campaign

Get all calls from a specific campaign:

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"

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

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)

Combine Multiple Filters

Get recent inbound calls for a contact with full details:

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"

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

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)

Pagination

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

Example - Page 2 with 25 results per page:

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"

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

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']}")

The response includes pagination metadata:

{
  "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`

On this page