Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

The Super SIM API


Twilio IoT's Super SIM API empowers you to manage and deploy massive fleets of IoT devices around the world.

Using this REST API, you can activate and deactivate Super SIMs, control the capabilities of individual Super SIMs or groups of Super SIMs, send machine-to-machine (M2M) messages, and query usage.


The Super SIM API base URL

the-super-sim-api-base-url page anchor

All URLs in the reference documentation use the following base URL:


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

The API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported. All responses are provided in JSON format.

(information)

Info

You don't need to use the .json file extension in API request URIs.


The Super SIM API comprises the following resources:

ResourceDescription
SimAccess individual SIMs
Sim BillingPeriod subresourceAccess Super SIM billing data
UsageRecordAccess Super SIM usage data
eSimProfileAccess Super SIM functionality via eUICCs
FleetOrganize and configure groups of Sim resources
NetworkAccess cellular networks to which Super SIMs can connect
NetworkAccessProfileControl which mobile networks Super SIMs can connect to
NetworkAccessProfile Network subresourceManage NAP-listed cellular networks
SMSCommandExchange machine-to-machine (M2M) messages via SMS
IPCommandTransfer IP/UDP messages between your cloud and your devices

When you create or update resources, you indicate the data that is being added or changed by specifying the appropriate resource property. All resource properties are case-sensitive and written in UpperCamelCase(link takes you to an external page). For example, if you want to change a new Sim's status from new to active and receive an asynchronous notification of the change, you call:


_10
curl https://supersim.twilio.com/v1/Sims/{Sim SID} \
_10
-d 'Status=active' \
_10
-d 'CallbackUrl={Your notification URI}'
_10
-u '{Account_Sid}:{Auth_Token}'

This contrasts with responses from the API, in which properties are referenced using lower_snake_case(link takes you to an external page). For example, getting that same Sim's details will return:


_11
{
_11
"sid": "HSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_11
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_11
"unique_name": "My SIM",
_11
"status": "new",
_11
"fleet_sid": null,
_11
"iccid": "89883070000123456789",
_11
"date_created": "2021-04-01T20:00:00Z",
_11
"date_updated": "2021-04-01T20:00:00Z",
_11
"url": "https://supersim.twilio.com/v1/Sims/HSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_11
}

The API documentation presents the appropriate parameter formatting for the language or tool that you select in the code column.

(information)

Info

If you use one of Twilio's Helper Libraries or SDKs, properties' cases may be different from those outlined above for the base API. The API documentation always shows the correct case for a given library.


HTTPS requests made to the Super SIM API are protected with HTTP Basic authentication(link takes you to an external page). To learn more about how Twilio handles authentication, please refer to our security documentation.

You will use your Twilio Account SID as the username and your Auth Token as the password. For example, using the command line tool curl to get a list of your Sim resources, you would use:


_10
curl https://supersim.twilio.com/v1/Sims \
_10
-u '{Account_Sid}:{Auth_Token}'

You can find your Account SID and Auth Token in the Console(link takes you to an external page).

(information)

Info

To learn more about authentication and interaction with the Twilio REST API, see our documentation for requests to the API and Twilio's response.


Errors are signaled by 4xx and 5xx HTTP response status codes and a JSON response body. The error data is a standard Twilio structure. For example:


_10
{
_10
"code": 20003,
_10
"detail": "Your AccountSid or AuthToken was incorrect.",
_10
"message": "Authentication Error - No credentials provided",
_10
"more_info": "https://www.twilio.com/docs/errors/20003",
_10
"status": 401
_10
}

As you can see, the JSON gives you a human- and machine-readable indication of the nature (the detail key) and cause (message) of the error, and a reference to a more detailed description of the error in Twilio's documentation. The value of code is a Twilio error code, and is referenced again in the more_info URL.

Many errors are generic to platform — the one shown above, for example. However, Super SIM-specific error codes are in the range 83000-83999.

You can see a list of all such codes in the error code documentation and as a JSON file.


Certain operations in the Super SIM API — such as changing a Sim's status — are handled asynchronously. These operations will return an intermediate HTTP response — 202 Accepted — while the requested action completes in the background.

Requests that will be processed asynchronously allow you to specify a callback URL for Twilio to notify when the requested action has completed. A callback is sent to your server as either an HTTP POST or GET, according to your preference. Form parameters or query string parameters sent with the callback request describe the asynchronous outcome. Callback request formats are documented with each of the relevant API resources.

If your initial request completes synchronously, a 200 OK, 201 Created, or 204 No Content response will be returned and you should not expect an asynchronous callback, even if you specified a callback URL.

An event will be posted to your account's Debugger in the Console(link takes you to an external page) with error details if Twilio doesn't receive a success response from your callback URL.


Help integrating the Super SIM API

help-integrating-the-super-sim-api page anchor

Twilio's Super SIM API is a flexible building block which can take you from activating your first Super SIM to managing a fleet of millions of Super SIMs.

While we hope this page gives a good overview of what you can do with the API, we're only scratching the surface of what the Super SIM API can do.

If you need any help integrating the Super SIM API or want to talk about best practices, please get in touch. You can contact Twilio Support through the Console(link takes you to an external page) or Help Center(link takes you to an external page).

We can't wait to see what you build!


Rate this page: