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

ShortCode Resource

A short code is a 5 or 6-digit number that can send and receive messages with mobile phones. These high-throughput numbers are perfect for apps that need to send messages to lots of users or need to send time-sensitive messages. You can buy shortcodes from Twilio(link takes you to an external page) or port existing short codes to Twilio(link takes you to an external page).

To send messages from your short code, see the Sending Messages documentation.

ShortCode Properties

shortcode-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 this ShortCode resource.

api_versiontype: string
Not PII

The API version used to start a new TwiML session when an SMS message is sent to this short code.

date_createdtype: string<date-time-rfc-2822>
Not PII

The date and time in GMT that this 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 this resource was last updated, specified in RFC 2822(link takes you to an external page) format.

friendly_nametype: string
Not PII

A string that you assigned to describe this resource. By default, the FriendlyName is the short code.

short_codetype: string
Not PII

The short code. e.g., 894546.

sidtype: SID<SC>
Not PII

The unique string that that we created to identify this ShortCode resource.

sms_fallback_methodtype: enum<http-method>
Not PII

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

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

The URL that we call if 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 the sms_url. Can be: GET or POST.

Possible values:
GETPOST
sms_urltype: string<uri>
Not PII

The URL we call when receiving an incoming SMS message to this short code.

uritype: string
Not PII

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

Fetch a ShortCode resource

fetch-a-shortcode-resource page anchor
GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/SMS/ShortCodes/{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 ShortCode resource(s) to fetch.

Sidtype: SID<SC>
Path ParameterNot PII

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

Fetch a ShortCode

fetch-a-shortcode 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.shortCodes('SCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.fetch()
_10
.then(short_code => console.log(short_code.friendlyName));

Output

_14
{
_14
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_14
"api_version": "2010-04-01",
_14
"date_created": null,
_14
"date_updated": null,
_14
"friendly_name": "API_CLUSTER_TEST_SHORT_CODE",
_14
"short_code": "99990",
_14
"sid": "SCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_14
"sms_fallback_method": "POST",
_14
"sms_fallback_url": null,
_14
"sms_method": "POST",
_14
"sms_url": null,
_14
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/ShortCodes/SCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_14
}

Read multiple ShortCode resources

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

Returns a list of ShortCode resources, each representing a short code within your account. This list includes paging information.

Filter the list Twilio returns

filter-the-list-twilio-returns page anchor

The following query string parameters allow you to limit the list returned.

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 ShortCode resource(s) to read.

FriendlyNametype: string
Query ParameterNot PII

The string that identifies the ShortCode resources to read.

ShortCodetype: string
Query ParameterNot PII

Only show the ShortCode resources that match this pattern. You can specify partial numbers and use '*' as a wildcard for any digit.

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.

Read: list all Short Codes in your account

read-list-all-short-codes-in-your-account 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.shortCodes.list({limit: 20})
_10
.then(shortCodes => shortCodes.forEach(s => console.log(s.sid)));

Output

_29
{
_29
"end": 0,
_29
"first_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/ShortCodes.json?Page=0&PageSize=50",
_29
"last_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/ShortCodes.json?Page=0&PageSize=50",
_29
"next_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/ShortCodes.json?Page=50",
_29
"num_pages": 1,
_29
"page": 0,
_29
"page_size": 50,
_29
"previous_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/ShortCodes.json?Page=0&PageSize=50",
_29
"short_codes": [
_29
{
_29
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_29
"api_version": "2010-04-01",
_29
"date_created": null,
_29
"date_updated": null,
_29
"friendly_name": "API_CLUSTER_TEST_SHORT_CODE",
_29
"short_code": "99990",
_29
"sid": "SCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_29
"sms_fallback_method": "POST",
_29
"sms_fallback_url": null,
_29
"sms_method": "POST",
_29
"sms_url": null,
_29
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/ShortCodes/SCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_29
}
_29
],
_29
"start": 0,
_29
"total": 1,
_29
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/ShortCodes.json"
_29
}

Read: list Short Codes with an exact match

read-list-short-codes-with-an-exact-match page anchor

Return the set of short codes that match '67898'

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.shortCodes.list({shortCode: '67898', limit: 20})
_10
.then(shortCodes => shortCodes.forEach(s => console.log(s.sid)));

Output

_29
{
_29
"end": 0,
_29
"first_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/ShortCodes.json?Page=0&PageSize=50",
_29
"last_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/ShortCodes.json?Page=0&PageSize=50",
_29
"next_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/ShortCodes.json?Page=50",
_29
"num_pages": 1,
_29
"page": 0,
_29
"page_size": 50,
_29
"previous_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/ShortCodes.json?Page=0&PageSize=50",
_29
"short_codes": [
_29
{
_29
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_29
"api_version": "2010-04-01",
_29
"date_created": null,
_29
"date_updated": null,
_29
"friendly_name": "API_CLUSTER_TEST_SHORT_CODE",
_29
"short_code": "99990",
_29
"sid": "SCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_29
"sms_fallback_method": "POST",
_29
"sms_fallback_url": null,
_29
"sms_method": "POST",
_29
"sms_url": null,
_29
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/ShortCodes/SCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_29
}
_29
],
_29
"start": 0,
_29
"total": 1,
_29
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/ShortCodes.json"
_29
}

Read: list all Short Codes with a partial match

read-list-all-short-codes-with-a-partial-match page anchor

Return the set of all phone numbers containing the digits '898'

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.shortCodes.list({shortCode: '898', limit: 20})
_10
.then(shortCodes => shortCodes.forEach(s => console.log(s.sid)));

Output

_29
{
_29
"end": 0,
_29
"first_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/ShortCodes.json?Page=0&PageSize=50",
_29
"last_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/ShortCodes.json?Page=0&PageSize=50",
_29
"next_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/ShortCodes.json?Page=50",
_29
"num_pages": 1,
_29
"page": 0,
_29
"page_size": 50,
_29
"previous_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/ShortCodes.json?Page=0&PageSize=50",
_29
"short_codes": [
_29
{
_29
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_29
"api_version": "2010-04-01",
_29
"date_created": null,
_29
"date_updated": null,
_29
"friendly_name": "API_CLUSTER_TEST_SHORT_CODE",
_29
"short_code": "99990",
_29
"sid": "SCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_29
"sms_fallback_method": "POST",
_29
"sms_fallback_url": null,
_29
"sms_method": "POST",
_29
"sms_url": null,
_29
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/ShortCodes/SCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_29
}
_29
],
_29
"start": 0,
_29
"total": 1,
_29
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/ShortCodes.json"
_29
}

Update a ShortCode resource

update-a-shortcode-resource page anchor
POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/SMS/ShortCodes/{Sid}.json

Tries to update the shortcode's properties. This API call returns the updated resource representation if it is successful. The returned response is identical to that returned 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 ShortCode resource(s) to update.

Sidtype: SID<SC>
Path ParameterNot PII

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

Request body parameters
FriendlyNametype: string
Not PII

A descriptive string that you created to describe this resource. It can be up to 64 characters long. By default, the FriendlyName is the short code.

ApiVersiontype: string
Not PII

The API version to use to start a new TwiML session. Can be: 2010-04-01 or 2008-08-01.

SmsUrltype: string<uri>
Not PII

The URL we should call when receiving an incoming SMS message to this short code.

SmsMethodtype: enum<http-method>
Not PII

The HTTP method we should use when calling the sms_url. Can be: GET or POST.

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

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

SmsFallbackMethodtype: enum<http-method>
Not PII

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

Possible values:
GETPOST

Update: Change a short code parameter

update-change-a-short-code-parameter page anchor

Set the SMS Url on a short code to 'http://demo.twilio.com/docs/sms.xml'

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.shortCodes('SC6b20cb705c1e8f00210049b20b70fce3')
_10
.update({smsUrl: 'http://demo.twilio.com/docs/sms.xml'})
_10
.then(short_code => console.log(short_code.friendlyName));

Output

_14
{
_14
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_14
"api_version": "2010-04-01",
_14
"date_created": null,
_14
"date_updated": null,
_14
"friendly_name": "API_CLUSTER_TEST_SHORT_CODE",
_14
"short_code": "99990",
_14
"sid": "SC6b20cb705c1e8f00210049b20b70fce3",
_14
"sms_fallback_method": "POST",
_14
"sms_fallback_url": null,
_14
"sms_method": "POST",
_14
"sms_url": "http://demo.twilio.com/docs/sms.xml",
_14
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/ShortCodes/SCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_14
}

Rate this page: