API Reference

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

Environment Setup

Quick Start

Set these environment variables before making API calls

Base URL

https://voice-ai-admin-api-762279639608.asia-south1.run.app/api/v1

API Key

your-api-key-here

Authentication

API Key Authentication

All API requests must be authenticated using an API key. The API key should be included in the request header.

X-API-Key: <your-api-key>

Getting Your API Key

For existing accounts and new accounts, retrieve your API key from the admin panel dashboard → profile settings. Can be used for all API calls.

Agent Management

List Agents

GET/api/v1/agents🔒 Auth Required

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

Query Parameters

Name	Type	Description
`page`	`number`	Page number (default: 1)
`per_page`	`number`	Items per page (default: 10, max: 100)
`status_filter`	`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

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"

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

Name	Type	Description
`agent_id`required	`uuid`	UUID of the agent to update

Request Body (all fields optional)

Name	Type	Description
`name`	`string`	Agent name
`status`	`string`	Agent status (active, inactive)
`prompt`	`string`	Updated agent prompt
`welcome_message`	`string`	Updated welcome message
`voice_id`	`uuid`	Voice configuration UUID
`max_attempts`	`number`	Maximum call attempts per lead
`retry_delay_minutes`	`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

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
  }'

Delete Agent

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

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

Path Parameters

Name	Type	Description
`agent_id`required	`uuid`	UUID of the agent to delete

Response (200 OK)

Name	Type	Description
`message`	`string`	Success 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"

Lead Management

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

Name	Type	Description
`agent_id`required	`uuid`	UUID of the agent that will call this lead
`first_name`required	`string`	Lead's full name
`phone_e164`required	`string`	Phone number in E.164 format (e.g., +14155552671 for US, +919412792855 for India)
`custom_fields`	`object`	Additional custom data (email, company, etc.)

Response (200 OK)

Name	Type	Description
`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

Important Note

Phone numbers must be in E.164 format
Ensure the trailing slash in the endpoint: /api/v1/leads/
Indian numbers are auto-verified with "company_verified" method

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

Get Lead

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

Retrieve detailed information about a specific lead by its UUID.

Path Parameters

Name	Type	Description
`lead_id`required	`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

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"

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

Name	Type	Description
`agent_id`	`uuid`	Filter by agent UUID
`status_filter`	`string`	Filter by status (new, in_progress, done, stopped)
`search`	`string`	Search by name or phone number
`page`	`number`	Page number (default: 1)
`per_page`	`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

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"

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

Name	Type	Description
`lead_id`required	`uuid`	UUID of the lead to update

Request Body (all fields optional)

Name	Type	Description
`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 (email, company, etc.)
`schedule_at`	`datetime`	Scheduled call time (ISO 8601 format)
`disposition`	`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

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

Delete Lead

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

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

Path Parameters

Name	Type	Description
`lead_id`required	`uuid`	UUID of the lead to delete

Response (200 OK)

Name	Type	Description
`message`	`string`	Success 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"

Call Management

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

Name	Type	Description
`lead_id`required	`uuid`	UUID of the lead to call

Response (200 OK)

Name	Type	Description
`message`	`string`	Success 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"
  }'

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

Name	Type	Description
`agent_id`	`uuid`	Filter by agent UUID
`outcome`	`string`	Filter by outcome (answered, no_answer, failed)
`start_date`	`string`	Filter by start date (YYYY-MM-DD)
`end_date`	`string`	Filter by end date (YYYY-MM-DD)
`search`	`string`	Search by lead name or phone
`page`	`number`	Page number (default: 1)
`per_page`	`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

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"

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

Name	Type	Description
`agent_id`	`uuid`	Filter by agent UUID
`start_date`	`string`	Filter by start date (YYYY-MM-DD)
`end_date`	`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

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"

Webhook Management

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:

call.started

Triggered when a call begins. This event fires immediately when an outbound call is initiated or an inbound call is received.

call.completed

Triggered when a call ends. The event payload includes details like call duration, status, outcome, transcript, recording URL, and other relevant information. This event fires immediately upon call completion and does NOT include AI analysis.

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.

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

Webhook Delivery Requirements

Your endpoint must use HTTPS (HTTP is not supported)
Return a 2xx status code within 30 seconds to acknowledge receipt
Failed deliveries are retried at 1min, 5min, and 15min intervals (max 4 attempts)
Implement idempotency using call_id to handle duplicate events

Webhook Payload Examples

call.started

{
  "event": "call.started",
  "timestamp": "2025-01-15T10:30:00Z",
  "call_id": "uuid",
  "lead_id": "uuid",
  "agent_id": "uuid",
  "phone_number": "+1234567890",
  "lead_name": "John Doe"
}

call.completed

{
  "event": "call.completed",
  "timestamp": "2025-01-15T10:35:00Z",
  "call_id": "uuid",
  "lead_id": "uuid",
  "agent_id": "uuid",
  "duration_seconds": 125,
  "tokens_consumed": 5,
  "status": "completed",
  "outcome": "answered",
  "summary": "Call completed successfully",
  "recording_url": "https://...",
  "transcript": "..."
}

Note: AI analysis is NOT included in this event. Use call.analysed for AI insights.

call.analysed

{
  "event": "call.analysed",
  "timestamp": "2025-01-15T10:35:30Z",
  "call_id": "uuid",
  "lead_id": "uuid",
  "agent_id": "uuid",
  "duration_seconds": 125,
  "tokens_consumed": 5,
  "status": "completed",
  "outcome": "answered",
  "summary": "Call completed successfully",
  "ai_analysis": {
    "sentiment": "positive",
    "key_points": [
      "Customer interested in product demo",
      "Budget confirmed at $50k"
    ],
    "next_action": "Schedule product demonstration",
    "call_successful": true,
    "custom_analysis_data": {}
  },
  "recording_url": "https://...",
  "transcript": "..."
}

This event fires after call.completed, typically 5-30 seconds later when AI analysis finishes.

Configure Webhook

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

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

Request Body

Name	Type	Description
`webhook_url`required	`string`	Your endpoint URL to receive webhook events
`enabled`	`boolean`	Enable/disable webhook (default: true)
`events`	`array`	Array of event types to subscribe to (default: all events)

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.started - Triggered when a call begins
call.completed - Triggered immediately when a call ends (basic info, no AI analysis)
call.failed - Triggered when a call fails
call.analysed - Triggered when AI analysis completes (includes sentiment, insights, next actions)

Webhook Delivery

Failed deliveries will be retried at 1min, 5min, and 15min intervals (max 4 attempts). Ensure your endpoint returns 2xx status codes.

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 '{
    "webhook_url": "https://your-domain.com/webhook",
    "enabled": true,
    "events": ["call.started", "call.completed", "call.failed", "call.analysed"]
  }'

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)

Name	Type	Description
`webhook_url`	`string`	Configured webhook URL
`enabled`	`boolean`	Whether webhook is enabled
`events`	`array`	Array 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"

Delete Webhook Configuration

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

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

Response (200 OK)

Name	Type	Description
`message`	`string`	Success 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"

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

Name	Type	Description
`event_type`	`string`	Event type to test (call.started, call.completed, call.failed). Default: call.completed

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

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.completed"}'

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?