Skip to content Skip to navigation Skip to topbar

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, 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

Property nameTypeRequiredDescriptionChild properties

account_sidSID<AC>Optional

The SID of the Account that created the Application resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

api_versionstringOptional

The API version used to start a new TwiML session.

date_createdstring<date-time-rfc-2822>Optional

The date and time in GMT that the resource was created specified in RFC 2822 format.

date_updatedstring<date-time-rfc-2822>Optional

The date and time in GMT that the resource was last updated specified in RFC 2822 format.

friendly_namestringOptional

The string that you assigned to describe the resource.

message_status_callbackstring<uri>Optional

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

sidSID<AP>Optional

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

Pattern: ^AP[0-9a-fA-F]{32}$Min length: 34Max length: 34

sms_fallback_methodenum<http-method>Optional

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

Possible values:

GETPOST

sms_fallback_urlstring<uri>Optional

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

sms_methodenum<http-method>Optional

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

Possible values:

GETPOST

sms_status_callbackstring<uri>Optional

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

sms_urlstring<uri>Optional

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

status_callbackstring<uri>Optional

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

status_callback_methodenum<http-method>Optional

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

Possible values:

GETPOST

uristringOptional

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

voice_caller_id_lookupbooleanOptional

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

voice_fallback_methodenum<http-method>Optional

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

Possible values:

GETPOST

voice_fallback_urlstring<uri>Optional

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

voice_methodenum<http-method>Optional

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

Possible values:

GETPOST

voice_urlstring<uri>Optional

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

public_application_connect_enabledbooleanOptional

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

Create an Application resource

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.

Path parameters

Property nameTypeRequiredPIIDescription

AccountSidSID<AC>required

The SID of the Account that will create the resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

ApiVersionstringOptional

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.

VoiceUrlstring<uri>Optional

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

VoiceMethodenum<http-method>Optional

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

Possible values:

GETPOST

VoiceFallbackUrlstring<uri>Optional

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

VoiceFallbackMethodenum<http-method>Optional

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

Possible values:

GETPOST

StatusCallbackstring<uri>Optional

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

StatusCallbackMethodenum<http-method>Optional

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

Possible values:

GETPOST

VoiceCallerIdLookupbooleanOptional

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

SmsUrlstring<uri>Optional

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

SmsMethodenum<http-method>Optional

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

Possible values:

GETPOST

SmsFallbackUrlstring<uri>Optional

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

SmsFallbackMethodenum<http-method>Optional

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

Possible values:

GETPOST

SmsStatusCallbackstring<uri>Optional

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

MessageStatusCallbackstring<uri>Optional

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

FriendlyNamestringOptional

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

PublicApplicationConnectEnabledbooleanOptional

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

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

curl


_20// Download the helper library from https://www.twilio.com/docs/node/install
_20const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_20
_20// Find your Account SID and Auth Token at twilio.com/console
_20// and set the environment variables. See http://twil.io/secure
_20const accountSid = process.env.TWILIO_ACCOUNT_SID;
_20const authToken = process.env.TWILIO_AUTH_TOKEN;
_20const client = twilio(accountSid, authToken);
_20
_20async function createApplication() {
_20  const application = await client.applications.create({
_20    friendlyName: "Phone Me",
_20    voiceMethod: "GET",
_20    voiceUrl: "http://demo.twilio.com/docs/voice.xml",
_20  });
_20
_20  console.log(application.accountSid);
_20}
_20
_20createApplication();

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": "APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_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/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Applications/APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.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

GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Applications/{Sid}.json

Path parameters

Property nameTypeRequiredPIIDescription

AccountSidSID<AC>required

The SID of the Account that created the Application resource to fetch.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

SidSID<AP>required

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

Pattern: ^AP[0-9a-fA-F]{32}$Min length: 34Max length: 34

Fetch an Application

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

curl


_18// Download the helper library from https://www.twilio.com/docs/node/install
_18const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_18
_18// Find your Account SID and Auth Token at twilio.com/console
_18// and set the environment variables. See http://twil.io/secure
_18const accountSid = process.env.TWILIO_ACCOUNT_SID;
_18const authToken = process.env.TWILIO_AUTH_TOKEN;
_18const client = twilio(accountSid, authToken);
_18
_18async function fetchApplication() {
_18  const application = await client
_18    .applications("APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
_18    .fetch();
_18
_18  console.log(application.accountSid);
_18}
_18
_18fetchApplication();

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/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Applications/APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.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

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.

Path parameters

Property nameTypeRequiredPIIDescription

AccountSidSID<AC>required

The SID of the Account that created the Application resources to read.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

Query parameters

Property nameTypeRequiredPIIDescription

FriendlyNamestringOptional

The string that identifies the Application resources to read.

PageSizeintegerOptional

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

Minimum: 1Maximum: 1000

PageintegerOptional

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

Minimum: 0

PageTokenstringOptional

The page token. This is provided by the API.

List All Application Resource Representations

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

curl


_16// Download the helper library from https://www.twilio.com/docs/node/install
_16const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_16
_16// Find your Account SID and Auth Token at twilio.com/console
_16// and set the environment variables. See http://twil.io/secure
_16const accountSid = process.env.TWILIO_ACCOUNT_SID;
_16const authToken = process.env.TWILIO_AUTH_TOKEN;
_16const client = twilio(accountSid, authToken);
_16
_16async function listApplication() {
_16  const applications = await client.applications.list({ limit: 20 });
_16
_16  applications.forEach((a) => console.log(a.accountSid));
_16}
_16
_16listApplication();

Output


_35{
_35  "applications": [
_35    {
_35      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_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": "APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_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/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Applications/APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.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/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Applications.json?PageSize=1&Page=0",
_35  "next_page_uri": null,
_35  "previous_page_uri": null,
_35  "page_size": 1,
_35  "page": 0,
_35  "start": 0,
_35  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Applications.json?PageSize=1&Page=0"
_35}

Return the Application named 'MyApp'

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

curl


_19// Download the helper library from https://www.twilio.com/docs/node/install
_19const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_19
_19// Find your Account SID and Auth Token at twilio.com/console
_19// and set the environment variables. See http://twil.io/secure
_19const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19const authToken = process.env.TWILIO_AUTH_TOKEN;
_19const client = twilio(accountSid, authToken);
_19
_19async function listApplication() {
_19  const applications = await client.applications.list({
_19    friendlyName: "MyApp",
_19    limit: 20,
_19  });
_19
_19  applications.forEach((a) => console.log(a.accountSid));
_19}
_19
_19listApplication();

Output


_35{
_35  "applications": [
_35    {
_35      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_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": "APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_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/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Applications/APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.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/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Applications.json?PageSize=1&Page=0",
_35  "next_page_uri": null,
_35  "previous_page_uri": null,
_35  "page_size": 1,
_35  "page": 0,
_35  "start": 0,
_35  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Applications.json?PageSize=1&Page=0"
_35}

Update an Application resource

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.

Path parameters

Property nameTypeRequiredPIIDescription

AccountSidSID<AC>required

The SID of the Account that created the Application resources to update.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

SidSID<AP>required

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

Pattern: ^AP[0-9a-fA-F]{32}$Min length: 34Max length: 34

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

FriendlyNamestringOptional

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

ApiVersionstringOptional

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.

VoiceUrlstring<uri>Optional

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

VoiceMethodenum<http-method>Optional

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

Possible values:

GETPOST

VoiceFallbackUrlstring<uri>Optional

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

VoiceFallbackMethodenum<http-method>Optional

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

Possible values:

GETPOST

StatusCallbackstring<uri>Optional

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

StatusCallbackMethodenum<http-method>Optional

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

Possible values:

GETPOST

VoiceCallerIdLookupbooleanOptional

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

SmsUrlstring<uri>Optional

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

SmsMethodenum<http-method>Optional

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

Possible values:

GETPOST

SmsFallbackUrlstring<uri>Optional

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

SmsFallbackMethodenum<http-method>Optional

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

Possible values:

GETPOST

SmsStatusCallbackstring<uri>Optional

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.

MessageStatusCallbackstring<uri>Optional

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

PublicApplicationConnectEnabledbooleanOptional

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'

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

curl


_21// Download the helper library from https://www.twilio.com/docs/node/install
_21const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_21
_21// Find your Account SID and Auth Token at twilio.com/console
_21// and set the environment variables. See http://twil.io/secure
_21const accountSid = process.env.TWILIO_ACCOUNT_SID;
_21const authToken = process.env.TWILIO_AUTH_TOKEN;
_21const client = twilio(accountSid, authToken);
_21
_21async function updateApplication() {
_21  const application = await client
_21    .applications("AP2a0747eba6abf96b7e3c3ff0b4530f6e")
_21    .update({
_21      smsUrl: "http://demo.twilio.com/docs/sms.xml",
_21      voiceUrl: "http://demo.twilio.com/docs/voice.xml",
_21    });
_21
_21  console.log(application.accountSid);
_21}
_21
_21updateApplication();

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/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Applications/APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.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 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.

Path parameters

Property nameTypeRequiredPIIDescription

AccountSidSID<AC>required

The SID of the Account that created the Application resources to delete.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

SidSID<AP>required

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

Pattern: ^AP[0-9a-fA-F]{32}$Min length: 34Max length: 34

Delete an Application

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

curl


_14// Download the helper library from https://www.twilio.com/docs/node/install
_14const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_14
_14// Find your Account SID and Auth Token at twilio.com/console
_14// and set the environment variables. See http://twil.io/secure
_14const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14const authToken = process.env.TWILIO_AUTH_TOKEN;
_14const client = twilio(accountSid, authToken);
_14
_14async function deleteApplication() {
_14  await client.applications("APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX").remove();
_14}
_14
_14deleteApplication();