Skip to content Skip to navigation Skip to topbar

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

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

ShortCode Properties

Property nameTypeRequiredDescriptionChild properties

account_sidSID<AC>

Optional

The SID of the Account that created this ShortCode resource.

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

api_versionstring

Optional

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>

Optional

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

date_updatedstring<date-time-rfc-2822>

Optional

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

friendly_namestring

Optional

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

short_codestring

Optional

The short code. e.g., 894546.

sidSID<SC>

Optional

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>

Optional

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

Possible values:

GETPOST

sms_fallback_urlstring<uri>

Optional

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

sms_methodenum<http-method>

Optional

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

Possible values:

GETPOST

sms_urlstring<uri>

Optional

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

uristring

Optional

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

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

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

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchShortCode() {
11  const shortCode = await client
12    .shortCodes("SCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .fetch();
14
15  console.log(shortCode.accountSid);
16}
17
18fetchShortCode();

Output

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "api_version": "2010-04-01",
4  "date_created": null,
5  "date_updated": null,
6  "friendly_name": "API_CLUSTER_TEST_SHORT_CODE",
7  "short_code": "99990",
8  "sid": "SCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
9  "sms_fallback_method": "POST",
10  "sms_fallback_url": null,
11  "sms_method": "POST",
12  "sms_url": null,
13  "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

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

FriendlyNamestring

Optional

The string that identifies the ShortCode resources to read.

ShortCodestring

Optional

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

PageSizeinteger

Optional

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

Minimum: 1Maximum: 1000

Pageinteger

Optional

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

Minimum: 0

PageTokenstring

Optional

The page token. This is provided by the API.

Read: list all Short Codes in your account

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listShortCode() {
11  const shortCodes = await client.shortCodes.list({ limit: 20 });
12
13  shortCodes.forEach((s) => console.log(s.accountSid));
14}
15
16listShortCode();

Output

1{
2  "end": 0,
3  "first_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes.json?Page=0&PageSize=50",
4  "last_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes.json?Page=0&PageSize=50",
5  "next_page_uri": null,
6  "num_pages": 1,
7  "page": 0,
8  "page_size": 50,
9  "previous_page_uri": null,
10  "short_codes": [
11    {
12      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13      "api_version": "2010-04-01",
14      "date_created": null,
15      "date_updated": null,
16      "friendly_name": "API_CLUSTER_TEST_SHORT_CODE",
17      "short_code": "99990",
18      "sid": "SCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
19      "sms_fallback_method": "POST",
20      "sms_fallback_url": null,
21      "sms_method": "POST",
22      "sms_url": null,
23      "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes/SCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
24    }
25  ],
26  "start": 0,
27  "total": 1,
28  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes.json"
29}

Read: list Short Codes with an exact match

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listShortCode() {
11  const shortCodes = await client.shortCodes.list({
12    shortCode: "67898",
13    limit: 20,
14  });
15
16  shortCodes.forEach((s) => console.log(s.accountSid));
17}
18
19listShortCode();

Output

1{
2  "end": 0,
3  "first_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes.json?Page=0&PageSize=50",
4  "last_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes.json?Page=0&PageSize=50",
5  "next_page_uri": null,
6  "num_pages": 1,
7  "page": 0,
8  "page_size": 50,
9  "previous_page_uri": null,
10  "short_codes": [
11    {
12      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13      "api_version": "2010-04-01",
14      "date_created": null,
15      "date_updated": null,
16      "friendly_name": "API_CLUSTER_TEST_SHORT_CODE",
17      "short_code": "99990",
18      "sid": "SCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
19      "sms_fallback_method": "POST",
20      "sms_fallback_url": null,
21      "sms_method": "POST",
22      "sms_url": null,
23      "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes/SCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
24    }
25  ],
26  "start": 0,
27  "total": 1,
28  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes.json"
29}

Read: list all Short Codes with a partial match

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listShortCode() {
11  const shortCodes = await client.shortCodes.list({
12    shortCode: "898",
13    limit: 20,
14  });
15
16  shortCodes.forEach((s) => console.log(s.accountSid));
17}
18
19listShortCode();

Output

1{
2  "end": 0,
3  "first_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes.json?Page=0&PageSize=50",
4  "last_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes.json?Page=0&PageSize=50",
5  "next_page_uri": null,
6  "num_pages": 1,
7  "page": 0,
8  "page_size": 50,
9  "previous_page_uri": null,
10  "short_codes": [
11    {
12      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13      "api_version": "2010-04-01",
14      "date_created": null,
15      "date_updated": null,
16      "friendly_name": "API_CLUSTER_TEST_SHORT_CODE",
17      "short_code": "99990",
18      "sid": "SCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
19      "sms_fallback_method": "POST",
20      "sms_fallback_url": null,
21      "sms_method": "POST",
22      "sms_url": null,
23      "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes/SCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
24    }
25  ],
26  "start": 0,
27  "total": 1,
28  "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 short code'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

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

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

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

SchemaExample

Property nameTypeRequiredDescriptionChild properties

FriendlyNamestring

Optional

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.

ApiVersionstring

Optional

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

SmsUrlstring<uri>

Optional

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

SmsMethodenum<http-method>

Optional

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

Possible values:

GETPOST

SmsFallbackUrlstring<uri>

Optional

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

SmsFallbackMethodenum<http-method>

Optional

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

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateShortCode() {
11  const shortCode = await client
12    .shortCodes("SC6b20cb705c1e8f00210049b20b70fce3")
13    .update({ smsUrl: "http://demo.twilio.com/docs/sms.xml" });
14
15  console.log(shortCode.accountSid);
16}
17
18updateShortCode();

Output

1{
2  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3  "api_version": "2010-04-01",
4  "date_created": null,
5  "date_updated": null,
6  "friendly_name": "API_CLUSTER_TEST_SHORT_CODE",
7  "short_code": "99990",
8  "sid": "SC6b20cb705c1e8f00210049b20b70fce3",
9  "sms_fallback_method": "POST",
10  "sms_fallback_url": null,
11  "sms_method": "POST",
12  "sms_url": "http://demo.twilio.com/docs/sms.xml",
13  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes/SCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
14}