Calls API

List Calls

Retrieve all calls associated with a specific lead.

GET /api/public/v1/agents/{agent_id}/leads/{lead_id}/calls

Query Parameters

Parameter	Type	Description
agent_id	string	The ID of the agent
lead_id	string	ID of the lead

Response

[
	{
		"id": "call_id",
		"leadId": "lead_id",
		"transcription": "Call transcript...",
		"summary": "Call summary...",
		"recordingUrl": "https://example.com/recording.mp3",
		"billDuration": 180,
		"callDuration": 180,
		"startTime": "2024-02-14T10:00:00Z",
		"endTime": "2024-02-14T10:30:00Z",
		"callConclusion": "Call ended successfully",
		"apiCallbackUrl": "https://example.com/callback",
		"apiCallbackHeaders": {
			"Authorization": "Bearer api_key"
		},
		"billedDuration": 180,
		"status": "completed",
		"callSuccess": true,
		"additionalInfo": {},
		"callRating": 4.5,
		"callFeedback": "Positive interaction"
	}
]

Create Lead Call

Initiate a new AI-powered call for a specific lead.

POST /api/public/v1/agents/{agent_id}/leads/{lead_id}/calls

Parameters

Parameter	Type	Description
agent_id	string	The ID of the agent
lead_id	string	The ID of the lead to call

Response

{
	"call": {
		"id": "call_id",
		"leadId": "lead_id",
		"transcription": null,
		"summary": null,
		"recordingUrl": null,
		"billDuration": null,
		"callDuration": null,
		"startTime": null,
		"endTime": null,
		"callConclusion": null,
		"apiCallbackUrl": null,
		"apiCallbackHeaders": null,
		"billedDuration": null,
		"status": "initiated",
		"callSuccess": null,
		"additionalInfo": null,
		"callRating": null,
		"callFeedback": null
	},
	"message": "Call Initiated"
}

Get a single call

Retrieve a single call by its ID.

GET /api/public/v1/agents/{agent_id}/leads/{lead_id}/calls/{call_id}

Parameters

Parameter	Type	Description
agent_id	string	The ID of the agent
lead_id	string	The ID of the lead
call_id	string	The ID of the call to retrieve

Response

{
	"id": "call_id",
	"leadId": "lead_id",
	"transcription": "Call transcript...",
	"summary": "Call summary...",
	"recordingUrl": "https://example.com/recording.mp3",
	"billDuration": 180,
	"callDuration": 180,
	"startTime": "2024-02-14T10:00:00Z",
	"endTime": "2024-02-14T10:30:00Z",
	"callConclusion": "Call ended successfully",
	"apiCallbackUrl": "https://example.com/callback",
	"apiCallbackHeaders": {
		"Authorization": "Bearer api_key"
	},
	"billedDuration": 180,
	"status": "completed",
	"callSuccess": true,
	"additionalInfo": {},
	"callRating": 4.5,
	"callFeedback": "Positive interaction"
}

Bulk Call

Create multiple calls for different leads in a single request.

POST /api/public/v1/agents/{agent_id}/leads/bulk-call

Parameters

Parameter	Type	Description
agent_id	string	The ID of the agent

Request Body

{
	"lead_ids": ["lead_id_1", "lead_id_2", "lead_id_3"]
}

Response

{
	"success": true,
	"total_requested": 2,
	"total_queued": 2,
	"missing_leads": null,
	"message": "Successfully queued 2 calls for processing"
}

Important Notes

Bulk calls are queued for processing - they are not immediately initiated
Call records are created by webhooks when calls are actually processed from the queue
Use the List Calls endpoint to retrieve call details after processing begins
Calls are processed in batches with configurable delays between batches

Bulk Call Processing

Bulk calls are processed through a queue system to ensure optimal performance and prevent overwhelming the telephony infrastructure:

Batching: Calls are processed in configurable batches (default: 5 calls per batch)
Rate Limiting: There's a delay between batches (default: 4 minutes)
Concurrent Processing: All calls within a batch are processed simultaneously
Webhook Creation: Call records are created automatically when webhooks are received
Organization Settings: Batch size and delays can be customized per organization

Call States

Status	Description
initiated	Call has been created but not yet started
ringing	Call is ringing
started	Call has started
ended	Call has ended

Error Responses

Status Code	Description
400	Bad Request - Invalid input parameters
401	Unauthorized - Invalid or missing API key
404	Not Found - Call/Lead/Agent not found
500	Internal Server Error

Enhanced Transcription

OutCaller provides enhanced transcription capabilities for higher accuracy and better quality transcriptions.

Request Enhanced Transcription for a Single Call

Request enhanced transcription for a specific call.

POST /api/public/v1/calls/{call_id}/enhance-transcription

Parameters

Parameter	Type	Description
call_id	string	The ID of the call to enhance transcription for

Request Body

{
	"force": false
}

Response

{
	"success": true,
	"message": "Enhanced transcription requested",
	"callId": "call_id",
	"jobId": "job_456",
	"status": "pending"
}

Bulk Enhanced Transcription

Request enhanced transcription for multiple calls in a single request.

POST /api/public/v1/calls/bulk-enhance-transcription

Request Body

{
	"callIds": ["call_id_1", "call_id_2", "call_id_3"],
	"force": false
}

Parameters

Parameter	Type	Description
callIds	array	Array of call IDs to enhance transcription for (max 50)
force	boolean	Force retry failed transcriptions (default: false)

Response

{
	"success": true,
	"message": "Bulk enhanced transcription processed",
	"jobs": [
		{
			"callId": "call_id_1",
			"jobId": "job_456",
			"status": "queued",
			"message": "Enhanced transcription requested"
		},
		{
			"callId": "call_id_2",
			"jobId": "job_789",
			"status": "completed",
			"message": "Enhanced transcription completed",
			"enhancedTranscription": "Enhanced transcript content...",
			"createdAt": "2024-01-01T00:00:00.000Z",
			"completedAt": "2024-01-01T00:05:00.000Z"
		}
	]
}

Get Enhanced Transcription Status

Retrieve the status and content of enhanced transcription for a call.

GET /api/public/v1/calls/{call_id}/enhanced-transcription

Parameters

Parameter	Type	Description
call_id	string	The ID of the call

Response

{
	"success": true,
	"status": "completed",
	"transcription": "Enhanced transcript content...",
	"cost": 0.48,
	"error": null,
	"created_at": "2024-01-01T00:00:00.000Z",
	"updated_at": "2024-01-01T00:05:00.000Z"
}

Enhanced Transcription Status Values

Status	Description
queued	Transcription request submitted and queued for processing
pending	Transcription is currently being processed
completed	Transcription finished successfully
failed	Transcription failed - use force=true to retry

Enhanced Transcription Features

Higher Accuracy: Uses advanced AI technology for improved transcription quality
Bulk Processing: Process up to 50 calls simultaneously
Cost Tracking: Automatic cost calculation and usage tracking
Webhook Support: Receive notifications when transcription completes via organization webhooks
Retry Mechanism: Force retry failed transcriptions
Organization-specific: All transcriptions are scoped to your organization
Real-time Status: Check transcription status through the API

Enhanced Transcription Requirements

Enhanced transcription must be enabled for your organization
Valid API key with appropriate permissions
Calls must belong to your organization
Maximum 50 calls per bulk request

Call Features

Real-time transcription
Enhanced transcription
Call recording
AI-powered conversation
Automatic call rating
Detailed analytics
Call summaries
Multi-language support

Security

All endpoints require authentication
Calls are organization-specific
Call recordings are securely stored
Access is restricted to authorized users only
API keys must have appropriate permissions

On this page