Detailed SIP Trunking API Reference

this section documents the apis required to configure and manage sip trunking with exotel use these apis to make outbound calls to the pstn receive inbound calls on your sip system integrate sip with exotel flows and voice ai (streamkit) base url & authentication all apis use http basic authentication base urls region base url india (mumbai) https //api in exotel com singapore https //api exotel com all endpoints are prefixed with /v2/accounts/{account sid} required headers authorization basic \<api key\ api token> content type application/json rate limits limit type value requests per minute 200 api workflow overview typical pstn setup follows this order → create trunk → map phone number → map acl (outbound) → map destination uri (inbound) getting started (pstn setup) this section covers the apis required to set up sip trunking for standard pstn (telephone network) connectivity https //www postman com/grey star 272776/exotel sip trunking apis/collection/14803574 a0c66128 0e2c 4e6d a06a 03173b9d43cd https //github com/exotel/exotel vsip trunk configuration api/tree/main setup flow create trunk → 2 map phone number → 3 map acl (for outbound) → 4 map destination uri (for inbound) 1\ create trunk creates a new sip trunk this is the first step for all sip trunking use cases a sip trunk acts as a virtual connection between your communication system (pbx/contact center) and exotel's telephony network http request post https //\<your api key> \<your api token>@\<subdomain>/v2/accounts/\<your sid>/trunks request headers header value content type application/json request parameters the following parameters are sent as json in the body of the request parameter name mandatory/optional value trunk name mandatory string; unique identifier for the trunk must be alphanumeric with underscores only, maximum 16 characters example outbound trunk, my pbx trunk nso code mandatory string; network service operator code use any anyfor standard configuration domain name mandatory string; sip domain for the trunk format \<your sid> pstn exotel com example ameyo5m pstn exotel com example request curl s x post "https //\<your api key> \<your api token>@\<subdomain>/v2/accounts/\<your sid>/trunks" \\ h "content type application/json" \\ d '{ "trunk name" "outbound trunk", "nso code" "any any", "domain name" "\<your sid> pstn exotel com" }' http response on success, the http response status code will be 200 ok the trunk sidis the unique identifier of the trunk save this value as it will be required for all subsequent api calls example response { "request id" "10a67da360d446378d5c2b66407b7f18", "method" "post", "http code" 200, "response" { "code" 200, "error data" null, "status" "success", "data" { "trunk name" "outbound trunk", "date created" "2026 01 23t09 24 59z", "date updated" "2026 01 23t09 24 59z", "trunk sid" "trmum1f708622631150902801a1n", "status" "active", "domain name" "ameyo5m pstn exotel com", "auth type" "ip whitelist", "registration enabled" "disabled", "edge preference" "auto", "nso code" "any any", "secure trunking" "disabled", "destination uris" "/v2/accounts/ameyo5m/trunks/trmum1f708622631150902801a1n/destination uris", "whitelisted ips" "/v2/accounts/ameyo5m/trunks/trmum1f708622631150902801a1n/whitelisted ips", "credentials" "/v2/accounts/ameyo5m/trunks/trmum1f708622631150902801a1n/credentials", "phone numbers" "/v2/accounts/ameyo5m/trunks/trmum1f708622631150902801a1n/phone numbers" } } } response parameters parameter name type & value request id string; unique identifier for this api request method string; http method used (post) http code integer; http status code (200 for success) trunk sid string; important unique identifier for the trunk save this for subsequent api calls example trmum1f708622631150902801a1n trunk name string; name of the trunk as provided in request domain name string; sip domain for the trunk status string; current trunk status active trunk is ready for use, inactive trunk is disabled auth type string; authentication type currently only ip whitelistis supported registration enabled string; sip registration status enabledor disabled edge preference string; edge server preference default auto nso code string; network service operator code secure trunking string; tls status enabledor disabled destination uris string; api path to manage destination uris for this trunk whitelisted ips string; api path to manage acls (whitelisted ips) for this trunk credentials string; api path to credentials for this trunk phone numbers string; api path to manage phone numbers for this trunk date created string; iso 8601 timestamp when trunk was created date updated string; iso 8601 timestamp when trunk was last updated 2\ map phone number to trunk associates a phone number (did/exophone) with the trunk this phone number will be used for making and receiving calls through the trunk http request post https //\<your api key> \<your api token>@\<subdomain>/v2/accounts/\<your sid>/trunks/\<trunk sid>/phone numbers request headers header value content type application/json request parameters parameter name mandatory/optional value phone number mandatory string; the phone number to map to the trunk must be in e 164 format (with country code) example +919876543210, +912247790597 mode optional string; routing mode for the phone number can be pstn(default) routes calls to telephone network, flow routes calls to voice ai bot (streamkit) if not specified, defaults to nulland behaves as pstn example request curl s x post "https //\<your api key> \<your api token>@\<subdomain>/v2/accounts/\<your sid>/trunks/\<trunk sid>/phone numbers" \\ h "content type application/json" \\ d '{ "phone number" "+919876543210" }' for streamkit (voice ai) mode curl s x post "https //\<your api key> \<your api token>@\<subdomain>/v2/accounts/\<your sid>/trunks/\<trunk sid>/phone numbers" \\ h "content type application/json" \\ d '{ "phone number" "+919876543210", "mode" "flow" }' http response on success, the http response status code will be 200 ok important save the idfrom the response this numeric id is required for the update phone number mode api example response { "request id" "13ab9319cf574486ba299c364f82cade", "method" "post", "http code" 200, "response" { "code" 200, "error data" null, "status" "success", "data" { "id" "41512", "phone number" "+919876543210", "trunk sid" "trmum1f708622631150902801a1n", "date created" "2026 01 23t10 26 54z", "date updated" "2026 01 23t10 26 54z", "mode" null } } } response parameters parameter name type & value id string; important numeric identifier for this phone number mapping save this value required for update phone number mode api example 41512 phone number string; the mapped phone number in e 164 format trunk sid string; the trunk this phone number is associated with mode string or null; routing mode pstn pstn routing, flow streamkit/voice ai routing, null default (same as pstn) date created string; iso 8601 timestamp when mapping was created date updated string; iso 8601 timestamp when mapping was last updated 3\ map acl to trunk (whitelist ip) registers your server's public ip address for authentication this is required for outbound/termination calls allowing your system to send calls through the trunk acl (access control list) ensures only authorized ip addresses can use your trunk for outbound calling http request post https //\<your api key> \<your api token>@\<subdomain>/v2/accounts/\<your sid>/trunks/\<trunk sid>/whitelisted ips request headers header value content type application/json request parameters parameter name mandatory/optional value ip mandatory string; your server's public ip address must be a valid ipv4 address example 44 248 146 11, 203 0 113 50 mask optional integer; subnet mask in cidr notation default 32(single ip) use 24for /24 subnet, 16for /16 subnet example 32, 24 example request curl s x post "https //\<your api key> \<your api token>@\<subdomain>/v2/accounts/\<your sid>/trunks/\<trunk sid>/whitelisted ips" \\ h "content type application/json" \\ d '{ "ip" "44 248 146 11", "mask" 32 }' http response on success, the http response status code will be 200 ok example response { "request id" "3daaed4cd05d443f854e07e60dd4c008", "method" "post", "http code" 200, "response" { "code" 200, "error data" null, "status" "success", "data" { "id" "1153", "mask" 32, "trunk sid" "trmum1f708622631150902801a1n", "ip" "44 248 146 11", "friendly name" null, "date created" "2026 01 23t11 37 36z", "date updated" "2026 01 23t11 37 36z" } } } response parameters parameter name type & value id string; unique identifier for this acl entry example 1153 ip string; the whitelisted ip address mask integer; subnet mask in cidr notation trunk sid string; the trunk this acl is associated with friendly name string or null; optional friendly name for the ip date created string; iso 8601 timestamp when acl was created date updated string; iso 8601 timestamp when acl was last updated 4\ map destination uri to trunk 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 http request post https //\<your api key> \<your api token>@\<subdomain>/v2/accounts/\<your sid>/trunks/\<trunk sid>/destination uris 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 destinationfield destinations\[] destination mandatory string; sip uri in format \<ip or fqdn> \<port>;transport=\<protocol> port is typically 5061for tls or 5060for tcp transport can be tls(recommended) or tcp example 44 248 146 11 5061;transport=tls, sip company com 5061;transport=tls example request (ip based destination) note ensure the ip 44 248 146 11is whitelisted first using map acl api curl s 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" } ] }' example request (fqdn based destination) curl s 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" } ] }' http response on success, the http response status code will be 200 okor 207 multi status(for partial success/failure) the response includes metadatawith counts of successful and failed destinations example response (success) { "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" } } ] } 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 for inbound sip a create a flow using connect applet in app bazaar https //my in exotel com/apps b use sip \<trunk sid> in the dial whom field c map did to flow through exophone https //my in exotel com/numbers d check inbound call flow by dialling exophone/phonenumber to your system via exotel sip trunking e follow detailed steps here docid\ euvmvkznxnkm6zsjoc9gw f advance routing for custom routing, use a dynamic url to fetch the destination uri and pass headers or define failover use programmable connect supports up to 3 custom sip headers , e g , x param1=value1 (max 200 bytes total) headers prefixed with exotel or veeno are platform reserved connect applet – dynamic url response example { "fetch after attempt" false, "destination" { "trunk" "trunk 2134" }, "custom params" "param1=value1\&param2=value2", "record" true, "recording channels" "dual" } manage & view apis for viewing configurations, updating settings, and managing your trunk 5\ get phone numbers retrieves all phone numbers mapped to a trunk http request get https //\<your api key> \<your api token>@\<subdomain>/v2/accounts/\<your sid>/trunks/\<trunk sid>/phone numbers example request curl s x get "https //\<your api key> \<your api token>@\<subdomain>/v2/accounts/\<your sid>/trunks/\<trunk sid>/phone numbers" example response { "request id" "785471d288054cbf8c677b75e0b5f2f8", "method" "get", "http code" 200, "metadata" { "page size" 50, "first page uri" "/v2/accounts/ameyo5m/trunks/trmum1f708622631150902801a1n/phone numbers?offset=0\&page size=50", "prev page uri" null, "next page uri" null }, "response" \[ { "code" 200, "error data" null, "status" "success", "data" { "id" "41523", "phone number" "+918040264208", "trunk sid" "trmum1f708622631150902801a1n", "date created" "2026 01 23t13 28 11z", "date updated" "2026 01 23t13 41 59z", "mode" "flow" } } ] } response parameters parameter name type & value metadata page size integer; number of results per page metadata first page uri string; uri for the first page metadata prev page uri string or null; uri for previous page (null if on first page) metadata next page uri string or null; uri for next page (null if on last page) response\[] array; list of phone number objects 6\ get acls (whitelisted ips) retrieves all whitelisted ip addresses for a trunk http request get https //\<your api key> \<your api token>@\<subdomain>/v2/accounts/\<your sid>/trunks/\<trunk sid>/whitelisted ips example request curl s x get "https //\<your api key> \<your api token>@\<subdomain>/v2/accounts/\<your sid>/trunks/\<trunk sid>/whitelisted ips" example response { "request id" "91dc982ca79846479c6f9678c788cfc1", "method" "get", "http code" 200, "metadata" { "page size" 50, "first page uri" "/v2/accounts/ameyo5m/trunks/trmum1f708622631150902801a1n/whitelisted ips?offset=0\&page size=50", "prev page uri" null, "next page uri" null }, "response" \[ { "code" 200, "error data" null, "status" "success", "data" { "id" "1154", "mask" 32, "trunk sid" "trmum1f708622631150902801a1n", "ip" "44 248 146 11", "friendly name" null, "date created" "2026 01 23t13 30 04z", "date updated" "2026 01 23t13 30 04z" } } ] } 7\ get destination uris retrieves all destination uris configured for a trunk http request get https //\<your api key> \<your api token>@\<subdomain>/v2/accounts/\<your sid>/trunks/\<trunk sid>/destination uris example request curl s x get "https //\<your api key> \<your api token>@\<subdomain>/v2/accounts/\<your sid>/trunks/\<trunk sid>/destination uris" example response { "request id" "bfc1544ab0ab4df3ae49173ccc744331", "method" "get", "http code" 200, "metadata" { "page size" 50, "first page uri" "/v2/accounts/ameyo5m/trunks/trmum1f708622631150902801a1n/destination uris?offset=0\&page size=50", "prev page uri" null, "next page uri" null }, "response" \[ { "code" 200, "error data" null, "status" "success", "data" { "id" "2544", "destination" "sip\ sip company com 5061;transport=tls", "date created" "2026 01 23t13 39 06z", "date updated" "2026 01 23t13 39 06z", "type" "public", "priority" 0, "weight" 1, "trunk sid" "trmum1f708622631150902801a1n" } }, { "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" } } ] } 8\ update phone number mode updates the routing mode for a mapped phone number use this to switch between pstn and streamkit (voice ai) modes http request put https //\<your api key> \<your api token>@\<subdomain>/v2/accounts/\<your sid>/trunks/\<trunk sid>/phone numbers/\<phone number id> important the \<phone number id>is the numeric id returned when you mapped the phone number (e g , 41523), not the phone number itself request headers header value content type application/json request parameters parameter name mandatory/optional value phone number mandatory string; the phone number in e 164 format must match the phone number associated with the id example +919876543210 mode mandatory string; the new routing mode can be pstn route calls to telephone network, flow route calls to voice ai bot (streamkit) example request (switch to flow mode) curl s x put "https //\<your api key> \<your api token>@\<subdomain>/v2/accounts/\<your sid>/trunks/\<trunk sid>/phone numbers/41523" \\ h "content type application/json" \\ d '{ "phone number" "+918040264208", "mode" "flow" }' example request (switch to pstn mode) curl s x put "https //\<your api key> \<your api token>@\<subdomain>/v2/accounts/\<your sid>/trunks/\<trunk sid>/phone numbers/41523" \\ h "content type application/json" \\ d '{ "phone number" "+918040264208", "mode" "pstn" }' example response { "request id" "c719cd56eb5943e789e1bdbd4ce1515a", "method" "put", "http code" 200, "response" { "code" 200, "error data" null, "status" "success", "data" { "id" "41523", "phone number" "+918040264208", "trunk sid" "trmum1f708622631150902801a1n", "date created" "2026 01 23t13 28 11z", "date updated" "2026 01 23t13 41 59z", "mode" "flow" } } } response parameters parameter name type & value id string; the phone number mapping id phone number string; the phone number in e 164 format trunk sid string; the associated trunk mode string; the updated routing mode (pstn or flow) date created string; iso 8601 timestamp when mapping was created date updated string; iso 8601 timestamp when mapping was updated (will be updated after this call) 9\ set trunk alias (caller id) sets the phone number displayed to called parties on outbound calls this is useful when you want to display a specific caller id regardless of which phone number is mapped to the trunk http request post https //\<your api key> \<your api token>@\<subdomain>/v2/accounts/\<your sid>/trunks/\<trunk sid>/settings request headers header value content type application/json request parameters parameter name mandatory/optional value settings mandatory array; list of setting objects settings\[] name mandatory string; setting name use trunk external aliasfor caller id settings\[] value mandatory string; the phone number to display as caller id should be in e 164 format example +919876543210 example request curl s x post "https //\<your api key> \<your api token>@\<subdomain>/v2/accounts/\<your sid>/trunks/\<trunk sid>/settings" \\ h "content type application/json" \\ d '{ "settings" \[ { "name" "trunk external alias", "value" "+919876543210" } ] }' example response { "request id" "8ce98845365f43fd97c2f46df38438c6", "method" "post", "http code" 200, "metadata" { "total" 1, "success" 1 }, "response" \[ { "code" 200, "error data" null, "status" "success", "data" { "name" "trunk external alias", "value" "+919876543210", "trunk sid" "trmum1f708622631150902801a1n", "date created" "2026 01 23t13 34 50z", "date updated" "2026 01 23t13 34 50z" } } ] } response parameters parameter name type & value metadata total integer; total number of settings in request metadata success integer; number of successfully applied settings name string; setting name (trunk external alias) value string; the caller id phone number trunk sid string; the associated trunk date created string; iso 8601 timestamp when setting was created date updated string; iso 8601 timestamp when setting was last updated 10\ delete trunk permanently deletes a trunk and all its associated configurations (phone numbers, acls, destination uris) ⚠️ warning this action cannot be undone all associated phone number mappings, whitelisted ips, and destination uris will be permanently deleted http request delete https //\<your api key> \<your api token>@\<subdomain>/v2/accounts/\<your sid>/trunks?trunk sid=\<trunk sid> example request curl s x delete "https //\<your api key> \<your api token>@\<subdomain>/v2/accounts/\<your sid>/trunks?trunk sid=\<trunk sid>" example response { "request id" "f708818c79f547b3aee31c4a480367a5", "method" "delete", "http code" 200, "response" { "code" 200, "error data" null, "status" "success", "data" { "trunk name" "my trunk1234", "date created" "2026 01 23t13 25 39z", "date updated" "2026 01 23t13 25 39z", "trunk sid" "trmum15f77c83605998cdb9d1a1n", "status" "active", "domain name" "ameyo5m pstn exotel com", "auth type" "ip whitelist", "registration enabled" "disabled", "edge preference" "auto", "nso code" "any any", "secure trunking" "disabled", "destination uris" "/v2/accounts/ameyo5m/trunks/trmum15f77c83605998cdb9d1a1n/destination uris", "whitelisted ips" "/v2/accounts/ameyo5m/trunks/trmum15f77c83605998cdb9d1a1n/whitelisted ips", "credentials" "/v2/accounts/ameyo5m/trunks/trmum15f77c83605998cdb9d1a1n/credentials", "phone numbers" "/v2/accounts/ameyo5m/trunks/trmum15f77c83605998cdb9d1a1n/phone numbers" } } } response parameters the response returns the full trunk data that was deleted, allowing you to verify which trunk was removed error codes reference error code http status message description 1000 404 not found resource not found (invalid trunk sid, phone number id, etc ) 1001 400 mandatory parameter missing required parameter not provided 1002 400 invalid parameter parameter value is invalid or malformed 1007 400 invalid request body json parsing error or malformed request body 1008 409 duplicate resource resource already exists (duplicate trunk name, ip already whitelisted, etc ) 1011 415 unsupported content type wrong content type header use application/json quick reference api endpoints summary api method endpoint create trunk post /v2/accounts/{sid}/trunks map phone number post /v2/accounts/{sid}/trunks/{trunk sid}/phone numbers map acl post /v2/accounts/{sid}/trunks/{trunk sid}/whitelisted ips map destination uri post /v2/accounts/{sid}/trunks/{trunk sid}/destination uris get phone numbers get /v2/accounts/{sid}/trunks/{trunk sid}/phone numbers get acls get /v2/accounts/{sid}/trunks/{trunk sid}/whitelisted ips get destination uris get /v2/accounts/{sid}/trunks/{trunk sid}/destination uris update phone number mode put /v2/accounts/{sid}/trunks/{trunk sid}/phone numbers/{id} set trunk alias post /v2/accounts/{sid}/trunks/{trunk sid}/settings delete trunk delete /v2/accounts/{sid}/trunks?trunk sid={trunk sid} mode options mode description use case pstn routes calls to telephone network standard pbx/contact center integration flow routes calls to voice ai bot streamkit/voice ai integration notes duplicate resource errors (1008) are safe and can be ignored if the configuration already exists destination uri must always be configured, even when using exotel flows flow mode is required only for voicebot or non connect applets