Skip to main content
POST
/
api
/
calls
/
create-phone-call
curl -X POST "https://api.zudu.ai/api/calls/create-phone-call" \
  -H "X-API-KEY: sk_Abc123Def456..." \
  -H "X-API-SECRET: s3cr3t_Xyz789..." \
  -d '{
    "from_number": "+14157774444",
    "to_number": "+12137774445",
    "override_agent_id": "agent_1234567890",
    "metadata": {
      "customer_id": "cust-001",
      "campaign": "summer-2024"
    }
  }'

{
  "message": "Phone call created and initiated successfully",
  "status": "success",
  "error": null,
  "data": {
    "organization_id": "org_1234567890",
    "call_type": "phone_call",
    "status": "call_initiated",
    "call": {
      "call_id": "call_abc123def456",
      "agent_id": "agent_1234567890",
      "organization_id": "org_1234567890",
      "call_status": "ONGOING",
      "call_type": "PHONE_CALL",
      "from_number": "+14157774444",
      "to_number": "+12137774445",
      "direction": "OUTBOUND",
      "created_at": 1705320000000
    },
    "phone_call_info": {
      "from_number": "+14157774444",
      "to_number": "+12137774445",
      "direction": "outbound",
      "call_status": "ongoing"
    }
  }
}
Create a phone call record and automatically trigger outbound calling through LiveKit. This endpoint combines call data creation with actual phone call initiation. 
curl -X POST "https://api.zudu.ai/api/calls/create-phone-call" \
  -H "X-API-KEY: sk_Abc123Def456..." \
  -H "X-API-SECRET: s3cr3t_Xyz789..." \
  -d '{
    "from_number": "+14157774444",
    "to_number": "+12137774445",
    "override_agent_id": "agent_1234567890",
    "metadata": {
      "customer_id": "cust-001",
      "campaign": "summer-2024"
    }
  }'

{
  "message": "Phone call created and initiated successfully",
  "status": "success",
  "error": null,
  "data": {
    "organization_id": "org_1234567890",
    "call_type": "phone_call",
    "status": "call_initiated",
    "call": {
      "call_id": "call_abc123def456",
      "agent_id": "agent_1234567890",
      "organization_id": "org_1234567890",
      "call_status": "ONGOING",
      "call_type": "PHONE_CALL",
      "from_number": "+14157774444",
      "to_number": "+12137774445",
      "direction": "OUTBOUND",
      "created_at": 1705320000000
    },
    "phone_call_info": {
      "from_number": "+14157774444",
      "to_number": "+12137774445",
      "direction": "outbound",
      "call_status": "ongoing"
    }
  }
}

​
Headers

​
X-API-KEY
string
required
Your API key (format: sk_...)
​
X-API-SECRET
string
required
Your API secret (format: s3cr3t_...)

​
Request Body

​
from_number
string
required
The phone number to call from (E.164 format)Example: "+14157774444"
​
to_number
string
required
The phone number to call (E.164 format)Example: "+12137774445"
​
override_agent_id
string
Optional agent ID to use for this call. If not provided, the system will automatically select the best agent based on the from_number.Example: "agent_1234567890"
​
scheduled_timestamp
integer
Optional Unix timestamp (in seconds) to schedule the call for a future time. If provided, the call will be created but not immediately initiated.Example: 1705320000
​
metadata
object
Optional metadata to attach to the callCan include any custom fields like:
  • customer_id: Customer identifier
  • campaign: Campaign name
  • priority: Priority level
Example:
{
  "customer_id": "cust-001",
  "campaign": "summer-2024"
}

​
Response Fields

​
data.call_id
string
The unique identifier for the created callFormat: call_...
​
data.call_type
string
Type of call - always "phone_call" for this endpoint
​
data.status
string
Status of the call initiationValues: "call_initiated", "scheduled", "error"
​
data.phone_call_info
object
Phone call specific informationIncludes:
  • from_number: Source phone number
  • to_number: Destination phone number
  • direction: Call direction (outbound/inbound)
  • call_status: Current call status

​
Error Responses

​
error
string
Bad Request - Missing required fields
{
  "message": "Missing required fields",
  "status": "error",
  "error": "from_number and to_number are required for phone calls"
}
​
error
string
Not Found - Agent does not exist
{
  "message": "Agent not found",
  "status": "error",
  "error": "Agent with ID 'agent_123' does not exist in organization 'org_123'"
}
​
error
string
Payment Required - Insufficient credits
{
  "message": "Insufficient credits",
  "status": "error",
  "error": "Organization does not have sufficient credits for outbound calling"
}
​
error
string
Unauthorized - Missing or invalid API key/secret

​
Notes

  • The organization ID is automatically extracted from your API key
  • If override_agent_id is not provided, the system automatically selects the best agent based on the from_number
  • Phone numbers must be in E.164 format (e.g., +14157774444)
  • Scheduled calls will be executed automatically at the specified timestamp
  • The call is immediately initiated unless scheduled_timestamp is provided
  • Credits are validated before call initiation for outbound calls