SIMs

The SIM resource

A SIM is a unique card that identifies itself to a specific mobile network and provides voice, text, and data connectivity to a user’s device. There are two types of available SIMs: eSIM and pSIM. eSIMs can be activated and installed instantly on any eSIM compatible device, pSIMs (physical SIMs) must be provided to the user or installed into the device beforehand.

Properties

Name
object
Type
string
Description
Type of object is always sim.
Allowed values: sim
Name
id
Type
string
Description
Unique identifier for the SIM.
Example: "sim_0SNlurA049MEWV1BAAmWZULA4lf6"
Name
metadata
Type
Metadata
Description
A set of key-value pairs, to store metadata related to the resource.
Name
createdAt
Type
string
Description
Time when the SIM was created.
Example: "2021-01-21T19:38:34Z"
Name
iccid
Type
string
Description
The ICCID (integrated circuit card identifier) associated with the SIM.
Example: "89883070000007537119"
Name
provider
Type
string
Description
The ID of the network provider of the SIM.
Example: "p9"
Name
status
Type
string
Description
The status of the SIM. Can be active or inactive.
Allowed values: inactive, active, retired
Name
type
Type
string
Description
The type of the SIM. Can be eSIM or pSIM.
Allowed values: eSIM, pSIM

Response

{
  "object": "sim",
  "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
  "createdAt": "2021-01-21T19:38:34Z",
  "iccid": "89883070000007537119",
  "provider": "p9",
  "status": "inactive",
  "type": "eSIM"
}

GET/projects/{project}/sims/{sim}/eSimProfile

Retrieve an eSIM profile

Retrieves the details of an existing eSIM profile for a given SIM.

A 404 response will be returned if the SIM does not exist, or is a pSIM.

Note that for providers other than p3, p14 or p15 the status of the profile will currently always be unknown.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
sim
Type
string
required
Description
The unique identifier for the SIM.
Example: "sim_0SNlurA049MEWV1BAAmWZULA4lf6"

Response Schemas

Returns the eSimProfile if it exists.

Name
object
Type
string
required
Description
Type of object is always eSimProfile.
Allowed values: eSimProfile
Name
sim
Type
Sim
required
Description
A SIM is a unique card that identifies itself to a specific mobile network and provides voice, text, and data connectivity to a user’s device. There are two types of available SIMs: eSIM and pSIM. eSIMs can be activated and installed instantly on any eSIM compatible device, pSIMs (physical SIMs) must be provided to the user or installed into the device beforehand.
Name
status
Type
string
required
Description
The current status of the eSimProfile.
Allowed values: deleted, disabled, enabled, installed, unknown
Name
updatedAt
Type
string
required
Description
Time at which the status was last updated.
Example: "2024-03-13T15:36:01Z"

Request

GET

/projects/{project}/sims/{sim}/eSimProfile

curl https://api.gigs.com/projects/{project}/sims/{sim}/eSimProfile \
-X GET \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

{
  "object": "eSimProfile",
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "metadata": {},
    "createdAt": "2021-01-21T19:38:34Z",
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "inactive",
    "type": "eSIM"
  },
  "status": "deleted",
  "updatedAt": "2024-03-13T15:36:01Z"
}

GET/projects/{project}/sims/{sim}/credentials

Retrieve the SIM credentials

Retrieve the credentials of an existing SIM.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
sim
Type
string
required
Description
The unique identifier for the SIM.
Example: "sim_0SNlurA049MEWV1BAAmWZULA4lf6"

Response Schemas

Returns the SIM credentials.

Name
object
Type
string
required
Description
Type of object is always simCredentials.
Allowed values: simCredentials
Name
activationCode
Type
nullable string
required
Description
eSIM activation code to download and install the profile in a device. Only available for type eSIM.
Example: "LPA:1$smdp.gigs.com$2M-3L0MX-F8HE2"
Name
qrCodeUrl
Type
nullable string
required
Description
URL of the activation code in QR-Code format. Only available for type eSIM.

Be careful how you share this URL, it can be accessed publicly without authentication.

Example: "https://files.gigs.com/qrcode/example/pUNIvfeLBNQ.png"
Name
sim
Type
string
required
Description
Unique identifier for the SIM this credentials are for.
Example: "sim_0SNlurA049MEWV1BAAmWZULA4lf6"

Request

GET

/projects/{project}/sims/{sim}/credentials

curl https://api.gigs.com/projects/{project}/sims/{sim}/credentials \
-X GET \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

{
  "object": "simCredentials",
  "activationCode": "LPA:1$smdp.gigs.com$2M-3L0MX-F8HE2",
  "qrCodeUrl": "https://files.gigs.com/qrcode/example/pUNIvfeLBNQ.png",
  "sim": "sim_0SNlurA049MEWV1BAAmWZULA4lf6"
}

GET/projects/{project}/sims/{sim}

Retrieve a SIM

Retrieve the details of an existing SIM which the authenticated user is authorized to view.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
sim
Type
string
required
Description
The unique identifier for the SIM.
Example: "sim_0SNlurA049MEWV1BAAmWZULA4lf6"

Response Schemas

Returns the SIM if it exists.

Name
object
Type
string
required
Description
Type of object is always sim.
Allowed values: sim
Name
id
Type
string
required
Description
Unique identifier for the SIM.
Example: "sim_0SNlurA049MEWV1BAAmWZULA4lf6"
Name
metadata
Type
Metadata
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
createdAt
Type
string
required
Description
Time when the SIM was created.
Example: "2021-01-21T19:38:34Z"
Name
iccid
Type
string
required
Description
The ICCID (integrated circuit card identifier) associated with the SIM.
Example: "89883070000007537119"
Name
provider
Type
string
required
Description
The ID of the network provider of the SIM.
Example: "p9"
Name
status
Type
string
required
Description
The status of the SIM. Can be active or inactive.
Allowed values: inactive, active, retired
Name
type
Type
string
required
Description
The type of the SIM. Can be eSIM or pSIM.
Allowed values: eSIM, pSIM

Request

GET

/projects/{project}/sims/{sim}

curl https://api.gigs.com/projects/{project}/sims/{sim} \
-X GET \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

{
  "object": "sim",
  "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
  "metadata": {},
  "createdAt": "2021-01-21T19:38:34Z",
  "iccid": "89883070000007537119",
  "provider": "p9",
  "status": "inactive",
  "type": "eSIM"
}

PATCH/projects/{project}/sims/{sim}

Update a SIM

Update the details of an existing SIM.

Body

Name
metadata
Type
Metadata
Description
A set of key-value pairs, to store metadata related to the resource.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
sim
Type
string
required
Description
The unique identifier for the SIM.
Example: "sim_0SNlurA049MEWV1BAAmWZULA4lf6"

Response Schemas

Returns the updates SIM.

Name
object
Type
string
required
Description
Type of object is always sim.
Allowed values: sim
Name
id
Type
string
required
Description
Unique identifier for the SIM.
Example: "sim_0SNlurA049MEWV1BAAmWZULA4lf6"
Name
metadata
Type
Metadata
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
createdAt
Type
string
required
Description
Time when the SIM was created.
Example: "2021-01-21T19:38:34Z"
Name
iccid
Type
string
required
Description
The ICCID (integrated circuit card identifier) associated with the SIM.
Example: "89883070000007537119"
Name
provider
Type
string
required
Description
The ID of the network provider of the SIM.
Example: "p9"
Name
status
Type
string
required
Description
The status of the SIM. Can be active or inactive.
Allowed values: inactive, active, retired
Name
type
Type
string
required
Description
The type of the SIM. Can be eSIM or pSIM.
Allowed values: eSIM, pSIM

Request

PATCH

/projects/{project}/sims/{sim}

curl https://api.gigs.com/projects/{project}/sims/{sim} \
-X PATCH \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{\"metadata\":{}}"

Response

{
  "object": "sim",
  "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
  "metadata": {},
  "createdAt": "2021-01-21T19:38:34Z",
  "iccid": "89883070000007537119",
  "provider": "p9",
  "status": "inactive",
  "type": "eSIM"
}

POST/projects/{project}/sims/search

Search for SIMs

Searches for existing SIMs matching the given parameters.

Body

Name
iccid
Type
string
required
Description
The ICCID (integrated circuit card identifier) associated with the SIM.
Example: "89883070000007537119"
Name
type
Type
nullable array
Description
Optional type of the SIM card, either eSIM, pSIM or both.
Default: eSIM,pSIM

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"

Response Schemas

Returns a list schema response with all found SIMs.

Name
object
Type
string
required
Description
Type of object is always list.
Allowed values: list
Name
items
Type
array
required
Description
List of objects of type `sim`.
Name
moreItemsAfter
Type
nullable string
required
Description
A unique identifier to be used as after pagination parameter if more items are available sorted after the current batch of items.
Name
moreItemsBefore
Type
nullable string
required
Description
A unique identifier to be used as before pagination parameter if more items are available sorted before the current batch of items.

Request

POST

/projects/{project}/sims/search

curl https://api.gigs.com/projects/{project}/sims/search \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{\"iccid\":\"89883070000007537119\",\"type\":[\"eSIM\"]}"

Response

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

GET/projects/{project}/sims

List all SIMs

Returns a list of SIMs. The SIMs returned are sorted by creation date, with the most recently created SIMs appearing first.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"

Query Parameters

Name
provider
Type
array
Description
The network provider ID for the sim to be filtered by.
Name
status
Type
array
Description
A comma-separated list of statuses to filter the sims by.
Default: inactive,active
Name
type
Type
string
Description
The type for the sim to be filtered by.
Allowed values: eSIM, pSIM
Name
user
Type
string
Description
The unique identifier for the user to be filtered by.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
Name
after
Type
string
Description
A cursor for use in pagination. The after parameter takes an object ID that defines the position in the list, only items immediately following the item with that ID will be returned.
Name
before
Type
string
Description
A cursor for use in pagination. The before parameter takes an object ID that defines the position in the list, only items immediately preceding the item with that ID will be returned.
Name
limit
Type
integer
Description
The limit of items to be returned in the list, between 0 and 200.
Default: 10
>= 0
<= 200

Response Schemas

Returns a dictionary with an items property that contains an array of SIMs.

Name
object
Type
string
required
Description
Type of object is always list.
Allowed values: list
Name
items
Type
array
required
Description
List of objects of type `sim`.
Name
moreItemsAfter
Type
nullable string
required
Description
A unique identifier to be used as after pagination parameter if more items are available sorted after the current batch of items.
Name
moreItemsBefore
Type
nullable string
required
Description
A unique identifier to be used as before pagination parameter if more items are available sorted before the current batch of items.

Request

GET

/projects/{project}/sims

curl https://api.gigs.com/projects/{project}/sims \
-X GET \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

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