# SIMs

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

The following sections assume you have an [API key][authentication], your first project and familiarized your self with some basics of the Gigs API. All of this is covered by working through the [introduction][introduction-guide] 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 `pSIM`s 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][plans-endpoint] can provide these details:

<CodeGroup title="Retrieving plan details with the Gigs Core API - cURL.">

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

</CodeGroup>

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

<CodeGroup title="A successful plan response.">

```json
{
  "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": {...}
}
```

</CodeGroup>

From the above plan we can see that it supports both `pSIM` and `eSIM`s in Germany (DE). You will need to have your `pSIM`s 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][sims-endpoint]:

<CodeGroup title="Listing project SIMs with the Gigs Core API - cURL.">

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

</CodeGroup>

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

```json
{
  "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][create-a-subscription] for more details regarding connectivity supplied via eSIMs.

<Note type="info">

#### Provisioning Time

Depending on the network provider it can take several minutes before a SIM is fully provisioned.

</Note>

## Test SIMs

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

Follow our ["Create a subscription"][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][gigs-support].

[create-a-subscription]: /docs/create-a-subscription
[sims-endpoint]: /core/sims#list-all-sims
[sim-search-endpoint]: /core/sims#search-for-sims
[authentication]: /api/authentication
[plans-endpoint]: /core/plans#list-all-plans
[sims]: https://en.wikipedia.org/wiki/SIM_card
[introduction-guide]: /api/introduction
[create-a-subscription]: /core/subscriptions#create-a-subscription
[create-a-device]: /core/devices#create-a-device
[update-a-device]: /core/devices#update-a-device
[gigs-support]: mailto:support@gigs.com
[test-sims]: /docs/core/testing/test-sims