Skip to contentSkip to navigationSkip to topbar
Twilio Docs
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(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
Property nameTypeRequiredDescriptionChild properties
accountSidSID<AC>

Optional

Not PII

The SID of the Account that created this ShortCode resource.

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

Optional

Not PII

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

dateCreatedstring<date-time-rfc-2822>

Optional

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.

dateUpdatedstring<date-time-rfc-2822>

Optional

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.

friendlyNamestring

Optional

Not PII

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

shortCodestring

Optional

Not PII

The short code. e.g., 894546.

sidSID<SC>

Optional

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
smsFallbackMethodenum<http-method>

Optional

Not PII

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

Possible values:
GETPOST
smsFallbackUrlstring<uri>

Optional

Not PII

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

smsMethodenum<http-method>

Optional

Not PII

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

Possible values:
GETPOST
smsUrlstring<uri>

Optional

Not PII

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

uristring

Optional

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

Path parameters

path-parameters page anchor
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 ShortCodeLink to code sample: Fetch a ShortCode
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const 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

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function fetchShortCode() {

11
  const shortCode = await client

12
    .shortCodes("SCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .fetch();

14


15
  console.log(shortCode.accountSid);

16
}

17


18
fetchShortCode();

Response

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

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.

Path parameters

path-parameters-1 page anchor
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

query-parameters page anchor
Property nameTypeRequiredPIIDescription
friendlyNamestring

Optional

Not PII

The string that identifies the ShortCode resources to read.

shortCodestring

Optional

Not PII

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

pageSizeinteger<int64>

Optional

Not PII

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

Minimum: 1Maximum: 1000
pageinteger

Optional

Not PII

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

Minimum: 0
pageTokenstring

Optional

Not PII

The page token. This is provided by the API.

Read: list all Short Codes in your accountLink to code sample: Read: list all Short Codes in your account
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const 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

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function listShortCode() {

11
  const shortCodes = await client.shortCodes.list({ limit: 20 });

12


13
  shortCodes.forEach((s) => console.log(s.accountSid));

14
}

15


16
listShortCode();

Response

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 matchLink to code sample: Read: list Short Codes with an exact match
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const 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

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async 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


19
listShortCode();

Response

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 matchLink to code sample: Read: list all Short Codes with a partial match
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const 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

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async 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


19
listShortCode();

Response

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

update-a-shortcode-resource page anchor

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

path-parameters-2 page anchor
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

request-body-parameters page anchor
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
friendlyNamestring

Optional

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.

apiVersionstring

Optional

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 parameterLink to code sample: Update: Change a short code parameter
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const 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

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async 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


18
updateShortCode();

Response

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
}