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

SettingsUpdates Resource

(warning)

Public Beta

This resource is currently in Public Beta . Some features are not yet implemented and others may be changed before being declared as Generally Available. Beta products are not covered by a Twilio SLA . Learn more about beta product support(link takes you to an external page).

A SettingsUpdate instance represents a single update to the configuration of a single physical SIM or eSIM profile. Settings updates are either applied at the time of manufacturing or via over-the-air updates. Updates to the SIM may include modifying the standard elementary files (EFs) found on all SIMs or resources specific to Super SIM, such as the multi-IMSI applet, that may impact how a SIM behaves.

Pending over-the-air updates that are waiting to for the corresponding SIM to connect, download, and install the update can be read using this resource.

This resource can be found at the following URL:

https://supersim.twilio.com/v1/SettingsUpdates

SettingsUpdate Properties

settingsupdate-properties page anchor
Property nameTypeRequiredDescriptionChild properties
sidSID<OB>

Optional

Not PII

The unique identifier of this Settings Update.

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

Optional

Not PII

The ICCID(link takes you to an external page) associated with the SIM.

sim_sidSID<HS>

Optional

Not PII

The SID of the Super SIM to which this Settings Update was applied.

Pattern: ^HS[0-9a-fA-F]{32}$Min length: 34Max length: 34
statusenum<string>

Optional

Not PII

The Status of this Settings Update. One of scheduled, in-progress, successful or failed.

Possible values:
scheduledin-progresssuccessfulfailed
packagesarray

Optional

Not PII

Array containing the different Settings Packages that will be applied to the SIM after the update completes. Each object within the array indicates the name and the version of the Settings Package that will be on the SIM if the update is successful.

date_completedstring<date-time>

Optional

Not PII

The time, given in ISO 8601(link takes you to an external page) format, when the update successfully completed and the new settings were applied to the SIM.

date_createdstring<date-time>

Optional

Not PII

The date that this Settings Update was created, given in ISO 8601(link takes you to an external page) format.

date_updatedstring<date-time>

Optional

Not PII

The date that this Settings Update was updated, given in ISO 8601(link takes you to an external page) format.

Status values

status-values page anchor

The table below describes the available status values of a SettingsUpdate instance:

StatusDescription
scheduledThe update is waiting for the SIM and has not started.
in-progressThe update is in progress but may require multiple update stages to complete.
successfulThe update is complete and the settings described in the packages array are what is now being used by the SIM.
failedThe update did not complete all stages successfully and the update is no longer being retried.

Packages properties

packages-properties page anchor

An update may add, remove, or update one or more settings packages. Each settings package represents a collection of configuration values that are set on the SIM that influence how it behaves. Some settings packages may override others. For example, all SIMs will have a base-settings package which represents the default settings used by all SIMs. If an additional settings package is loaded onto a SIM, the subset of settings controlled by package will override those set by the base-settings package.

nameThe string identifier of the settings package.
versionThe version of the settings package. SIMs using the same version of a settings package should behave identically. When a change is made to a settings package that alters the behavior, the version of the settings package will be incremented. When comparing two versions of a settings package, a higher version indicates a newer version. The value will be a string. Example: "1.0.0".
more_infoURL of the dedicated docs page for the settings package. Will be null if there is no additional public documentation for the settings package.

Read a list of SettingsUpdates

read-a-list-of-settingsupdates page anchor
GET https://supersim.twilio.com/v1/SettingsUpdates

Query parameters

query-parameters page anchor
Property nameTypeRequiredPIIDescription
Simstring

Optional

Not PII

Filter the Settings Updates by a Super SIM's SID or UniqueName.

Statusenum<string>

Optional

Not PII

Filter the Settings Updates by status. Can be scheduled, in-progress, successful, or failed.

Possible values:
scheduledin-progresssuccessfulfailed
PageSizeinteger

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 a list of SettingsUpdatesLink to code sample: Read a list of SettingsUpdates
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 listSettingsUpdate() {

11
  const settingsUpdates = await client.supersim.v1.settingsUpdates.list({

12
    limit: 20,

13
  });

14


15
  settingsUpdates.forEach((s) => console.log(s.sid));

16
}

17


18
listSettingsUpdate();

Output

1
{

2
  "settings_updates": [

3
    {

4
      "sid": "OBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
      "iccid": "89883070000123456789",

6
      "sim_sid": "HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

7
      "status": "scheduled",

8
      "packages": [

9
        {

10
          "name": "base-settings",

11
          "version": "1.0.0",

12
          "more_info": "https://twilio.com/docs/iot/supersim/settings-packages/base-settings"

13
        }

14
      ],

15
      "date_completed": null,

16
      "date_created": "2015-07-30T20:00:00Z",

17
      "date_updated": "2015-07-30T20:00:00Z"

18
    }

19
  ],

20
  "meta": {

21
    "page": 0,

22
    "page_size": 50,

23
    "first_page_url": "https://supersim.twilio.com/v1/SettingsUpdates?Status=scheduled&Sim=HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0",

24
    "previous_page_url": null,

25
    "url": "https://supersim.twilio.com/v1/SettingsUpdates?Status=scheduled&Sim=HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0",

26
    "next_page_url": null,

27
    "key": "settings_updates"

28
  }

29
}
Read a list of SettingsUpdates for a single SIMLink to code sample: Read a list of SettingsUpdates for a single SIM
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 listSettingsUpdate() {

11
  const settingsUpdates = await client.supersim.v1.settingsUpdates.list({

12
    sim: "HSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

13
    limit: 20,

14
  });

15


16
  settingsUpdates.forEach((s) => console.log(s.sid));

17
}

18


19
listSettingsUpdate();

Output

1
{

2
  "settings_updates": [

3
    {

4
      "sid": "OBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
      "iccid": "89883070000123456789",

6
      "sim_sid": "HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

7
      "status": "successful",

8
      "packages": [

9
        {

10
          "name": "base-settings",

11
          "version": "1.0.0",

12
          "more_info": "https://twilio.com/docs/iot/supersim/settings-packages/base-settings"

13
        }

14
      ],

15
      "date_completed": "2015-07-30T20:00:00Z",

16
      "date_created": "2015-07-30T20:00:00Z",

17
      "date_updated": "2015-07-30T20:00:00Z"

18
    }

19
  ],

20
  "meta": {

21
    "page": 0,

22
    "page_size": 50,

23
    "first_page_url": "https://supersim.twilio.com/v1/SettingsUpdates?Sim=HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0",

24
    "previous_page_url": null,

25
    "url": "https://supersim.twilio.com/v1/SettingsUpdates?Sim=HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0",

26
    "next_page_url": null,

27
    "key": "settings_updates"

28
  }

29
}
Read a list of Pending SettingsUpdatesLink to code sample: Read a list of Pending SettingsUpdates
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 listSettingsUpdate() {

11
  const settingsUpdates = await client.supersim.v1.settingsUpdates.list({

12
    status: "scheduled",

13
    limit: 20,

14
  });

15


16
  settingsUpdates.forEach((s) => console.log(s.status));

17
}

18


19
listSettingsUpdate();

Output

1
{

2
  "settings_updates": [

3
    {

4
      "sid": "OBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
      "iccid": "89883070000123456789",

6
      "sim_sid": "HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

7
      "status": "scheduled",

8
      "packages": [

9
        {

10
          "name": "base-settings",

11
          "version": "1.0.0",

12
          "more_info": "https://twilio.com/docs/iot/supersim/settings-packages/base-settings"

13
        }

14
      ],

15
      "date_completed": null,

16
      "date_created": "2015-07-30T20:00:00Z",

17
      "date_updated": "2015-07-30T20:00:00Z"

18
    }

19
  ],

20
  "meta": {

21
    "page": 0,

22
    "page_size": 50,

23
    "first_page_url": "https://supersim.twilio.com/v1/SettingsUpdates?Status=scheduled&PageSize=50&Page=0",

24
    "previous_page_url": null,

25
    "url": "https://supersim.twilio.com/v1/SettingsUpdates?Status=scheduled&PageSize=50&Page=0",

26
    "next_page_url": null,

27
    "key": "settings_updates"

28
  }

29
}

Determine a SIM's Current Settings

determine-a-sims-current-settings page anchor

You can determine what Settings Packages and their respective versions that are currently installed on a SIM by looking at a SIM's most recent successful Settings Update. Records are returned in reverse chronological order with the most recent Settings Update returned first. Use the SIM's SID or Unique Name and the successful status as filters and the look at the first record. The Settings Packages listed in the record's settings_packages are what your SIM is currently using.

Read the current settings on a SIMLink to code sample: Read the current settings on a SIM
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 listSettingsUpdate() {

11
  const settingsUpdates = await client.supersim.v1.settingsUpdates.list({

12
    sim: "HSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

13
    status: "successful",

14
    limit: 20,

15
  });

16


17
  settingsUpdates.forEach((s) => console.log(s.status));

18
}

19


20
listSettingsUpdate();

Output

1
{

2
  "settings_updates": [

3
    {

4
      "sid": "OBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
      "iccid": "89883070000123456789",

6
      "sim_sid": "HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

7
      "status": "successful",

8
      "packages": [

9
        {

10
          "name": "base-settings",

11
          "version": "1.0.0",

12
          "more_info": "https://twilio.com/docs/iot/supersim/settings-packages/base-settings"

13
        }

14
      ],

15
      "date_completed": "2015-07-30T20:00:00Z",

16
      "date_created": "2015-07-30T20:00:00Z",

17
      "date_updated": "2015-07-30T20:00:00Z"

18
    }

19
  ],

20
  "meta": {

21
    "page": 0,

22
    "page_size": 50,

23
    "first_page_url": "https://supersim.twilio.com/v1/SettingsUpdates?Sim=HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0",

24
    "previous_page_url": null,

25
    "url": "https://supersim.twilio.com/v1/SettingsUpdates?Sim=HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0",

26
    "next_page_url": null,

27
    "key": "settings_updates"

28
  }

29
}

Need some help?

Terms of service
Privacy Policy

Copyright © 2024 Twilio Inc.