Activate Physical SIMs Inside Devices

In this guide we will walk you through activating your user's SIM cards when they arrive with a device that has the physical SIM already inserted. A possible scenario here is that you bought Gigs SIM cards for devices that you sell and inserted them into the devices during the packaging process.

That's great user experience because now your users just have to unpack the device and provide you with the device's IMEI in order to activate the SIM card in an instant.

The workflow

Once the user opens up their new device, they will only need to provide you with the device's IMEI number, usually easily found on the device's backside or inside its general settings.

Once you have a device's IMEI you need to go through the following steps inside the Gigs API to activate the SIM card:

1. Find user's device
2. Place an order

Respectively, you'll need to do a series of requests.

1. Find user's device

To find a user's device, the device must be present in the database. Read here to add your devices to the Gigs API.

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

This search endpoint is a POST endpoint because it potentially requires personal identifiable search parameter information (namely the IMEI). Passing it via the message body makes is less likely to be exposed to third parties, e.g. in higher-level log records.

You should receive a JSON response resembling this:

{
  "object": "device",
  "id": "dev_0SNlurA049MEWV55CrA9qMvI2FVJ",
  "imei": "123456789012435",
  "model": {
    "object": "deviceModel",
    "id": "dmd_0SNlurA04OUskUGfGAn3Rh",
    "brand": "Apple",
    "name": "iPhone 13 Pro",
    "simTypes": ["pSIM", "eSIM"],
    "type": "smartphone"
  },
  "name": null,
  "sims": [
    {
      "object": "sim",
      "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
      "type": "pSIM",
      "iccid": "89014104271234567890",
      "provider": "p4",
      "status": "active",
      "createdAt": "2021-10-07T14:59:00Z"
    }
  ],
  "user": null,
  "createdAt": "2022-01-22T20:38:31Z"
}

Please take a note of the SIM ID (response.sims[0].id).

2. Place an order

By placing an order you activate the SIM card so that it becomes active and usable by the end-user.

Let's look at a sample order request POST body:

{
  "paymentMethod": "${PAYMENT_METHOD_ID}",
  "plan": "${PLAN_ID}",
  "subscriptionDetails": {
    "sim": "${SIM_ID}",
    "user": "${USER_ID}"
  }
}

Respectively, you'll need to...

1. Provide a ${PLAN_ID} (You should have plans pre-configured and retrievable via the GET /projects/${GIGS_PROJECT}/plans endpoint)
2. Provide a ${PAYMENT_METHOD_ID} (You can retrieve, create, update, and delete payment methods via the respective /projects/${GIGS_PROJECT}/paymentMethods endpoints)
3. Provide a ${SIM_ID}
4. Provide a ${USER_ID}

Equipped with that, we can now fire up a real order request:

curl --request POST \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/orders" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "paymentMethod": "pm_1JLOrDI2m82Dc6Ynl4iRd1sy",
    "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
    "subscriptionDetails": [
      {
        "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
        "sim": "sim_0SNlurA049MEWV1BAAmWZULA4lf6"
      }
    ]
  }'

The response will contain all the details about your order, including the subscription created for the SIM card:

{
  "object": "order",
  "id": "ord_0SNlurA049MEWV0SiRFOw0dmChqN",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  // [... more properties ...]
}

As you can see, when the user scans a device's IMEI, it's just a matter of a few requests to find the device, get its mapped SIM card and then place an order to finally activate the SIM card.

Once the SIM card is activated, the end user is able to use it.

Import devices

You can send the device details (i.e. brand name and model name) and a CSV table of an ICCID to IMEI mapping table to Gigs.