POST — Create a Leg
Description
Creates a call leg, which represents one side of a call (customer, agent, bot, or SIP endpoint).
A leg can be:
- Outbound (Exotel → destination)
- Inbound (answered and controlled via actions)
- PSTN or SIP-based
Once created, the leg can be answered, played to, recorded, streamed, bridged, or terminated using Leg Actions.
Endpoint
POST
Full URL
Authentication
- Type: HTTP Basic Authentication
- Username: API Key
- Password: API Token
Request Headers
Request Body Parameters
Mandatory Parameters
Parameter | Type | Description |
|---|---|---|
contact_uri | string | Destination to dial. Can be a phone number or a SIP URI (sip:user@domain). |
exophone | string | Exotel number or SIP identity used as the caller ID. |
leg_event_endpoint | string | gRPC endpoint where leg events are delivered. Must start with grpc://. |
Optional Parameters
Parameter | Type | Default | Description |
|---|---|---|---|
network_type | string | pstn | pstn or voip. Use voip when contact_uri is a SIP URI. |
custom_param | string | – | Custom value echoed back in events for correlation. |
timeout | integer (sec) | 30 | Time allowed for the call to be answered. |
setup_timeout | integer (sec) | 30 | Time allowed for call setup. |
ring_timeout | integer (sec) | 30 | Time the destination is rung. |
time_limit | integer (sec) | 14400 | Maximum duration of the leg (default: 4 hours). |
amd_enable | boolean | false | Enables Answering Machine Detection. |
async_amd | boolean | false | If true, AMD result is delivered asynchronously as an event. |
reference_leg_sid | string | – | Used to colocate legs for low-latency bridging. |
priority | string | normal | Call priority when CPS controls are enabled. |
Example Request
Success Response
HTTP 202 – Accepted
Response Fields
Field | Description |
|---|---|
leg_sid | Unique identifier for the created leg. |
account_sid | Exotel account identifier. |
contact_uri | Destination that was dialed. |
exophone | Caller ID used for the leg. |
network_type | Network used for the call. |
created_at | Timestamp when the leg was created. |
Events Create Leg can generate:
Event Name | data |
|---|---|
“leg_connecting” | "state": "connecting" |
“leg_ringing” | "state": "ringing" |
“leg_answered” | "state": "connected" (if amd_enable is true ) "answered_by":"BEEP/ HUMAN / MACHINE" |
“amd_result_success” | (If amd_enable, async_amd both is set to true ) "state": "connected", "answered_by":"BEEP/ HUMAN / MACHINE" |
“leg_terminated” | "state": "terminal", "terminal_status": "completed/ busy/ no-answer/ failed" |
“leg_failed_to_create” | "state": "terminal", "terminal_status": "failed" |
Error Responses
HTTP Code | Meaning | Description |
|---|---|---|
400 | Bad Request | Missing or invalid parameters |
401 | Unauthorized | Invalid API Key or Token |
403 | Forbidden | Access not allowed for this account |
404 | Not Found | Account SID not found |
429 | Too Many Requests | Rate limit exceeded |
500 | Server Error | Internal error |
Notes & Best Practices
- Creating a leg is asynchronous — wait for events to know when it is answered
- Always store the returned leg_sid
- Use custom_param to correlate calls with your internal systems
- Ensure your leg_event_endpoint is reachable before creating legs
- Use reference_leg_sid when you plan to bridge multiple legs
What’s Next?
After creating a leg, you can:
- Answer or hang up the leg
- Play or say audio
- Record or stream the call
- Bridge the leg with another leg
➡️ Proceed to Leg Actions to control the call.