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 quickstart 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 Gigs Core API getting started guide for more details regarding connectivity supplied via eSIMs.

Test SIMs

Test SIMs can be used for testing purposes or to get you going with the Gigs API while you are waiting on real SIMs to be made available to you. These SIMs use the "test" provider and behave like any other API SIM resource, but don't provide actual connectivity.

The Gigs API supports both embedded and physical SIMs for testing purposes. To make use of a test SIM, insert one of the below placeholder SIM IDs in a supported create request:

The following Gigs API endpoints support the use of placeholder test SIMs:

• Create a subscription
• Create an order
• Create a device
• Update a device
• Search for SIMs

A new test SIM instance will automatically be created when you define a resource using one of the above supported endpoints with a special placeholder SIM ID such as: sim_test_psim. This new test SIM instance will be generated with a unique resource ID as well as an unique ICCID, starting with 8942424242 followed by 10 characters, for example: "iccid": "89424242428486763002".

The resultant test SIM will be associated to the newly created user's subscription or order. For example, the request to create a new subscription with a test pSIM (using placeholder SIM ID: sim_test_psim) is:

$ curl --request POST \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptions" \
--header "Accept: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}" \
--header "Content-Type: application/json" \
--data '{
  "plan": "...",
  "sim": "sim_test_psim"
  "user": "...",
}'

This will result in a response similar to:

{
  "object": "subscription",
  "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "currentPeriod": {...},
  "phoneNumber": "+25411865216434",
  "plan": {...},
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV3clHBExvxoU22R",
    "type": "pSIM",
    "iccid": "89424242428486763002",
    "provider": "test",
    "status": "inactive",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "status": "pending",
  "user": {...},
  ...
}

In this response, a new test physical SIM resource is created with an unique id and iccid.

To find the placeholder SIMs, you can by search for them using the SIM search endpoint with their ICCIDs, for example looking up the placeholder eSIM - 89424242420000037469:

$ curl --request "POST" \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/sims/search" \
--header "Accept: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}" \
--header "Content-Type: application/json" \
--data '{"iccid": "89424242420000037469"}'

The response provides the details of the placeholder eSIM:

{
  "object": "list",
  "items": [
    {
      "object": "sim",
      "id": "sim_test_esim",
      "iccid": "89424242420000037469",
      "provider": "test",
      "status": "inactive",
      "type": "eSIM",
      "createdAt": "2021-01-01T00:00:00Z"
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}

Follow our "Getting Started" guide for more details regarding subscriptions.

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