×

Configures where incoming calls should be routed. This is required for Inbound/Origination calls - routing calls from the telephone network to your system.

The destination can be an IP address or FQDN (Fully Qualified Domain Name) of your PBX/SBC.

Important Notes

  • For IP-based destinations: You MUST whitelist the IP using the "Map ACL to Trunk" API first
  • For FQDN-based destinations: No whitelisting required (e.g., sip.yourcompany.com)
  • The destination format is: <ip_or_fqdn>:<port>;transport=<protocol>
  • You need to set
 
POST

https://<your_api_key>:<your_api_token>@<subdomain>/v2/accounts/<your_sid>/trunks/<trunk_sid>/destination-uris

Replace <your_api_key> and <your_api_token> with the API key and token created by you.

  • Replace <your_sid> with your “Account sid”
  • Replace <subdomain> with the region of your account
    1. <subdomain> of Singapore cluster is @api.exotel.com
    2. <subdomain> of Mumbai cluster is @api.in.exotel.com

<your_api_key> , <your_api_token> and <your_sid> are available in the API settings page of your Exotel Dashboard

Request Headers

Header Value
Content-Type application/json

Request Parameters

Parameter Name Mandatory/Optional Value
destinations Mandatory Array; List of destination objects. Each object contains a destination field.
destinations[].destination Mandatory String; SIP URI in format <ip_or_fqdn>:<port>;transport=<protocol>. Port is typically 5061 for TLS or 5060 for TCP. Transport can be tls (recommended) or tcp. Example: 44.248.146.11:5061;transport=tls, sip.company.com:5061;transport=tls
  • Sample Request (FQDN-based destination)
curl -X POST "https://<your_api_key>:<your_api_token>@<subdomain>/v2/accounts/<your_sid>/trunks/<trunk_sid>/destination-uris" \
  -H "Content-Type: application/json" \
  -d '{
    "destinations": [
      {
        "destination": "sip.yourcompany.com:5061;transport=tls"
      }
    ]
  }'
  • Sample Request (IP-based destination)
curl -X POST "https://<your_api_key>:<your_api_token>@<subdomain>/v2/accounts/<your_sid>/trunks/<trunk_sid>/destination-uris" \
  -H "Content-Type: application/json" \
  -d '{
    "destinations": [
      {
        "destination": "44.248.146.11:5061;transport=tls"
      }
    ]
  }'

HTTP Response

On success, the HTTP response status code will be 200 OK or 207 Multi-Status (for partial success/failure).

The response includes metadata with counts of successful and failed destinations.

Response Parameters

Parameter Name Type & Value
metadata.total Integer; Total number of destinations in request
metadata.success Integer; Number of successfully added destinations
metadata.failed Integer; Number of failed destinations
id String; Unique identifier for this destination URI. Example: 2543
destination String; The SIP URI (prefixed with sip:)
type String; Destination type: public
priority Integer; Priority for load balancing. Lower values = higher priority. Default: 0
weight Integer; Weight for load balancing. Higher values = more traffic. Default: 1
trunk_sid String; The trunk this destination is associated with
date_created String; ISO 8601 timestamp when destination was created
date_updated String; ISO 8601 timestamp when destination was last updated
  • HTTP Sample Response
{
  "request_id": "63999f0a98a24a0aa58ab5b74aec9f0a",
  "method": "POST",
  "http_code": 200,
  "metadata": {
    "total": 1,
    "success": 1,
    "failed": 0
  },
  "response": [
    {
      "code": 200,
      "error_data": null,
      "status": "success",
      "data": {
        "id": "2543",
        "destination": "sip:44.248.146.11:5061;transport=tls",
        "date_created": "2026-01-23T13:38:32Z",
        "date_updated": "2026-01-23T13:38:32Z",
        "type": "public",
        "priority": 0,
        "weight": 1,
        "trunk_sid": "trmum1f708622631150902801a1n"
      }
    }
  ]
}