# SettingsUpdates Resource 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](https://docs.korewireless.com/en-us/supersim/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](https://docs.korewireless.com/en-us/supersim/supersim-multi-imsi-applet), that may impact how a SIM behaves. Pending over-the-air updates that are waiting for the corresponding SIM to connect, to be download, and to be installed can be read using this resource. This resource can be found at the following URL: ```url https://supersim.api.korewireless.com/v1/SettingsUpdates ``` *** ## Status values The table below describes the available `status` values of a SettingsUpdate instance: | **Status** | **Description** | | ------------- | ---------------------------------------------------------------------------------------------------------------- | | `scheduled` | The update is waiting for the SIM and has not started. | | `in-progress` | The update is in progress but may require multiple update stages to complete. | | `successful` | The update is complete and the settings described in the `packages` array are what is now being used by the SIM. | | `failed` | The update did not complete all stages successfully and the update is no longer being retried. | ## Packages properties 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 and 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 the additional package will override those set by the `base-settings` package. | `name` | The string identifier of the settings package. | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `version` | The 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_info` | URL of the dedicated docs page for the settings package. Will be `null` if there is no additional public documentation. | ## API Authorization Before you can make requests to this resource, you must have a valid bearer token. Review our API [authorization guide](https://docs.korewireless.com/en-us/developers/api-management/auth) to learn how to generate a token. Here's a curl example on how to define your access token in a header: {% code overflow="wrap" %} ```bash curl -L "https://supersim.api.korewireless.com/v1/Sims" -H "Authorization: Bearer " ``` {% endcode %} {% hint style="warning" %} The examples below do not show the required `Authorization` header due to a bug. We're working on fixing that. In the meantime, be sure to include that in all of your requests. {% endhint %} *** ## Read a list of SettingsUpdates ## GET /v1/SettingsUpdates > Retrieve a list of Settings Updates. ```json {"openapi":"3.0.1","info":{"title":"KORE - Supersim","version":"1.0.0"},"tags":[{"name":"SupersimV1SettingsUpdate"}],"servers":[{"url":"https://supersim.api.korewireless.com"}],"security":[{"OAuth":[]}],"components":{"securitySchemes":{"OAuth":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.korewireless.com/api-services/v1/auth/token","scopes":{}}}}},"schemas":{"settings_update_enum_status":{"type":"string","nullable":true,"description":"The Status of this Settings Update. One of `scheduled`, `in-progress`, `successful` or `failed`.","enum":["scheduled","in-progress","successful","failed"]},"supersim.v1.settings_update":{"type":"object","properties":{"sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^OB[0-9a-fA-F]{32}$","nullable":true,"description":"The unique identifier of this Settings Update."},"iccid":{"type":"string","nullable":true,"description":"The [ICCID](https://en.wikipedia.org/wiki/SIM_card#ICCID) associated with the SIM."},"sim_sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^HS[0-9a-fA-F]{32}$","nullable":true,"description":"The SID of the Super SIM to which this Settings Update was applied."},"status":{"$ref":"#/components/schemas/settings_update_enum_status"},"packages":{"type":"array","items":{},"nullable":true,"description":"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_completed":{"type":"string","format":"date-time","nullable":true,"description":"The time, given in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, when the update successfully completed and the new settings were applied to the SIM."},"date_created":{"type":"string","format":"date-time","nullable":true,"description":"The date that this Settings Update was created, given in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format."},"date_updated":{"type":"string","format":"date-time","nullable":true,"description":"The date that this Settings Update was updated, given in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format."}}}}},"paths":{"/v1/SettingsUpdates":{"get":{"description":"Retrieve a list of Settings Updates.","tags":["SupersimV1SettingsUpdate"],"parameters":[{"name":"Sim","in":"query","description":"Filter the Settings Updates by a Super SIM's SID or UniqueName.","schema":{"type":"string"}},{"name":"Status","in":"query","description":"Filter the Settings Updates by status. Can be `scheduled`, `in-progress`, `successful`, or `failed`.","schema":{"$ref":"#/components/schemas/settings_update_enum_status"}},{"name":"PageSize","in":"query","description":"How many resources to return in each list page. The default is 50, and the maximum is 1000.","schema":{"type":"integer","minimum":1,"maximum":1000}},{"name":"Page","in":"query","description":"The page index. This value is simply for client state.","schema":{"type":"integer","minimum":0}},{"name":"PageToken","in":"query","description":"The page token. This is provided by the API.","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"settings_updates":{"type":"array","items":{"$ref":"#/components/schemas/supersim.v1.settings_update"}},"meta":{"properties":{"first_page_url":{"format":"uri","type":"string"},"key":{"type":"string"},"next_page_url":{"format":"uri","nullable":true,"type":"string"},"page":{"type":"integer"},"page_size":{"type":"integer"},"previous_page_url":{"format":"uri","nullable":true,"type":"string"},"url":{"format":"uri","type":"string"}},"type":"object"}},"title":"ListSettingsUpdateResponse"}}},"headers":{"Access-Control-Allow-Origin":{"description":"Specify the origin(s) allowed to access the resource","schema":{"type":"string"}},"Access-Control-Allow-Methods":{"description":"Specify the HTTP methods allowed when accessing the resource","schema":{"type":"string"}},"Access-Control-Allow-Headers":{"description":"Specify the headers allowed when accessing the resource","schema":{"type":"string"}},"Access-Control-Allow-Credentials":{"description":"Indicates whether the browser should include credentials","schema":{"type":"boolean"}},"Access-Control-Expose-Headers":{"description":"Headers exposed to the client","schema":{"type":"string"}}},"description":"OK"}},"operationId":"ListSettingsUpdate"}}}} ``` ## Determine a SIM's Current Settings 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. ### More Request Examples #### Read a list of SettingsUpdates for a single SIM To view the history of updates for an individual SIM, provide it's `sid` or `unique_name` in the request `Sim` query parameter. {% tabs %} {% tab title="Request" %} {% code overflow="wrap" %} ```sh curl -X GET "https://supersim.api.korewireless.com/v1/SettingsUpdates?Sim=HSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&PageSize=20" -H "Authorization: Bearer " ``` {% endcode %} {% endtab %} {% tab title="Response" %} {% code overflow="wrap" %} ```json { "meta": { "page": 0, "page_size": 20, "first_page_url": "https://supersim.api.korewireless.com/v1/SettingsUpdates?Sim=HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&Page=0&PageSize=20", "previous_page_url": null, "url": "https://supersim.api.korewireless.com/v1/SettingsUpdates?Sim=HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&Page=0&PageSize=20", "key": "settings_updates", "next_page_url": null }, "settings_updates": [ { "sid": "OBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "iccid": "89nnnnnnnnnnnnnnnnnn", "status": "successful", "date_created": "2024-04-05T07:09:49Z", "date_updated": "2024-04-05T07:09:49Z", "sim_sid": "HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "packages": [ { "name": "base-settings", "version": "2.3.0", "more_info": null } ], "date_completed": "2024-04-05T07:09:49Z" } ] } ``` {% endcode %} {% endtab %} {% endtabs %} #### Read a list of Pending SettingsUpdates When an over-the-air update is enqueued for your SIM, a SettingsUpdate resource is created with `status=scheduled`. To see what updates are waiting for your SIMs (and which SIMs aren't fully up to date) , you can filter for this `status`. Additionally, some updates can also require multiple check-ins to our over-the-air update services to complete. Those that have received part of the update but still need additional check-ins to finish it will have a status of `in-progress`. {% tabs %} {% tab title="Request" %} {% code overflow="wrap" %} ```bash curl -X GET "https://supersim.api.korewireless.com/v1/SettingsUpdates?Status=scheduled&PageSize=20" -H "Authorization: Bearer " ``` {% endcode %} {% endtab %} {% tab title="Response" %} ```json { "settings_updates": [ { "sid": "OBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "iccid": "89883070000123456789", "sim_sid": "HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "status": "scheduled", "packages": [ { "name": "base-settings", "version": "1.0.0", "more_info": null } ], "date_completed": null, "date_created": "2015-07-30T20:00:00Z", "date_updated": "2015-07-30T20:00:00Z" } ], "meta": { "page": 0, "page_size": 50, "first_page_url": "https://supersim.api.korewireless.com/v1/SettingsUpdates?Status=scheduled&PageSize=50&Page=0", "previous_page_url": null, "url": "https://supersim.ape.korewireless.com/v1/SettingsUpdates?Status=scheduled&PageSize=50&Page=0", "next_page_url": null, "key": "settings_updates" } } ``` {% endtab %} {% endtabs %} #### Read the current settings on a SIM Each SettingsUpdates resource shows the complete list of settings packages to be installed on the SIM. To see what is currently installed on your SIM, look at the most recent resource where `status=successful`. Results are returned in reverse chronological order so the most recent resource will be returned first. Grab the first record in your results or set `PageSize=1`. {% tabs %} {% tab title="Request" %} {% code overflow="wrap" %} ```sh curl -X GET "https://supersim.api.korewireless.com/v1/SettingsUpdates?Sim=HSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXStatus=successful&PageSize=1" -H "Authorization: Bearer " ``` {% endcode %} {% endtab %} {% tab title="Response" %} ```json { "settings_updates": [ { "sid": "OBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "iccid": "89883070000123456789", "sim_sid": "HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "status": "successful", "packages": [ { "name": "base-settings", "version": "1.0.0", "more_info": null } ], "date_completed": "2015-07-30T20:00:00Z", "date_created": "2015-07-30T20:00:00Z", "date_updated": "2015-07-30T20:00:00Z" } ], "meta": { "page": 0, "page_size": 50, "first_page_url": "https://supersim.api.korewireless.com/v1/SettingsUpdates?Sim=HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0", "previous_page_url": null, "url": "https://supersim.api.korewireless.com/v1/SettingsUpdates?Sim=HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0", "next_page_url": null, "key": "settings_updates" } } ``` {% endtab %} {% endtabs %}