This API will first call the customer, and once they pick up the phone, it will connect them to an app (aka flow) that you have created in the system - like your landing app, or any other app that can play a greeting, have IVR etc.

A HTTP POST request to has to be made

Replace ~exotel_sid~ and ~exotel_token~ with the values you obtain from the Exotel Settings tab of your Exotel portal

The following are the POST parameters:

From Mandatory The customer phone # that will be called first 
In case of of mobile number, prefix the 10 digits with a 0; Ex: 09052161119. 
In case of landline number, prefix it with STD code; Ex: 08030752400
CallerId Mandatory This is your Exotel Number (pick one from the 'Company Numbers' page)
CallType Mandatory "trans" - for Transactional Calls 
"promo" - for Promotional calls No longer supported by Exotel
Url Mandatory ""
where ~appid~ is the identifier of the app (or flow) that you want to connect to once the 'From' number picks up the call
TimeLimit Optional The time limit (in seconds) that you want this call to last. Maximum is 4 hours. The call will be cut after this time. 
TimeOut Optional The time (in seconds) to ring the called parties (both first and second call leg). Maximum is 1 minute (which, we hear is mandated by TRAI)
StatusCallback Optional When the call completes, a HTTP POST will be made to the URL mentioned with the following four parameters (This data will be passed in Message body and as multipart/form-data) : 
CallSid - an alpha-numeric unique identifier 
Status - {completed, failed, busy, no-answer} 
RecordingUrl - link to the call recording (if it exists) 
DateUpdated - time when the call state was updated last
 CustomField  Optional Any application specific value that will be passed back as a parameter while doing a GET request to the URL mentioned in your Passthru Applet  or Greetings Applet .

HTTP Response:

On success, 

  • the HTTP response status code will be 200
  • the HTTP body will contain an XML such as whats given below. The "Sid" is the unique identifier of the call and will be useful to log this for future debuggability purposes.
<?xml version="1.0" encoding="UTF-8"?>
  <DateCreated>2012-08-17 12:31:49</DateCreated>
  <DateUpdated>2012-08-17 12:31:49</DateUpdated>
  <StartTime>2012-08-17 12:31:49</StartTime>
  <EndTime>2012-08-17 12:32:57</EndTime>

On failure:

  • the HTTP response status code will be non 200
  • the HTTP body will contain an XML such as below with the details of why the request failed

    <Message>Invalid Call Parameters: No 'From' specified</Message>

Rate Limit:

This API is rate limited to 200 calls per minute. Once this limit has been crossed, your requests will be rejected with an HTTP 429 'Too Many Requests' code.

Sample PHP Code:

An example PHP code for this is available in Github 

Sample Ruby Code:

Sample code available at Github and Ruby Gem available at

Need a techie for this integration?
Check our Phone a Friend App