Calls - AgentVoice

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"

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": "[email protected]",
      "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"

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"

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

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:

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"

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"

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"

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"

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"

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"

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"

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"

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"

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"

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`

API Reference

​List All Calls

​Get a Specific Call

​Get Most Recent Call

​Payload Modes

​Light Payload (Default)

​Full Payload

​Include Options

​Include Examples

​Filtering Examples

​Filter by Contact

​Filter by Phone Number

​Filter by Date Range

​Filter by Agent and Status

​Filter by Campaign

​Combine Multiple Filters

​Pagination

​Common Error Responses

List All Calls

Get a Specific Call

Get Most Recent Call

Payload Modes

Light Payload (Default)

Full Payload

Include Options

Include Examples

Filtering Examples

Filter by Contact

Filter by Phone Number

Filter by Date Range

Filter by Agent and Status

Filter by Campaign

Combine Multiple Filters

Pagination

Common Error Responses