SIMs

Learn some of the details around SIMs and how to use them with Gigs API!

The following sections assume you have an API key, your first project and familiarized your self with some basics of the Gigs API. All of this is covered by working through the introduction guide.

pSIM vs eSIM

At this time, the Gigs API supports two types of SIMs: embedded (eSIM) and physical (pSIM). A plan dictates what kind of SIMs it supports. A plan that only supports pSIMs will require you to distribute known SIMs to your users, or install them in your devices prior to shipping them out. A quick call to the plans endpoint can provide these details:

curl --request "GET" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/plans/${PLAN_ID}" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}"

From the above, ${GIGS_PROJECT} and ${PLAN_ID} are unique identifiers for your project and plan respectively. The ${GIGS_TOKEN} is your API key. A successful request will result in the following truncated response:

{
  "object": "plan",
  "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
  "name": "Gigs Global",
  "description": "A data plan you will love! Operates in most countries of the world.",
  "coverage": {
    "object": "coverage",
    "id": "de",
    "name": "Europe",
    "networks": [{"country": "DE", ...}]
  },
  "data": 10000000000,
  "dataUnit": "byte",
  "sms": 100,
  "smsUnit": "message",
  "voice": 30000,
  "voiceUnit": "second",
  "price": {...},
  "provider": "p4",
  "requirements": { "address": "none" },
  "simTypes": ["eSIM", "pSIM"],
  "status": "active",
  "tags": ["smartphone", "travel"],
  "validity": {...}
}

From the above plan we can see that it supports both pSIM and eSIMs in Germany (DE). You will need to have your pSIMs associated to your Gigs project before pairing them with a compatible plan. The SIMs linked to a project can be retrieved via the SIMs endpoint:

curl --request "GET" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/sims" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}"

An example response for requesting all SIMs linked to a specific project:

{
  "object": "list",
  "items": [
    {
      "object": "sim",
      "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
      "type": "pSIM",
      "iccid": "89883070000007537119",
      "provider": "p4",
      "status": "inactive",
      "createdAt": "2021-01-21T19:38:34Z"
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}

eSIMs do not share the same requirement of being associated to a specific project before being used. An eSIM is provisioned on demand via the Gigs API and returned to the caller. You can follow along with our guide on creating a subscription for more details regarding connectivity supplied via eSIMs.

eSIM profile lifecycle

Every eSIM has an eSIM profile: the profile that is downloaded onto the user's device and provides connectivity there. Its status tells you how far along that process the profile is, and you can read it at any time with the retrieve an eSIM profile endpoint.

A profile typically progresses like this:

Do not rely on these state transitions. Not every network provider reports every stage, so a profile can skip one entirely, and the first status you observe is not necessarily the earliest stage in the diagram. Treat any status as a possible starting point, and handle the status you actually receive rather than the step you expect to come next.

The diagram does not include unknown, because it is not a stage that a profile passes through. It means we have no information about the profile yet, and it is listed in the table below alongside the stages.

Events

Instead of polling the endpoint, you can subscribe to events and react to each change as it happens:

A status that is reported again without having changed does not produce a new event.

Bear in mind that these events depend on the device telling the network what happened. If switching a profile off leaves the device without connectivity, com.gigs.eSimProfile.disabled can arrive noticeably later than the change itself, because the device has to regain connectivity first.

Test SIMs

We provide placeholder SIMs which allow you to test various flows in the API. See our testing guide for more information.

Follow our "Create a subscription" guide for more details regarding subscriptions.

If you have any further questions or need any assistance please reach out to support@gigs.com.