ConversAI DocsAPI RefList Agents

API Reference

Complete guide for managing leads, initiating AI-powered calls, and configuring webhooks

List Agents

GET/api/v1/agents🔒 Auth Required

Retrieve a paginated list of AI agents with optional filtering by status.

Query Parameters

NameTypeDescription
pageoptional
numberPage number (default: 1)
per_pageoptional
numberItems per page (default: 10, max: 100)
status_filteroptional
stringFilter by status (active, inactive)

Response (200 OK)

NameTypeDescription
agents
arrayArray of agent objects
agents[].id
uuidAgent UUID
agents[].name
stringAgent name
agents[].status
stringAgent status (active, inactive)
agents[].prompt
stringAgent conversation prompt
agents[].voice_id
uuidVoice configuration UUID
agents[].max_attempts
numberMaximum call attempts per lead
agents[].retry_delay_minutes
numberDelay between retry attempts
total
numberTotal number of agents
page
numberCurrent page number
per_page
numberItems per page
Request Example
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"
Response Status Codes
// Success
// See Response Schema in documentation

Update Agent

PUT/api/v1/agents/{agent_id}🔒 Auth Required

Update an existing agent's configuration. All fields are optional - only include fields you want to update.

Path Parameters

NameTypeDescription
agent_idrequired
uuidUUID of the agent to update

Request Body (all fields optional)

NameTypeDescription
nameoptional
stringAgent name
statusoptional
stringAgent status (active, inactive)
promptoptional
stringUpdated agent prompt
welcome_messageoptional
stringUpdated welcome message
voice_idoptional
uuidVoice configuration UUID
max_attemptsoptional
numberMaximum call attempts per lead
retry_delay_minutesoptional
numberDelay between retry attempts

Response (200 OK)

NameTypeDescription
id
uuidAgent identifier
name
stringUpdated agent name
status
stringUpdated status
updated_at
datetimeTimestamp of update
Request Example
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
  }'
Response Status Codes
// Success
// See Response Schema in documentation

Delete Agent

DELETE/api/v1/agents/{agent_id}🔒 Auth Required

Permanently delete an agent from your account. This action cannot be undone.

Path Parameters

NameTypeDescription
agent_idrequired
uuidUUID of the agent to delete

Response (200 OK)

NameTypeDescription
message
stringSuccess message: "Agent deleted"

Warning

This action is permanent and cannot be undone. Deleting an agent will also affect all associated leads and call history.
Request Example
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"
Response Status Codes
// Success
// See Response Schema in documentation

Add Lead

POST/api/v1/leads/🔒 Auth Required

Create a new lead associated with an AI agent. The lead will be available for calling once created.

Request Body

NameTypeDescription
agent_idrequired
uuidUUID of the agent that will call this lead
first_namerequired
stringLead's full name
phone_e164required
stringPhone number in E.164 format (e.g., +14155552671 for US, +919412792855 for India)
custom_fieldsoptional
objectAdditional custom data (email, company, etc.)

Response (200 OK)

NameTypeDescription
lead_id
uuidUnique lead identifier
agent_id
uuidAssociated agent ID
status
stringLead status (new, contacted, scheduled, etc.)
is_verified
booleanWhether the phone number is verified
created_at
datetimeTimestamp when lead was created
lead_created
booleanWhether the lead was created successfully
call_scheduled
booleanWhether a call was scheduled immediately
call_queued
booleanWhether the call was queued for later
interaction_attempt_id
uuid | nullCall interaction attempt ID when scheduled, otherwise null
message
stringResult 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
Request Example
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"
    }
  }'
Response Status Codes
// Success
// See Response Schema in documentation

Bulk Import Leads (CSV)

POST/api/v1/leads/csv-import🔒 Auth Required

Bulk 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

NameTypeDescription
agent_idrequired
uuidUUID of the agent to associate the leads with
list_nameoptional
stringOptional list name for grouping leads, defaults to filename
country_codeoptional
stringISO country code for phone number parsing (default: IN)

Form Data

NameTypeDescription
filerequired
fileThe 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
Request Example
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"'
Response Status Codes
// Success
// See Response Schema in documentation

Get Lead

GET/api/v1/leads/{lead_id}🔒 Auth Required

Retrieve detailed information about a specific lead by its UUID.

Path Parameters

NameTypeDescription
lead_idrequired
uuidUUID of the lead to retrieve

Response (200 OK)

NameTypeDescription
id
uuidUnique lead identifier
agent_id
uuidAssociated agent ID
first_name
stringLead's full name
phone_e164
stringPhone number in E.164 format
status
stringLead status (new, in_progress, done, stopped)
custom_fields
objectCustom data associated with the lead
schedule_at
datetimeScheduled call time
attempts_count
numberNumber of call attempts
disposition
stringCall disposition
created_at
datetimeTimestamp when lead was created
updated_at
datetimeTimestamp when lead was last updated
Request Example
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"
Response Status Codes
// Success
// See Response Schema in documentation

List Leads

GET/api/v1/leads🔒 Auth Required

Retrieve a paginated list of leads with optional filtering by agent, status, or search term.

Query Parameters

NameTypeDescription
agent_idoptional
uuidFilter by agent UUID
status_filteroptional
stringFilter by status (new, in_progress, done, stopped)
searchoptional
stringSearch by name or phone number
pageoptional
numberPage number (default: 1)
per_pageoptional
numberItems per page (default: 10, max: 100)

Response (200 OK)

NameTypeDescription
leads
arrayArray of lead objects
total
numberTotal number of leads matching filters
page
numberCurrent page number
per_page
numberItems per page
Request Example
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"
Response Status Codes
// Success
// See Response Schema in documentation

Update Lead

PUT/api/v1/leads/{lead_id}🔒 Auth Required

Update an existing lead's information. All fields are optional - only include fields you want to update.

Path Parameters

NameTypeDescription
lead_idrequired
uuidUUID of the lead to update

Request Body (all fields optional)

NameTypeDescription
first_nameoptional
stringLead's full name
phone_e164optional
stringPhone number in E.164 format
statusoptional
stringLead status (new, in_progress, done, stopped)
custom_fieldsoptional
objectCustom data (email, company, etc.)
schedule_atoptional
datetimeScheduled call time (ISO 8601 format)
dispositionoptional
stringCall disposition (not_interested, hung_up, completed, no_answer)

Response (200 OK)

NameTypeDescription
id
uuidLead identifier
agent_id
uuidAssociated agent ID
first_name
stringUpdated lead name
status
stringUpdated status
updated_at
datetimeTimestamp of update
Request Example
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"
  }'
Response Status Codes
// Success
// See Response Schema in documentation

Delete Lead

DELETE/api/v1/leads/{lead_id}🔒 Auth Required

Permanently delete a lead from the system. This action cannot be undone.

Path Parameters

NameTypeDescription
lead_idrequired
uuidUUID of the lead to delete

Response (200 OK)

NameTypeDescription
message
stringSuccess message: "Lead deleted successfully"

Warning

This action is permanent and cannot be undone. Make sure you have the correct lead_id before proceeding.
Request Example
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"
Response Status Codes
// Success
// See Response Schema in documentation

Initiate Call

POST/api/v1/calls/schedule🔒 Auth Required

Schedule and initiate an AI-powered voice call to a lead. The call will be executed asynchronously.

Request Body

NameTypeDescription
lead_idrequired
uuidUUID of the lead to call

Response (200 OK)

NameTypeDescription
message
stringSuccess message (e.g., "Lead scheduled successfully")

Call Initiated

The call will be processed asynchronously. Check the calls dashboard or use webhooks to track call status.

Troubleshooting

If you receive "Failed to initiate call", check:
  • Agent configuration is complete with voice settings
  • Lead exists and is in valid state
  • Retell AI integration is properly configured
Request Example
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"
  }'
Response Status Codes
// Success
// See Response Schema in documentation

Get Call History

GET/api/v1/calls/history🔒 Auth Required

Retrieve paginated call history with optional filtering by agent, outcome, date range, or search term.

Query Parameters

NameTypeDescription
agent_idoptional
uuidFilter by agent UUID
outcomeoptional
stringFilter by outcome (answered, no_answer, failed)
start_dateoptional
stringFilter by start date (YYYY-MM-DD)
end_dateoptional
stringFilter by end date (YYYY-MM-DD)
searchoptional
stringSearch by lead name or phone
pageoptional
numberPage number (default: 1)
per_pageoptional
numberItems per page (default: 10, max: 100)

Response (200 OK)

NameTypeDescription
calls
arrayArray of call/interaction objects
calls[].id
uuidInteraction UUID
calls[].lead_id
uuidAssociated lead UUID
calls[].agent_id
uuidAgent UUID
calls[].status
stringCall status (completed, in_progress, failed)
calls[].outcome
stringCall outcome (answered, no_answer, failed)
calls[].duration_seconds
numberCall duration in seconds
calls[].transcript_url
stringURL to call transcript
calls[].summary
stringAI-generated call summary
calls[].ai_insights
objectAI analysis and insights
total
numberTotal number of calls
page
numberCurrent page number
per_page
numberItems per page
Request Example
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"
Response Status Codes
// Success
// See Response Schema in documentation

Get Call Metrics

GET/api/v1/calls/metrics🔒 Auth Required

Retrieve aggregated call statistics and metrics with optional filtering by agent and date range.

Query Parameters

NameTypeDescription
agent_idoptional
uuidFilter by agent UUID
start_dateoptional
stringFilter by start date (YYYY-MM-DD)
end_dateoptional
stringFilter by end date (YYYY-MM-DD)

Response (200 OK)

NameTypeDescription
total_calls
numberTotal number of calls made
answered_calls
numberNumber of answered calls
no_answer_calls
numberNumber of unanswered calls
failed_calls
numberNumber of failed calls
pickup_rate
numberPickup rate percentage (0-100)
average_attempts_per_lead
numberAverage number of attempts per lead
active_agents
numberNumber of active agents

Metrics Calculation

Pickup rate is calculated as (answered_calls / total_calls) × 100. All metrics respect the applied filters.
Request Example
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"
Response Status Codes
// Success
// See Response Schema in documentation

Webhook 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

Only call.failed and call.analysed are currently delivered. call.started and call.completed are deprecated and retained below only for historical integration reference.
call.failed

Triggered when a call fails. The payload includes the failure reason and available provider error details.

call.analysed

Triggered 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.startedDeprecated

Historical event that was sent when a call began. This event is no longer delivered.

call.completedDeprecated

Historical 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

An agent webhook takes priority. The company webhook is used only when no agent webhook is configured. This delivery policy applies to call-result events, not tools invoked during a conversation.

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_id together 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

PUT/api/v1/webhooks/config🔒 Auth Required

Configure webhook URL and event subscriptions for receiving real-time call status updates.

Request Body

NameTypeDescription
lead_nameoptional
stringName of the lead
duration_secondsoptional
integerDuration of the call in seconds
credits_consumedoptional
integerNumber of credits consumed by the call
statusoptional
stringStatus of the call (e.g., "completed")
outcomeoptional
stringOutcome of the call (e.g., "answered")
recording_urloptional
stringURL of the call recording
transcriptoptional
stringTranscript of the call
ai_analysisoptional
objectAI analysis results including lead_status, key_points, next_action_items, and user_extraction_fields
webhook_sourceoptional
stringSource of the webhook (e.g., "agent")

Response (200 OK)

NameTypeDescription
webhook_url
stringConfigured webhook URL
enabled
booleanWebhook enabled status
events
arraySubscribed event types

Available Events

  • call.failed - Triggered when a call fails
  • call.analysed - Triggered when AI analysis completes (includes sentiment, insights, next actions)
  • call.started - Deprecated: no longer delivered
  • call.completed - Deprecated: no longer delivered

Delivery Restriction

Webhook configuration and test requests accept only 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

Transport failures, HTTP 429 and 5xx responses are retried after 1 second and 5 seconds, with at most 3 attempts total. Return a 2xx response promptly.
Request Example
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"
  }'
Response Status Codes
// Success
// See Response Schema in documentation

Get Webhook Configuration

GET/api/v1/webhooks/config🔒 Auth Required

Retrieve the current webhook configuration including URL, enabled status, and subscribed events.

Response (200 OK)

NameTypeDescription
webhook_url
stringConfigured webhook URL
enabled
booleanWhether webhook is enabled
events
arrayArray of subscribed event types
Request Example
curl -X GET "https://voice-ai-admin-api-762279639608.asia-south1.run.app/api/v1/webhooks/config" \
  -H "X-API-Key: your-api-key"
Response Status Codes
// Success
// See Response Schema in documentation

Delete Webhook Configuration

DELETE/api/v1/webhooks/config🔒 Auth Required

Remove the webhook configuration. This will stop all webhook event deliveries.

Response (200 OK)

NameTypeDescription
message
stringSuccess message: "Webhook configuration deleted successfully"
Request Example
curl -X DELETE "https://voice-ai-admin-api-762279639608.asia-south1.run.app/api/v1/webhooks/config" \
  -H "X-API-Key: your-api-key"
Response Status Codes
// Success
// See Response Schema in documentation

Send Test Webhook

POST/api/v1/webhooks/test🔒 Auth Required

Send a test webhook event to verify your webhook endpoint is properly configured and receiving events.

Request Body

NameTypeDescription
event_typeoptional
stringEvent type to test (call.failed or call.analysed). Default: call.failed

Response (200 OK)

NameTypeDescription
status
stringTest status (success/failure)
message
stringDescriptive message
response_status
numberHTTP status code from your webhook endpoint

Testing Tip

Use this endpoint to verify your webhook integration before going live. Check that your endpoint returns 200 status code.
Request Example
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"}'
Response Status Codes
// Success
// See Response Schema in documentation

Additional 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.