API authentication required
Need API Access?

Please use ‘Create Account’ to quickly register and start exploring our APIs

POST

https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls/connect

This API will connect two numbers. It connects From Number first. Once the person at the From end picks up the phone, it will connect to the number provided as To. You can choose which number should be connected first by adding that number in the From field. An HTTP POST request is made to

Parameter
Name
Value
Description
* From
formData

String; The phone number that will be called first. Preferably in E.164 format. If not set, our system will try to match it with a country and make a call. If landline number, prefix it with STD code; Ex: 080XXXX2400

* To
formData

String; Your customer’s phone number. If landline number, prefix it with STD code; Ex: 080XXXX2400

* CallerId
formData

String; This is your ExoPhone/Exotel Virtual Number (pick one from here)

* CallType
formData

String; trans – for Transactional Calls

* TimeLimit
formData

Integer; The time limit (in seconds) that you want this call to last. The call will be cut after this time

* TimeOut
formData

Integer; The time (in seconds) to ring the called parties (both first and second call leg)

* WaitUrl
formData

String; Play this audio to the caller. When the first leg (From) has to wait for the other leg (To) to pick up the call, the audio file specified in this parameter will be played.

Please refer this article to understand the format specifications of the audio file to be played (wav is only supported).

* Record
formData

Boolean; Record the conversation of your call. The RecordingUrl will be sent to the StatusCallback URL if this is set to ‘true’ and the call conversation happens. Can be:

* RecordingChannels
formData

String; Number of audio channels to be present in the final recording. This parameter works if Record is set to ‘true’.

* CustomField
formData

Any application specific value like order id that will be passed back as a parameter in StatusCallback (only via ‘terminal’ StatusCallbackEvent)

* StatusCallback
formData

String; An HTTP POST request will be made to this URL depending on what events are subscribed using ‘StatusCallbackEvents’. Refer here for complete list of parameters which will be sent to your endpoint.

* StatusCallbackEvents[0]
formData

Array; Call events for which we will send details to the URL as set in ‘StatusCallback’ parameter. Can be:

terminal – This event will be triggered once the call is over.
If no event is specified, we will send the default parameters as specified here. Currently, only ‘terminal’ event is supported but more events could be added in future.

* StatusCallbackEvents[1]
formData

Same as StatusCallbackEvents

* StatusCallbackContentType
formData

String; The HTTP header ‘Content-Type’ using which the StatusCallback webhook will be triggered to your URL. Can be:

Response Content Type

POST

https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls/connect

This API will first call the From number, and once they pick up the phone, it will connect them to a call flow (aka applet) that you have created in the system – like your landing app, or any other app that can play a greeting, have IVR, etc. For more details on setting up your flow, please refer Appplet documentation. An HTTP POST request is made to

Parameter
Name
Value
Description
* From
formData

The phone number that will be called first. Preferably in E.164 format. If not set, our system will try to match it with a country and make a call. If landline number, prefix it with STD code; Ex: 0XXXXXX2400

* CallerId
formData

This is your ExoPhone (pick one from here)

* Url
formData

http://my.exotel.com/{your_sid}/exoml/start_voice/{app_id} where app_id is the identifier of the flow (or applet) that you want to connect to once the From number picks up the call. You can get the app_id from your Exotel Dashboard

* CallType
formData

trans – for Transactional Calls

* TimeLimit
formData

The time limit (in seconds) that you want this call to last. The call will be cut after this time

* TimeOut
formData

The time (in seconds) to ring the called parties (both first and second call leg)

* StatusCallback
formData

When the call completes, an HTTP POST will be made to the provided URL with the following four parameters:

CallSid – an alpha-numeric unique identifier
Status – one of: completed, failed, busy, no-answer
RecordingUrl – link to the call recording (if it exists)
DateUpdated – time when the call state was updated last

* CustomField
formData

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.

Response Content Type

GET

https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls/<CallSid>

Parameter
Name
Value
Description
* CallSid
path

<CallSid> is an alpha-numeric unique identifier generated for all the calls made via Exotel.

Response Content Type

GET

https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls

To get details of calls in bulk (including Status, Price, etc.), you will need to make a HTTP GET request to

Parameter
Name
Value
Description
* Sid
query

string; an alpha-numeric unique identifier of the call

One or multiple Call SIDs which are comma separated. Recommended limit of SIDs which should be passed together is 20 and maximum allowed limit is 100. If DateCreated is not set, it will only check for last 31 days by default. While querying Sid(s) older than 31 days, DateCreated filter needs to be provided.

 

Example:
/Calls?Sid=48d690c837bb0c755a1228dcb6911416,d7d9cefd9773dd746d8f1e029cdb1417
/Calls?Sid=48d690c837bb0c755a1228dcb6911416&DateCreated=gte:2019-01-01 00:00:00;lte:2019-01-31 23:59:59

* DateCreated
query

Date and time at which the Call resource was created in the Exotel system. Supported operators (gte and lte), for more info refer to filter operators section below. You can query call records only up to 6 months old and provide maximum date range of 1 month.

Default if not set: Last 31 days

Example:
/Calls?DateCreated=gte:2019-01-01 00:00:00;lte:2019-01-31 23:59:59

* To
query

Your customer’s phone number. One or multiple To numbers can be provided (in E.164 format) which are comma separated. (max limit: 5)

Example:
/Calls?To=<number-1>
/Calls?To=<number-1>,<number-2>”

* From
query

The phone number that will be called first. One or multiple From numbers can be provided (in E.164 format) which are comma separated. (max limit: 5)

Example:
/Calls?From=<number-1>
/Calls?From=<number-1>,<number-2>,…

* Status
query

Overall call status, which could be one of:

  • queued – The call is ready and waiting in line before going out

  • ringing – The call is currently in-flight

  • in-progress – The call was answered and is currently in progress

  • completed – The call was answered and has ended normally

  • failed – The call could not be completed as dialled, most likely because the phone number was non-existent

  • busy – The caller received a busy signal

  • no-answer – The call ended without being answered

Example:
/Calls?Status=completed
/Calls?Status=failed,no-answer,busy,canceled

* Duration
query

Call duration in seconds. Supported operators (gte, eq and lte), for more info refer to filter operators section below.

Example:
/Calls?Duration=gte:10s;lte:45s
/Calls?Duration=eq:30s

* Price
query

If present, this will be the amount (as per your billing currency) you have been charged for the call. Supported operators (gte, eq and lte), for more info refer to filter operators section below.

Example:
/Calls?Price=gte:0.10;lte:1.0
/Calls?Price=eq:0.300030

* Direction
query
  • inbound

  • outbound-dial – Outbound calls from Exotel dashboard

  • outbound-api – All other Outbound calls (API, campaign etc.)

Example:
/Calls?Direction=inbound
/Calls?Direction=outbound-dial,inbound

* PhoneNumber
query

This represents the Virtual Number (ExoPhone) used for the call. One or multiple PhoneNumber(s) can be provided (in E.164 format) which are comma separated. (max limit: 5)

Example:
/Calls?PhoneNumber=<vn-1>
/Calls?PhoneNumber=<vn-1>,<vn-2>,…

* PageSize
query

This represents number of records visible in one page of the API response. Default: 50, Max: 100

* SortBy
query

This indicates in what order the Call records are sorted in the API response. By default records are sorted by DateCreated in descending order. However, you can override the same in following way for ascending order:

Example:
/Calls?SortBy=DateCreated:asc

* Before
query

Auto generated unique string returned in the PrevPageUri (under Metadata) to be used as query param when at least one record is returned in that page. The value of this field is a cursor which identifies a call record uniquely.

* After
query

Auto generated unique string returned in the NextPageUri (under Metadata) to be used as query param when at least one record is present in that page. The value of this field is a cursor which identifies a call record uniquely.

Response Content Type

GET

https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Numbers/~number~

This API provides the following metadata about a phone number:

Telecom Circle
Telecom Circle Name
Number Type
Whether the number belongs to DND or not

Parameter
Name
Value
Description
* PhoneNumber
path

Phone number for which metadata is needed

Response Content Type