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 /v2/accounts/{account sid}/legs full url https //cpaas api in exotel com/v2/accounts/{account sid}/legs authentication type http basic authentication username api key password api token request headers content type application/json authorization basic \<base64(api key\ api token)> 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 curl u "\<api key> \<api token>" \\ h "content type application/json" \\ x post \\ https //cpaas api in exotel com/v2/accounts/\<account sid>/legs \\ d '{ "contact uri" "09163816621", "exophone" "08030752400", "leg event endpoint" "grpc //127 0 0 1 9001", "network type" "pstn", "timeout" 30, "time limit" 600 }' success response http 202 – accepted { "request id" "811b113c561a4d35bd8520112eb629f7", "method" "post", "http code" 202, "response" { "error data" null, "data" { "leg sid" "2qyatxq9t4ukcuwcqjclsa9oez400000", "account sid" "ameyo5m", "contact uri" "09163816621", "exophone" "08030752400", "network type" "pstn", "created at" "2023 05 31t08 02 32z" } } } 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