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 or port existing short codes to Twilio.

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

ShortCode Properties

Property nameTypePIIDescription
account_sidSID<AC>
Not PII

The SID of the Account that created this ShortCode resource.

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

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

date_createdstring<date-time-rfc-2822>
Not PII

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

date_updatedstring<date-time-rfc-2822>
Not PII

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

friendly_namestring
Not PII

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

short_codestring
Not PII

The short code. e.g., 894546.

sidSID<SC>
Not PII

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

Pattern: ^SC[0-9a-fA-F]{32}$Min length: 34Max length: 34
sms_fallback_methodenum<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_urlstring<uri>
Not PII

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

sms_methodenum<http-method>
Not PII

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

Possible values:
GETPOST
sms_urlstring<uri>
Not PII

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

uristring
Not PII

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

Fetch a ShortCode resource

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

Path parameters

Property nameTypeRequiredPIIDescription
AccountSidSID<AC>required
Not PII

The SID of the Account that created the ShortCode resource(s) to fetch.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
SidSID<SC>required
Not PII

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

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

Fetch a ShortCode

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_18
// Download the helper library from https://www.twilio.com/docs/node/install
_18
const 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
_18
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_18
const authToken = process.env.TWILIO_AUTH_TOKEN;
_18
const client = twilio(accountSid, authToken);
_18
_18
async function fetchShortCode() {
_18
const shortCode = await client
_18
.shortCodes("SCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_18
.fetch();
_18
_18
console.log(shortCode.accountSid);
_18
}
_18
_18
fetchShortCode();

Output

_14
{
_14
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_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": "SCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_14
"sms_fallback_method": "POST",
_14
"sms_fallback_url": null,
_14
"sms_method": "POST",
_14
"sms_url": null,
_14
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes/SCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
_14
}

Read multiple ShortCode resources

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

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

Path parameters

Property nameTypeRequiredPIIDescription
AccountSidSID<AC>required
Not PII

The SID of the Account that created the ShortCode resource(s) to read.

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

Query parameters

Property nameTypeRequiredPIIDescription
FriendlyNamestringOptional
Not PII

The string that identifies the ShortCode resources to read.

ShortCodestringOptional
Not PII

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

PageSizeintegerOptional
Not PII

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

Minimum: 1Maximum: 1000
PageintegerOptional
Not PII

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

Minimum: 0
PageTokenstringOptional
Not PII

The page token. This is provided by the API.

Read: list all Short Codes in your account

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_16
// Download the helper library from https://www.twilio.com/docs/node/install
_16
const 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
_16
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_16
const authToken = process.env.TWILIO_AUTH_TOKEN;
_16
const client = twilio(accountSid, authToken);
_16
_16
async function listShortCode() {
_16
const shortCodes = await client.shortCodes.list({ limit: 20 });
_16
_16
shortCodes.forEach((s) => console.log(s.accountSid));
_16
}
_16
_16
listShortCode();

Output

_29
{
_29
"end": 0,
_29
"first_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes.json?Page=0&PageSize=50",
_29
"last_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes.json?Page=0&PageSize=50",
_29
"next_page_uri": null,
_29
"num_pages": 1,
_29
"page": 0,
_29
"page_size": 50,
_29
"previous_page_uri": null,
_29
"short_codes": [
_29
{
_29
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_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": "SCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_29
"sms_fallback_method": "POST",
_29
"sms_fallback_url": null,
_29
"sms_method": "POST",
_29
"sms_url": null,
_29
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes/SCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
_29
}
_29
],
_29
"start": 0,
_29
"total": 1,
_29
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes.json"
_29
}

Read: list Short Codes with an exact match

Return the set of short codes that match '67898'

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_19
// Download the helper library from https://www.twilio.com/docs/node/install
_19
const 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
_19
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19
const authToken = process.env.TWILIO_AUTH_TOKEN;
_19
const client = twilio(accountSid, authToken);
_19
_19
async function listShortCode() {
_19
const shortCodes = await client.shortCodes.list({
_19
shortCode: "67898",
_19
limit: 20,
_19
});
_19
_19
shortCodes.forEach((s) => console.log(s.accountSid));
_19
}
_19
_19
listShortCode();

Output

_29
{
_29
"end": 0,
_29
"first_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes.json?Page=0&PageSize=50",
_29
"last_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes.json?Page=0&PageSize=50",
_29
"next_page_uri": null,
_29
"num_pages": 1,
_29
"page": 0,
_29
"page_size": 50,
_29
"previous_page_uri": null,
_29
"short_codes": [
_29
{
_29
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_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": "SCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_29
"sms_fallback_method": "POST",
_29
"sms_fallback_url": null,
_29
"sms_method": "POST",
_29
"sms_url": null,
_29
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes/SCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
_29
}
_29
],
_29
"start": 0,
_29
"total": 1,
_29
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes.json"
_29
}

Read: list all Short Codes with a partial match

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

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_19
// Download the helper library from https://www.twilio.com/docs/node/install
_19
const 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
_19
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19
const authToken = process.env.TWILIO_AUTH_TOKEN;
_19
const client = twilio(accountSid, authToken);
_19
_19
async function listShortCode() {
_19
const shortCodes = await client.shortCodes.list({
_19
shortCode: "898",
_19
limit: 20,
_19
});
_19
_19
shortCodes.forEach((s) => console.log(s.accountSid));
_19
}
_19
_19
listShortCode();

Output

_29
{
_29
"end": 0,
_29
"first_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes.json?Page=0&PageSize=50",
_29
"last_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes.json?Page=0&PageSize=50",
_29
"next_page_uri": null,
_29
"num_pages": 1,
_29
"page": 0,
_29
"page_size": 50,
_29
"previous_page_uri": null,
_29
"short_codes": [
_29
{
_29
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_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": "SCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_29
"sms_fallback_method": "POST",
_29
"sms_fallback_url": null,
_29
"sms_method": "POST",
_29
"sms_url": null,
_29
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes/SCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
_29
}
_29
],
_29
"start": 0,
_29
"total": 1,
_29
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes.json"
_29
}

Update a ShortCode resource

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.

Path parameters

Property nameTypeRequiredPIIDescription
AccountSidSID<AC>required
Not PII

The SID of the Account that created the ShortCode resource(s) to update.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
SidSID<SC>required
Not PII

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

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

Request body parameters

Property nameTypeRequiredPIIDescription
FriendlyNamestringOptional
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.

ApiVersionstringOptional
Not PII

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

SmsUrlstring<uri>Optional
Not PII

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

SmsMethodenum<http-method>Optional
Not PII

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

Possible values:
GETPOST
SmsFallbackUrlstring<uri>Optional
Not PII

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

SmsFallbackMethodenum<http-method>Optional
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

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

_18
// Download the helper library from https://www.twilio.com/docs/node/install
_18
const 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
_18
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_18
const authToken = process.env.TWILIO_AUTH_TOKEN;
_18
const client = twilio(accountSid, authToken);
_18
_18
async function updateShortCode() {
_18
const shortCode = await client
_18
.shortCodes("SC6b20cb705c1e8f00210049b20b70fce3")
_18
.update({ smsUrl: "http://demo.twilio.com/docs/sms.xml" });
_18
_18
console.log(shortCode.accountSid);
_18
}
_18
_18
updateShortCode();

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/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes/SCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
_14
}

Rate this page: