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 SIM’s: eSIM and pSIM. eSIM’s can be activated and installed instantly on any eSIM compatible device, pSIM’s (physical SIM’s) must be provided to the user or installed into the device beforehand.

Properties

  • Name
    object
    Type
    string
    Description

    Type of object is always sim.

  • Name
    id
    Type
    string
    Description

    Unique identifier for the SIM.

    Example: sim_0SNlurA049MEWV1BAAmWZULA4lf6
  • Name
    metadata
    Type
    object
    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

  • Name
    object
    Type
    string
    required
    Description

    Type of object is always eSimProfile.

  • Name
    sim
    Type
    object
    required
    Description
  • 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

  • Name
    object
    Type
    string
    required
    Description

    Type of object is always 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

  • Name
    object
    Type
    string
    required
    Description

    Type of object is always sim.

  • Name
    id
    Type
    string
    required
    Description

    Unique identifier for the SIM.

    Example: sim_0SNlurA049MEWV1BAAmWZULA4lf6
  • Name
    metadata
    Type
    object
    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
    object
    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

  • Name
    object
    Type
    string
    required
    Description

    Type of object is always sim.

  • Name
    id
    Type
    string
    required
    Description

    Unique identifier for the SIM.

    Example: sim_0SNlurA049MEWV1BAAmWZULA4lf6
  • Name
    metadata
    Type
    object
    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

  • Name
    object
    Type
    string
    required
    Description

    Type of object is always 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

  • Name
    object
    Type
    string
    required
    Description

    Type of object is always 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
}