API Reference
Complete guide for managing leads, initiating AI-powered calls, and configuring webhooks
List Agents
/api/v1/agents🔒 Auth RequiredRetrieve a paginated list of AI agents with optional filtering by status.
Query Parameters
| Name | Type | Description |
|---|---|---|
pageoptional | number | Page number (default: 1) |
per_pageoptional | number | Items per page (default: 10, max: 100) |
status_filteroptional | string | Filter by status (active, inactive) |
Response (200 OK)
| Name | Type | Description |
|---|---|---|
agents | array | Array of agent objects |
agents[].id | uuid | Agent UUID |
agents[].name | string | Agent name |
agents[].status | string | Agent status (active, inactive) |
agents[].prompt | string | Agent conversation prompt |
agents[].voice_id | uuid | Voice configuration UUID |
agents[].max_attempts | number | Maximum call attempts per lead |
agents[].retry_delay_minutes | number | Delay between retry attempts |
total | number | Total number of agents |
page | number | Current page number |
per_page | number | Items per page |
curl -X GET "https://voice-ai-admin-api-762279639608.asia-south1.run.app/api/v1/agents?page=1&per_page=20&status_filter=active" \
-H "X-API-Key: your-api-key"// Success
// See Response Schema in documentationUpdate Agent
/api/v1/agents/{agent_id}🔒 Auth RequiredUpdate an existing agent's configuration. All fields are optional - only include fields you want to update.
Path Parameters
| Name | Type | Description |
|---|---|---|
agent_idrequired | uuid | UUID of the agent to update |
Request Body (all fields optional)
| Name | Type | Description |
|---|---|---|
nameoptional | string | Agent name |
statusoptional | string | Agent status (active, inactive) |
promptoptional | string | Updated agent prompt |
welcome_messageoptional | string | Updated welcome message |
voice_idoptional | uuid | Voice configuration UUID |
max_attemptsoptional | number | Maximum call attempts per lead |
retry_delay_minutesoptional | number | Delay between retry attempts |
Response (200 OK)
| Name | Type | Description |
|---|---|---|
id | uuid | Agent identifier |
name | string | Updated agent name |
status | string | Updated status |
updated_at | datetime | Timestamp of update |
curl -X PUT "https://voice-ai-admin-api-762279639608.asia-south1.run.app/api/v1/agents/{agent_id}" \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"name": "Updated Agent Name",
"status": "active",
"max_attempts": 5
}'// Success
// See Response Schema in documentationDelete Agent
/api/v1/agents/{agent_id}🔒 Auth RequiredPermanently delete an agent from your account. This action cannot be undone.
Path Parameters
| Name | Type | Description |
|---|---|---|
agent_idrequired | uuid | UUID of the agent to delete |
Response (200 OK)
| Name | Type | Description |
|---|---|---|
message | string | Success message: "Agent deleted" |
Warning
curl -X DELETE "https://voice-ai-admin-api-762279639608.asia-south1.run.app/api/v1/agents/{agent_id}" \
-H "X-API-Key: your-api-key"// Success
// See Response Schema in documentationAdd Lead
/api/v1/leads/🔒 Auth RequiredCreate a new lead associated with an AI agent. The lead will be available for calling once created.
Request Body
| Name | Type | Description |
|---|---|---|
agent_idrequired | uuid | UUID of the agent that will call this lead |
first_namerequired | string | Lead's full name |
phone_e164required | string | Phone number in E.164 format (e.g., +14155552671 for US, +919412792855 for India) |
custom_fieldsoptional | object | Additional custom data (email, company, etc.) |
Response (200 OK)
| Name | Type | Description |
|---|---|---|
lead_id | uuid | Unique lead identifier |
agent_id | uuid | Associated agent ID |
status | string | Lead status (new, contacted, scheduled, etc.) |
is_verified | boolean | Whether the phone number is verified |
created_at | datetime | Timestamp when lead was created |
lead_created | boolean | Whether the lead was created successfully |
call_scheduled | boolean | Whether a call was scheduled immediately |
call_queued | boolean | Whether the call was queued for later |
interaction_attempt_id | uuid | null | Call interaction attempt ID when scheduled, otherwise null |
message | string | Result message for lead creation and call scheduling |
Response Format Update
Previous create-lead response format is deprecated. This endpoint now returns the new operational response format documented above.
Important Note
- This endpoint initiates a call after lead creation when the lead is eligible for calling
- Phone numbers must be in E.164 format
- Ensure the trailing slash in the endpoint:
/api/v1/leads/ - Verification status in response depends on your company-level phone verification state
curl -X POST "https://voice-ai-admin-api-762279639608.asia-south1.run.app/api/v1/leads/" \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "b0b52c8c-b5c8-474a-a9fb-109473f436b4",
"first_name": "John Doe",
"phone_e164": "+14155552671",
"custom_fields": {
"email": "john@example.com",
"company": "ABC Corp"
}
}'// Success
// See Response Schema in documentationBulk Import Leads (CSV)
/api/v1/leads/csv-import🔒 Auth RequiredBulk import leads from a CSV file. The CSV must contain at minimum 'Name' and 'Phone' columns. This endpoint returns a job ID that can be used to check the import status.
Query Parameters
| Name | Type | Description |
|---|---|---|
agent_idrequired | uuid | UUID of the agent to associate the leads with |
list_nameoptional | string | Optional list name for grouping leads, defaults to filename |
country_codeoptional | string | ISO country code for phone number parsing (default: IN) |
Form Data
| Name | Type | Description |
|---|---|---|
filerequired | file | The CSV file containing the leads data. Must end with .csv extension. |
CSV Format Requirements
- Must contain at minimum Name and Phone columns
- Phone numbers should ideally include country codes
- File must have a .csv extension
curl --location 'https://voice-ai-admin-api-762279639608.asia-south1.run.app/api/v1/leads/csv-import?agent_id=YOUR_AGENT_ID' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'file=@"/path/to/your/leads.csv"'// Success
// See Response Schema in documentationGet Lead
/api/v1/leads/{lead_id}🔒 Auth RequiredRetrieve detailed information about a specific lead by its UUID.
Path Parameters
| Name | Type | Description |
|---|---|---|
lead_idrequired | uuid | UUID of the lead to retrieve |
Response (200 OK)
| Name | Type | Description |
|---|---|---|
id | uuid | Unique lead identifier |
agent_id | uuid | Associated agent ID |
first_name | string | Lead's full name |
phone_e164 | string | Phone number in E.164 format |
status | string | Lead status (new, in_progress, done, stopped) |
custom_fields | object | Custom data associated with the lead |
schedule_at | datetime | Scheduled call time |
attempts_count | number | Number of call attempts |
disposition | string | Call disposition |
created_at | datetime | Timestamp when lead was created |
updated_at | datetime | Timestamp when lead was last updated |
curl -X GET "https://voice-ai-admin-api-762279639608.asia-south1.run.app/api/v1/leads/{lead_id}" \
-H "X-API-Key: your-api-key"// Success
// See Response Schema in documentationList Leads
/api/v1/leads🔒 Auth RequiredRetrieve a paginated list of leads with optional filtering by agent, status, or search term.
Query Parameters
| Name | Type | Description |
|---|---|---|
agent_idoptional | uuid | Filter by agent UUID |
status_filteroptional | string | Filter by status (new, in_progress, done, stopped) |
searchoptional | string | Search by name or phone number |
pageoptional | number | Page number (default: 1) |
per_pageoptional | number | Items per page (default: 10, max: 100) |
Response (200 OK)
| Name | Type | Description |
|---|---|---|
leads | array | Array of lead objects |
total | number | Total number of leads matching filters |
page | number | Current page number |
per_page | number | Items per page |
curl -X GET "https://voice-ai-admin-api-762279639608.asia-south1.run.app/api/v1/leads?agent_id=your-agent-uuid&status_filter=new&page=1&per_page=20" \
-H "X-API-Key: your-api-key"// Success
// See Response Schema in documentationUpdate Lead
/api/v1/leads/{lead_id}🔒 Auth RequiredUpdate an existing lead's information. All fields are optional - only include fields you want to update.
Path Parameters
| Name | Type | Description |
|---|---|---|
lead_idrequired | uuid | UUID of the lead to update |
Request Body (all fields optional)
| Name | Type | Description |
|---|---|---|
first_nameoptional | string | Lead's full name |
phone_e164optional | string | Phone number in E.164 format |
statusoptional | string | Lead status (new, in_progress, done, stopped) |
custom_fieldsoptional | object | Custom data (email, company, etc.) |
schedule_atoptional | datetime | Scheduled call time (ISO 8601 format) |
dispositionoptional | string | Call disposition (not_interested, hung_up, completed, no_answer) |
Response (200 OK)
| Name | Type | Description |
|---|---|---|
id | uuid | Lead identifier |
agent_id | uuid | Associated agent ID |
first_name | string | Updated lead name |
status | string | Updated status |
updated_at | datetime | Timestamp of update |
curl -X PUT "https://voice-ai-admin-api-762279639608.asia-south1.run.app/api/v1/leads/{lead_id}" \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"first_name": "Jane Doe",
"status": "in_progress"
}'// Success
// See Response Schema in documentationDelete Lead
/api/v1/leads/{lead_id}🔒 Auth RequiredPermanently delete a lead from the system. This action cannot be undone.
Path Parameters
| Name | Type | Description |
|---|---|---|
lead_idrequired | uuid | UUID of the lead to delete |
Response (200 OK)
| Name | Type | Description |
|---|---|---|
message | string | Success message: "Lead deleted successfully" |
Warning
curl -X DELETE "https://voice-ai-admin-api-762279639608.asia-south1.run.app/api/v1/leads/{lead_id}" \
-H "X-API-Key: your-api-key"// Success
// See Response Schema in documentationInitiate Call
/api/v1/calls/schedule🔒 Auth RequiredSchedule and initiate an AI-powered voice call to a lead. The call will be executed asynchronously.
Request Body
| Name | Type | Description |
|---|---|---|
lead_idrequired | uuid | UUID of the lead to call |
Response (200 OK)
| Name | Type | Description |
|---|---|---|
message | string | Success message (e.g., "Lead scheduled successfully") |
Call Initiated
Troubleshooting
- Agent configuration is complete with voice settings
- Lead exists and is in valid state
- Retell AI integration is properly configured
curl -X POST "https://voice-ai-admin-api-762279639608.asia-south1.run.app/api/v1/calls/schedule" \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"lead_id": "b0160b3d-9eb5-45e2-abd6-8b6b785fe941"
}'// Success
// See Response Schema in documentationGet Call History
/api/v1/calls/history🔒 Auth RequiredRetrieve paginated call history with optional filtering by agent, outcome, date range, or search term.
Query Parameters
| Name | Type | Description |
|---|---|---|
agent_idoptional | uuid | Filter by agent UUID |
outcomeoptional | string | Filter by outcome (answered, no_answer, failed) |
start_dateoptional | string | Filter by start date (YYYY-MM-DD) |
end_dateoptional | string | Filter by end date (YYYY-MM-DD) |
searchoptional | string | Search by lead name or phone |
pageoptional | number | Page number (default: 1) |
per_pageoptional | number | Items per page (default: 10, max: 100) |
Response (200 OK)
| Name | Type | Description |
|---|---|---|
calls | array | Array of call/interaction objects |
calls[].id | uuid | Interaction UUID |
calls[].lead_id | uuid | Associated lead UUID |
calls[].agent_id | uuid | Agent UUID |
calls[].status | string | Call status (completed, in_progress, failed) |
calls[].outcome | string | Call outcome (answered, no_answer, failed) |
calls[].duration_seconds | number | Call duration in seconds |
calls[].transcript_url | string | URL to call transcript |
calls[].summary | string | AI-generated call summary |
calls[].ai_insights | object | AI analysis and insights |
total | number | Total number of calls |
page | number | Current page number |
per_page | number | Items per page |
curl -X GET "https://voice-ai-admin-api-762279639608.asia-south1.run.app/api/v1/calls/history?agent_id=your-agent-uuid&outcome=answered&page=1&per_page=20" \
-H "X-API-Key: your-api-key"// Success
// See Response Schema in documentationGet Call Metrics
/api/v1/calls/metrics🔒 Auth RequiredRetrieve aggregated call statistics and metrics with optional filtering by agent and date range.
Query Parameters
| Name | Type | Description |
|---|---|---|
agent_idoptional | uuid | Filter by agent UUID |
start_dateoptional | string | Filter by start date (YYYY-MM-DD) |
end_dateoptional | string | Filter by end date (YYYY-MM-DD) |
Response (200 OK)
| Name | Type | Description |
|---|---|---|
total_calls | number | Total number of calls made |
answered_calls | number | Number of answered calls |
no_answer_calls | number | Number of unanswered calls |
failed_calls | number | Number of failed calls |
pickup_rate | number | Pickup rate percentage (0-100) |
average_attempts_per_lead | number | Average number of attempts per lead |
active_agents | number | Number of active agents |
Metrics Calculation
curl -X GET "https://voice-ai-admin-api-762279639608.asia-south1.run.app/api/v1/calls/metrics?agent_id=your-agent-uuid&start_date=2025-01-01&end_date=2025-01-31" \
-H "X-API-Key: your-api-key"// Success
// See Response Schema in documentationWebhook Overview
Overview
Webhooks in ConversAI Labs provide a powerful way to respond to call events in real-time. By setting up webhooks, your applications can immediately react to specific call actions or changes, enhancing the interactivity and responsiveness of your integrations.
Types of Webhook Events
Currently, ConversAI Labs supports the following webhook event types:
Active and Deprecated Events
call.failed and call.analysed are currently delivered. call.started and call.completed are deprecated and retained below only for historical integration reference.call.failedTriggered when a call fails. The payload includes the failure reason and available provider error details.
call.analysedTriggered when AI analysis completes, typically 5-30 seconds after the call ends. The event payload includes all call details PLUS AI-generated insights such as sentiment analysis, key points extracted from the conversation, and recommended next actions. Use this event when you need AI insights for your workflow automation.
call.startedDeprecatedHistorical event that was sent when a call began. This event is no longer delivered.
call.completedDeprecatedHistorical event that was sent immediately after a call ended. This event is no longer delivered; use call.analysed for completed-call data.
Use Case Example
Consider the call.analysed event. This event is triggered when AI processing completes for a call in your ConversAI Labs account. By listening to this event, you can capture important call details and AI-generated insights, then perform custom actions such as:
- •CRM Integration: Automatically update lead status in Salesforce or HubSpot based on call sentiment
- •Task Creation: Create follow-up tasks for sales reps based on AI-recommended next actions
- •Analytics: Stream call data and AI insights to your data warehouse for analysis
- •Notifications: Send Slack or email alerts to managers when high-value opportunities are detected
Register Webhook
Configure your webhook through the API to receive real-time event notifications. You can specify:
- ✓Webhook URL: Your HTTPS endpoint that will receive event notifications
- ✓Event Subscriptions: Choose which events to receive (or subscribe to all events)
- ✓Enable/Disable: Toggle webhook delivery on or off without changing configuration
Call-result routing
Webhook Delivery Requirements
- Your endpoint must use HTTPS (HTTP is not supported)
- Return a 2xx status code promptly; the HTTP client timeout is configured to 30 seconds
- Transport failures, HTTP 429 and 5xx responses are retried after delays of 1 second and 5 seconds (at most 3 attempts total)
- Implement idempotency using the event type and
call_idtogether to handle duplicate deliveries without discarding different events for the same call
Webhook Payload Examples
call.failed
{
"event": "call.failed",
"timestamp": "2025-01-15T10:30:00Z",
"call_direction": "outbound",
"call_id": "uuid",
"lead_id": "uuid",
"agent_id": "uuid",
"phone_number": "+1234567890",
"lead_name": "John Doe",
"status": "failed",
"failure_reason": "busy",
"error_message": "User line was busy or unreachable."
}call.analysed
{
"event": "call.analysed",
"timestamp": "2025-01-15T10:35:20Z",
"call_direction": "outbound",
"call_id": "uuid",
"lead_id": "uuid",
"agent_id": "uuid",
"duration_seconds": 17,
"credits_consumed": 1,
"status": "completed",
"outcome": "answered",
"recording_url": "https://api.example.com/recordings/call_123.wav",
"transcript": "Agent: Hello, how can I help you today?\nUser: I would like to learn more about your services.",
"ai_analysis": {
"key_points": [
"John Doe asked the purpose of the call."
],
"next_action_items": [],
"user_extraction_fields": {
"Consultation": "",
"Email": null,
"Level": null,
"Department": null,
"Course": null
}
}
}This event fires after the call ends, typically 5-30 seconds later when AI analysis finishes.
call.startedDeprecated — no longer delivered
{
"event": "call.started",
"timestamp": "2025-01-15T10:30:00Z",
"call_direction": "outbound",
"call_id": "uuid",
"lead_id": "uuid",
"agent_id": "uuid",
"phone_number": "+1234567890",
"lead_name": "John Doe"
}call.completedDeprecated — no longer delivered
{
"event": "call.completed",
"timestamp": "2025-01-15T10:35:00Z",
"call_direction": "outbound",
"call_id": "uuid",
"lead_id": "uuid",
"agent_id": "uuid",
"duration_seconds": 125,
"status": "completed",
"recording_url": "https://...",
"transcript": "..."
}Configure Webhook
/api/v1/webhooks/config🔒 Auth RequiredConfigure webhook URL and event subscriptions for receiving real-time call status updates.
Request Body
| Name | Type | Description |
|---|---|---|
lead_nameoptional | string | Name of the lead |
duration_secondsoptional | integer | Duration of the call in seconds |
credits_consumedoptional | integer | Number of credits consumed by the call |
statusoptional | string | Status of the call (e.g., "completed") |
outcomeoptional | string | Outcome of the call (e.g., "answered") |
recording_urloptional | string | URL of the call recording |
transcriptoptional | string | Transcript of the call |
ai_analysisoptional | object | AI analysis results including lead_status, key_points, next_action_items, and user_extraction_fields |
webhook_sourceoptional | string | Source of the webhook (e.g., "agent") |
Response (200 OK)
| Name | Type | Description |
|---|---|---|
webhook_url | string | Configured webhook URL |
enabled | boolean | Webhook enabled status |
events | array | Subscribed event types |
Available Events
call.failed- Triggered when a call failscall.analysed- Triggered when AI analysis completes (includes sentiment, insights, next actions)call.started- Deprecated: no longer deliveredcall.completed- Deprecated: no longer delivered
Delivery Restriction
call.failed and call.analysed. Deprecated events cannot be configured, tested, resent, or delivered.Webhook Event Payloads
All webhook payloads include the following base properties:
{
"event": "call.failed",
"timestamp": "2025-01-15T10:35:00Z",
"call_direction": "outbound",
"call_id": "uuid",
"lead_id": "uuid",
"agent_id": "uuid",
"agent_name": "Riya",
"phone_number": "+1234567890",
"lead_name": "John Doe"
}Direction values are always one of inbound or outbound.
1. call.failed
Sent if the call cannot be completed due to an error. Includes these additional fields on top of base fields (including call_direction):
{
"call_direction": "inbound",
"status": "failed",
"failure_reason": "busy",
"error_message": "User line was busy or unreachable."
}2. call.analysed
Sent after the call is processed by AI. Contains the complete call details, including call_direction, plus the analysis:
{
"call_direction": "outbound",
"duration_seconds": 17,
"credits_consumed": 1,
"status": "completed",
"outcome": "answered",
"recording_url": "https://api.example.com/recordings/call_123.wav",
"transcript": "Agent: Hello, how can I help you today?\nUser: I would like to learn more about your services.",
"ai_analysis": {
"key_points": [
"John Doe asked the purpose of the call."
],
"next_action_items": [],
"user_extraction_fields": {
"Consultation": "",
"Email": null,
"Level": null,
"Department": null,
"Course": null
}
}
}Deprecated: call.started
Historical payload contained only the base call fields. This event is no longer delivered.
Deprecated: call.completed
Historical payload contained call duration, status, recording, and transcript fields. This event is no longer delivered.
Webhook Delivery
curl -X PUT "https://voice-ai-admin-api-762279639608.asia-south1.run.app/api/v1/webhooks/config" \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"lead_name": "John Doe",
"duration_seconds": 17,
"credits_consumed": 1,
"status": "completed",
"outcome": "answered",
"recording_url": "https://api.example.com/recordings/call_123.wav",
"transcript": "Agent: Hello, how can I help you today?\nUser: I would like to learn more about your services.",
"ai_analysis": {
"lead_status": "cold",
"key_points": [
"John Doe asked the purpose of the call."
],
"next_action_items": [],
"user_extraction_fields": {
"Consultation": "",
"Email": null,
"Level": null,
"Department": null,
"Course": null
}
},
"webhook_source": "agent"
}'// Success
// See Response Schema in documentationGet Webhook Configuration
/api/v1/webhooks/config🔒 Auth RequiredRetrieve the current webhook configuration including URL, enabled status, and subscribed events.
Response (200 OK)
| Name | Type | Description |
|---|---|---|
webhook_url | string | Configured webhook URL |
enabled | boolean | Whether webhook is enabled |
events | array | Array of subscribed event types |
curl -X GET "https://voice-ai-admin-api-762279639608.asia-south1.run.app/api/v1/webhooks/config" \
-H "X-API-Key: your-api-key"// Success
// See Response Schema in documentationDelete Webhook Configuration
/api/v1/webhooks/config🔒 Auth RequiredRemove the webhook configuration. This will stop all webhook event deliveries.
Response (200 OK)
| Name | Type | Description |
|---|---|---|
message | string | Success message: "Webhook configuration deleted successfully" |
curl -X DELETE "https://voice-ai-admin-api-762279639608.asia-south1.run.app/api/v1/webhooks/config" \
-H "X-API-Key: your-api-key"// Success
// See Response Schema in documentationSend Test Webhook
/api/v1/webhooks/test🔒 Auth RequiredSend a test webhook event to verify your webhook endpoint is properly configured and receiving events.
Request Body
| Name | Type | Description |
|---|---|---|
event_typeoptional | string | Event type to test (call.failed or call.analysed). Default: call.failed |
Response (200 OK)
| Name | Type | Description |
|---|---|---|
status | string | Test status (success/failure) |
message | string | Descriptive message |
response_status | number | HTTP status code from your webhook endpoint |
Testing Tip
curl -X POST "https://voice-ai-admin-api-762279639608.asia-south1.run.app/api/v1/webhooks/test" \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"event_type": "call.failed"}'// Success
// See Response Schema in documentationAdditional Information
Prerequisites
- You need an existing agent_id to create leads
- Use GET /api/v1/agents with authentication to list agents
- Phone numbers must be in E.164 format
- Get API key from admin panel settings
Need Help?
Contact us at connect@conversailabs.com for support or questions about the API.