--- title: POST — Create a Leg slug: voice-apis/post-create-a-leg docTags: createdAt: 2026-01-19T08:16:22.868Z --- # 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** :::BlockQuote /v2/accounts/{account\_sid}/legs ::: ## Full URL :::BlockQuote https\://cpaas-api.in.exotel.com/v2/accounts/{account\_sid}/legs ::: ## Authentication - **Type:** HTTP Basic Authentication - **Username:** API Key - **Password:** API Token ## Request Headers :::BlockQuote Content-Type: application/json Authorization: Basic \ ::: ## 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 :::BlockQuote curl -u "\:\" \\ -H "Content-Type: application/json" \\ -X POST \\ https\://cpaas-api.in.exotel.com/v2/accounts/\/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** :::BlockQuote \{ "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.