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.

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

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 when a call completes successfully
call.failed - Triggered when a call fails

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

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

Get Webhook Logs

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

Retrieve webhook delivery logs for debugging and monitoring webhook event deliveries.

Query Parameters

Name	Type	Description
`limit`	`number`	Number of logs to retrieve (default: 50, max: 200)
`offset`	`number`	Pagination offset (default: 0)
`event_type`	`string`	Filter by event type
`delivery_status`	`string`	Filter by delivery status (pending, success, failed, retrying)

Response (200 OK)

Name	Type	Description
`total`	`number`	Total number of logs
`limit`	`number`	Number of logs returned
`offset`	`number`	Pagination offset
`logs`	`array`	Array of webhook log entries
`logs[].event_type`	`string`	Type of event sent
`logs[].call_id`	`uuid`	Associated call/interaction UUID
`logs[].delivery_status`	`string`	Delivery status (pending, success, failed, retrying)
`logs[].http_status`	`number`	HTTP status code from webhook endpoint
`logs[].sent_at`	`datetime`	Timestamp when webhook was sent

Monitoring

Use these logs to debug webhook delivery issues. Check for failed deliveries and verify your endpoint is responding with 2xx status codes.

Request Example

curl -X GET "https://voice-ai-admin-api-762279639608.asia-south1.run.app/api/v1/webhooks/logs?limit=10" \
  -H "X-API-Key: your-api-key"

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?