Skip to contentSkip to navigationSkip to topbar
Twilio Docs
Rate this page:
On this page

REST API: Applications

An Application Resource (also referred to as a "TwiML Application" or "TwiML App") represents a collection of endpoints that return TwiML instructions to Twilio. TwiML Applications are most commonly used for the Voice SDKs to handle outbound calls, but can also be used to configure multiple phone numbers with the same set of TwiML endpoints.

The Applications list resource represents the set of an account's Twilio applications. You can POST to the list resource to create a new application. Note that accounts can contain at most 1000 applications.

Applications are useful for encapsulating configuration information that you need to distribute across multiple phone numbers. You can assign an ApplicationSid to an IncomingPhoneNumber to tell Twilio to use the application's URLs instead of the ones set directly on the IncomingPhoneNumber. So if you create an application with its VoiceUrl set to http://myapp.com/answer(link takes you to an external page), you can assign that application to all of your phone numbers and Twilio will make a request to that URL whenever a call comes in.

Application Properties

application-properties page anchor
Resource properties
account_sidtype: SID<AC>
Not PII

The SID of the Account(link takes you to an external page) that created the Application resource.

api_versiontype: string
Not PII

The API version used to start a new TwiML session.

date_createdtype: string<DATE TIME RFC 2822>
Not PII

The date and time in GMT that the resource was created specified in RFC 2822(link takes you to an external page) format.

date_updatedtype: string<DATE TIME RFC 2822>
Not PII

The date and time in GMT that the resource was last updated specified in RFC 2822(link takes you to an external page) format.

friendly_nametype: string
Not PII

The string that you assigned to describe the resource.

message_status_callbacktype: string<URI>
Not PII

The URL we call using a POST method to send message status information to your application.

sidtype: SID<AP>
Not PII

The unique string that that we created to identify the Application resource.

sms_fallback_methodtype: enum<HTTP METHOD>
Not PII

The HTTP method we use to call sms_fallback_url. Can be: GET or POST.

Possible values:
GETPOST
sms_fallback_urltype: string<URI>
Not PII

The URL that we call when an error occurs while retrieving or executing the TwiML from sms_url.

sms_methodtype: enum<HTTP METHOD>
Not PII

The HTTP method we use to call sms_url. Can be: GET or POST.

Possible values:
GETPOST
sms_status_callbacktype: string<URI>
Not PII

The URL we call using a POST method to send status information to your application about SMS messages that refer to the application.

sms_urltype: string<URI>
Not PII

The URL we call when the phone number receives an incoming SMS message.

status_callbacktype: string<URI>
Not PII

The URL we call using the status_callback_method to send status information to your application.

status_callback_methodtype: enum<HTTP METHOD>
Not PII

The HTTP method we use to call status_callback. Can be: GET or POST.

Possible values:
GETPOST
uritype: string
Not PII

The URI of the resource, relative to https://api.twilio.com.

voice_caller_id_lookuptype: boolean
Not PII

Whether we look up the caller's caller-ID name from the CNAM database (additional charges apply). Can be: true or false.

voice_fallback_methodtype: enum<HTTP METHOD>
Not PII

The HTTP method we use to call voice_fallback_url. Can be: GET or POST.

Possible values:
GETPOST
voice_fallback_urltype: string<URI>
Not PII

The URL that we call when an error occurs retrieving or executing the TwiML requested by url.

voice_methodtype: enum<HTTP METHOD>
Not PII

The HTTP method we use to call voice_url. Can be: GET or POST.

Possible values:
GETPOST
voice_urltype: string<URI>
Not PII

The URL we call when the phone number assigned to this application receives a call.

public_application_connect_enabledtype: boolean
Not PII

Whether to allow other Twilio accounts to dial this applicaton using Dial verb. Can be: true or false.

Create an Application resource

create-an-application-resource page anchor
POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Applications.json

Creates a new application within your account.

If successful, Twilio responds with a representation of the new application.

Parameters

create-parameters page anchor
URI parameters
AccountSidtype: SID<AC>
Path ParameterNot PII

The SID of the Account(link takes you to an external page) that will create the resource.

Request body parameters
ApiVersiontype: string
Not PII

The API version to use to start a new TwiML session. Can be: 2010-04-01 or 2008-08-01. The default value is the account's default API version.

VoiceUrltype: string<URI>
Not PII

The URL we should call when the phone number assigned to this application receives a call.

VoiceMethodtype: enum<HTTP METHOD>
Not PII

The HTTP method we should use to call voice_url. Can be: GET or POST.

Possible values:
GETPOST
VoiceFallbackUrltype: string<URI>
Not PII

The URL that we should call when an error occurs retrieving or executing the TwiML requested by url.

VoiceFallbackMethodtype: enum<HTTP METHOD>
Not PII

The HTTP method we should use to call voice_fallback_url. Can be: GET or POST.

Possible values:
GETPOST
StatusCallbacktype: string<URI>
Not PII

The URL we should call using the status_callback_method to send status information to your application.

StatusCallbackMethodtype: enum<HTTP METHOD>
Not PII

The HTTP method we should use to call status_callback. Can be: GET or POST.

Possible values:
GETPOST
VoiceCallerIdLookuptype: boolean
Not PII

Whether we should look up the caller's caller-ID name from the CNAM database (additional charges apply). Can be: true or false.

SmsUrltype: string<URI>
Not PII

The URL we should call when the phone number receives an incoming SMS message.

SmsMethodtype: enum<HTTP METHOD>
Not PII

The HTTP method we should use to call sms_url. Can be: GET or POST.

Possible values:
GETPOST
SmsFallbackUrltype: string<URI>
Not PII

The URL that we should call when an error occurs while retrieving or executing the TwiML from sms_url.

SmsFallbackMethodtype: enum<HTTP METHOD>
Not PII

The HTTP method we should use to call sms_fallback_url. Can be: GET or POST.

Possible values:
GETPOST
SmsStatusCallbacktype: string<URI>
Not PII

The URL we should call using a POST method to send status information about SMS messages sent by the application.

MessageStatusCallbacktype: string<URI>
Not PII

The URL we should call using a POST method to send message status information to your application.

FriendlyNametype: string
Not PII

A descriptive string that you create to describe the new application. It can be up to 64 characters long.

PublicApplicationConnectEnabledtype: boolean
Not PII

Whether to allow other Twilio accounts to dial this applicaton using Dial verb. Can be: true or false.

Create a New Application Within Your Account

create-a-new-application-within-your-account page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_14
// Download the helper library from https://www.twilio.com/docs/node/install
_14
// Find your Account SID and Auth Token at twilio.com/console
_14
// and set the environment variables. See http://twil.io/secure
_14
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14
const authToken = process.env.TWILIO_AUTH_TOKEN;
_14
const client = require('twilio')(accountSid, authToken);
_14
_14
client.applications
_14
.create({
_14
voiceMethod: 'GET',
_14
voiceUrl: 'http://demo.twilio.com/docs/voice.xml',
_14
friendlyName: 'Phone Me'
_14
})
_14
.then(application => console.log(application.sid));

Output

_23
{
_23
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"api_version": "2010-04-01",
_23
"date_created": "Mon, 22 Aug 2011 20:59:45 +0000",
_23
"date_updated": "Tue, 18 Aug 2015 16:48:57 +0000",
_23
"friendly_name": "Phone Me",
_23
"message_status_callback": "http://www.example.com/sms-status-callback",
_23
"sid": "APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"sms_fallback_method": "GET",
_23
"sms_fallback_url": "http://www.example.com/sms-fallback",
_23
"sms_method": "GET",
_23
"sms_status_callback": "http://www.example.com/sms-status-callback",
_23
"sms_url": "http://example.com",
_23
"status_callback": "http://example.com",
_23
"status_callback_method": "GET",
_23
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Applications/APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json",
_23
"voice_caller_id_lookup": false,
_23
"voice_fallback_method": "GET",
_23
"voice_fallback_url": "http://www.example.com/voice-callback",
_23
"voice_method": "GET",
_23
"voice_url": "http://demo.twilio.com/docs/voice.xml",
_23
"public_application_connect_enabled": true
_23
}

Fetch an Application resource

fetch-an-application-resource page anchor
GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Applications/{Sid}.json

Parameters

fetch-parameters page anchor
URI parameters
AccountSidtype: SID<AC>
Path ParameterNot PII

The SID of the Account(link takes you to an external page) that created the Application resource to fetch.

Sidtype: SID<AP>
Path ParameterNot PII

The Twilio-provided string that uniquely identifies the Application resource to fetch.

Fetch an Application

fetch-an-application page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.applications('APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.fetch()
_10
.then(application => console.log(application.friendlyName));

Output

_23
{
_23
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"api_version": "2010-04-01",
_23
"date_created": "Mon, 22 Aug 2011 20:59:45 +0000",
_23
"date_updated": "Tue, 18 Aug 2015 16:48:57 +0000",
_23
"friendly_name": "Application Friendly Name",
_23
"message_status_callback": "http://www.example.com/sms-status-callback",
_23
"sid": "APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"sms_fallback_method": "GET",
_23
"sms_fallback_url": "http://www.example.com/sms-fallback",
_23
"sms_method": "GET",
_23
"sms_status_callback": "http://www.example.com/sms-status-callback",
_23
"sms_url": "http://example.com",
_23
"status_callback": "http://example.com",
_23
"status_callback_method": "GET",
_23
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Applications/APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json",
_23
"voice_caller_id_lookup": false,
_23
"voice_fallback_method": "GET",
_23
"voice_fallback_url": "http://www.example.com/voice-callback",
_23
"voice_method": "GET",
_23
"voice_url": "http://example.com",
_23
"public_application_connect_enabled": false
_23
}

Read multiple Application resources

read-multiple-application-resources page anchor
GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Applications.json

Returns a list of Application resource representations, each representing an application within your account. The list includes paging information.

Parameters

list-parameters page anchor
URI parameters
AccountSidtype: SID<AC>
Path ParameterNot PII

The SID of the Account(link takes you to an external page) that created the Application resources to read.

FriendlyNametype: string
Query ParameterNot PII

The string that identifies the Application resources to read.

PageSizetype: integer
Query ParameterNot PII

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Pagetype: integer
Query ParameterNot PII

The page index. This value is simply for client state.

PageTokentype: string
Query ParameterNot PII

The page token. This is provided by the API.

List All Application Resource Representations

list-all-application-resource-representations page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.applications.list({limit: 20})
_10
.then(applications => applications.forEach(a => console.log(a.sid)));

Output

_35
{
_35
"applications": [
_35
{
_35
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_35
"api_version": "2010-04-01",
_35
"date_created": "Fri, 21 Aug 2015 00:07:25 +0000",
_35
"date_updated": "Fri, 21 Aug 2015 00:07:25 +0000",
_35
"friendly_name": "d8821fb7-4d01-48b2-bdc5-34e46252b90b",
_35
"message_status_callback": null,
_35
"sid": "APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_35
"sms_fallback_method": "POST",
_35
"sms_fallback_url": null,
_35
"sms_method": "POST",
_35
"sms_status_callback": null,
_35
"sms_url": null,
_35
"status_callback": null,
_35
"status_callback_method": "POST",
_35
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Applications/APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json",
_35
"voice_caller_id_lookup": false,
_35
"voice_fallback_method": "POST",
_35
"voice_fallback_url": null,
_35
"voice_method": "POST",
_35
"voice_url": null,
_35
"public_application_connect_enabled": false
_35
}
_35
],
_35
"end": 0,
_35
"first_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Applications.json?PageSize=1&Page=0",
_35
"next_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Applications.json?PageSize=1&Page=1",
_35
"previous_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Applications.json?PageSize=1&Page=0",
_35
"page_size": 1,
_35
"page": 0,
_35
"start": 0,
_35
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Applications.json?PageSize=1&Page=0"
_35
}

Return the Application named 'MyApp'

return-the-application-named-myapp page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.applications.list({friendlyName: 'MyApp', limit: 20})
_10
.then(applications => applications.forEach(a => console.log(a.sid)));

Output

_35
{
_35
"applications": [
_35
{
_35
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_35
"api_version": "2010-04-01",
_35
"date_created": "Fri, 21 Aug 2015 00:07:25 +0000",
_35
"date_updated": "Fri, 21 Aug 2015 00:07:25 +0000",
_35
"friendly_name": "d8821fb7-4d01-48b2-bdc5-34e46252b90b",
_35
"message_status_callback": null,
_35
"sid": "APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_35
"sms_fallback_method": "POST",
_35
"sms_fallback_url": null,
_35
"sms_method": "POST",
_35
"sms_status_callback": null,
_35
"sms_url": null,
_35
"status_callback": null,
_35
"status_callback_method": "POST",
_35
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Applications/APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json",
_35
"voice_caller_id_lookup": false,
_35
"voice_fallback_method": "POST",
_35
"voice_fallback_url": null,
_35
"voice_method": "POST",
_35
"voice_url": null,
_35
"public_application_connect_enabled": false
_35
}
_35
],
_35
"end": 0,
_35
"first_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Applications.json?PageSize=1&Page=0",
_35
"next_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Applications.json?PageSize=1&Page=1",
_35
"previous_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Applications.json?PageSize=1&Page=0",
_35
"page_size": 1,
_35
"page": 0,
_35
"start": 0,
_35
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Applications.json?PageSize=1&Page=0"
_35
}

Update an Application resource

update-an-application-resource page anchor
POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Applications/{Sid}.json

Tries to update the application's properties, and returns the updated resource representation if successful. The returned response is identical to that returned above when making a GET request.

Parameters

update-parameters page anchor
URI parameters
AccountSidtype: SID<AC>
Path ParameterNot PII

The SID of the Account(link takes you to an external page) that created the Application resources to update.

Sidtype: SID<AP>
Path ParameterNot PII

The Twilio-provided string that uniquely identifies the Application resource to update.

Request body parameters
FriendlyNametype: string
Not PII

A descriptive string that you create to describe the resource. It can be up to 64 characters long.

ApiVersiontype: string
Not PII

The API version to use to start a new TwiML session. Can be: 2010-04-01 or 2008-08-01. The default value is your account's default API version.

VoiceUrltype: string<URI>
Not PII

The URL we should call when the phone number assigned to this application receives a call.

VoiceMethodtype: enum<HTTP METHOD>
Not PII

The HTTP method we should use to call voice_url. Can be: GET or POST.

Possible values:
GETPOST
VoiceFallbackUrltype: string<URI>
Not PII

The URL that we should call when an error occurs retrieving or executing the TwiML requested by url.

VoiceFallbackMethodtype: enum<HTTP METHOD>
Not PII

The HTTP method we should use to call voice_fallback_url. Can be: GET or POST.

Possible values:
GETPOST
StatusCallbacktype: string<URI>
Not PII

The URL we should call using the status_callback_method to send status information to your application.

StatusCallbackMethodtype: enum<HTTP METHOD>
Not PII

The HTTP method we should use to call status_callback. Can be: GET or POST.

Possible values:
GETPOST
VoiceCallerIdLookuptype: boolean
Not PII

Whether we should look up the caller's caller-ID name from the CNAM database (additional charges apply). Can be: true or false.

SmsUrltype: string<URI>
Not PII

The URL we should call when the phone number receives an incoming SMS message.

SmsMethodtype: enum<HTTP METHOD>
Not PII

The HTTP method we should use to call sms_url. Can be: GET or POST.

Possible values:
GETPOST
SmsFallbackUrltype: string<URI>
Not PII

The URL that we should call when an error occurs while retrieving or executing the TwiML from sms_url.

SmsFallbackMethodtype: enum<HTTP METHOD>
Not PII

The HTTP method we should use to call sms_fallback_url. Can be: GET or POST.

Possible values:
GETPOST
SmsStatusCallbacktype: string<URI>
Not PII

Same as message_status_callback: The URL we should call using a POST method to send status information about SMS messages sent by the application. Deprecated, included for backwards compatibility.

MessageStatusCallbacktype: string<URI>
Not PII

The URL we should call using a POST method to send message status information to your application.

PublicApplicationConnectEnabledtype: boolean
Not PII

Whether to allow other Twilio accounts to dial this applicaton using Dial verb. Can be: true or false.

Set the VoiceUrl and SmsUrl on an Application to 'http://myapp.com/awesome'

set-the-voiceurl-and-smsurl-on-an-application-to-httpmyappcomawesome page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_13
// Download the helper library from https://www.twilio.com/docs/node/install
_13
// Find your Account SID and Auth Token at twilio.com/console
_13
// and set the environment variables. See http://twil.io/secure
_13
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_13
const authToken = process.env.TWILIO_AUTH_TOKEN;
_13
const client = require('twilio')(accountSid, authToken);
_13
_13
client.applications('AP2a0747eba6abf96b7e3c3ff0b4530f6e')
_13
.update({
_13
smsUrl: 'http://demo.twilio.com/docs/sms.xml',
_13
voiceUrl: 'http://demo.twilio.com/docs/voice.xml'
_13
})
_13
.then(application => console.log(application.friendlyName));

Output

_23
{
_23
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"api_version": "2010-04-01",
_23
"date_created": "Mon, 22 Aug 2011 20:59:45 +0000",
_23
"date_updated": "Tue, 18 Aug 2015 16:48:57 +0000",
_23
"friendly_name": "Application Friendly Name",
_23
"message_status_callback": "http://www.example.com/sms-status-callback",
_23
"sid": "AP2a0747eba6abf96b7e3c3ff0b4530f6e",
_23
"sms_fallback_method": "GET",
_23
"sms_fallback_url": "http://www.example.com/sms-fallback",
_23
"sms_method": "GET",
_23
"sms_status_callback": "http://www.example.com/sms-status-callback",
_23
"sms_url": "http://demo.twilio.com/docs/sms.xml",
_23
"status_callback": "http://example.com",
_23
"status_callback_method": "GET",
_23
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Applications/APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json",
_23
"voice_caller_id_lookup": false,
_23
"voice_fallback_method": "GET",
_23
"voice_fallback_url": "http://www.example.com/voice-callback",
_23
"voice_method": "GET",
_23
"voice_url": "http://demo.twilio.com/docs/voice.xml",
_23
"public_application_connect_enabled": true
_23
}

Delete an Application resource

delete-an-application-resource page anchor
DELETE https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Applications/{Sid}.json

Delete this application. If this application's sid is assigned to any IncomingPhoneNumber resources as a VoiceApplicationSid or SmsApplicationSid it will be removed.

If successful, Twilio will return an HTTP 204 response with no body.

Parameters

delete-parameters page anchor
URI parameters
AccountSidtype: SID<AC>
Path ParameterNot PII

The SID of the Account(link takes you to an external page) that created the Application resources to delete.

Sidtype: SID<AP>
Path ParameterNot PII

The Twilio-provided string that uniquely identifies the Application resource to delete.

Delete an Application

delete-an-application page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.applications('APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX').remove();

Rate this page: