# SIMs

## The Sim object

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.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `sim`. |
| `id` | string | Yes | Unique identifier for the SIM. |
| `metadata` | object | Yes | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. |
| `createdAt` | string | Yes | Time when the SIM was created. |
| `iccid` | string | Yes | The ICCID (integrated circuit card identifier) associated with the SIM. |
| `provider` | string | Yes | The ID of the network provider of the SIM. |
| `status` | inactive | active | retired | Yes | The status of the SIM. Can be `active` or `inactive`. |
| `type` | eSIM | pSIM | Yes | The type of the SIM. Can be `eSIM` or `pSIM`. |

---

## Retrieve an eSIM profile

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

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 | Type | Required | Description |
|------|------|----------|-------------|
| `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). |
| `sim` | string | Yes | The unique identifier for the SIM. |

### Responses

#### 200 — Returns the eSimProfile if it exists.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `eSimProfile`. |
| `sim` | object | Yes | 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. |
| `status` | deleted | disabled | enabled | installed | unknown | Yes | The current status of the eSimProfile.  This will be `unknown` when:   - the SIM's provider is not supported (i.e. it is not `p3`), or   - no lifecycle events have occurred for the given SIM.  |
| `updatedAt` | string | Yes | Time at which the status was last updated. |

#### 404 — The requested resource doesn't exist.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- theme: info --> > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

---

## List all SIMs

`GET /projects/{project}/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 | Type | Required | Description |
|------|------|----------|-------------|
| `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). |

### Query Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `provider` | string[] | No | The network provider ID for the sim to be filtered by. |
| `status` | string[] | No | A comma-separated list of statuses to filter the sims by. |
| `type` | eSIM | pSIM | No | The type for the sim to be filtered by. |
| `user` | string | No | The unique identifier for the user to be filtered by. |
| `after` | string | No | 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. |
| `before` | string | No | 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. |
| `limit` | integer | No | The limit of items to be returned in the list, between 0 and 200. |

### Responses

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `list`. |
| `items` | object[] | Yes | List of objects of type `sim`. |
| `moreItemsAfter` | string,null | Yes | A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items. |
| `moreItemsBefore` | string,null | Yes | A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items. |

#### 422 — The request can't be processed, often due to an invalid parameter or incompatible system state.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- theme: info --> > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

---

## Retrieve a SIM

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

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

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). |
| `sim` | string | Yes | The unique identifier for the SIM. |

### Responses

#### 200 — Returns the SIM if it exists.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `sim`. |
| `id` | string | Yes | Unique identifier for the SIM. |
| `metadata` | object | Yes | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. |
| `createdAt` | string | Yes | Time when the SIM was created. |
| `iccid` | string | Yes | The ICCID (integrated circuit card identifier) associated with the SIM. |
| `provider` | string | Yes | The ID of the network provider of the SIM. |
| `status` | inactive | active | retired | Yes | The status of the SIM. Can be `active` or `inactive`. |
| `type` | eSIM | pSIM | Yes | The type of the SIM. Can be `eSIM` or `pSIM`. |

#### 404 — The requested resource doesn't exist.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- theme: info --> > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

---

## Update a SIM

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

Update the details of an existing SIM.

### Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `metadata` | object | No | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. |

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). |
| `sim` | string | Yes | The unique identifier for the SIM. |

### Responses

#### 200 — Returns the updates SIM.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `sim`. |
| `id` | string | Yes | Unique identifier for the SIM. |
| `metadata` | object | Yes | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. |
| `createdAt` | string | Yes | Time when the SIM was created. |
| `iccid` | string | Yes | The ICCID (integrated circuit card identifier) associated with the SIM. |
| `provider` | string | Yes | The ID of the network provider of the SIM. |
| `status` | inactive | active | retired | Yes | The status of the SIM. Can be `active` or `inactive`. |
| `type` | eSIM | pSIM | Yes | The type of the SIM. Can be `eSIM` or `pSIM`. |

#### 403 — The authenticated user doesn't have permissions to perform the request.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- theme: info --> > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

#### 404 — The requested resource doesn't exist.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- theme: info --> > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

#### 422 — The request can't be processed, often due to an invalid parameter or incompatible system state.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- theme: info --> > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

---

## Retrieve the SIM credentials

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

Retrieve the credentials of an existing SIM.

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). |
| `sim` | string | Yes | The unique identifier for the SIM. |

### Responses

#### 200 — Returns the SIM credentials.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `simCredentials`. |
| `activationCode` | string,null | Yes | eSIM activation code to download and install the profile in a device. Only available for type `eSIM`. |
| `androidInstallUrl` | string,null | Yes | URL to install the eSIM profile on Android devices. Only available for type `eSIM`.  <!-- theme: warning -->  > Be careful how you share this URL, it contains the credentials required to install the eSIM profile. |
| `iosInstallUrl` | string,null | Yes | URL to install the eSIM profile on iOS devices. Only available for type `eSIM`.  <!-- theme: warning -->  > Be careful how you share this URL, it contains the credentials required to install the eSIM profile. |
| `qrCodeUrl` | string,null | Yes | URL of the activation code in QR-Code format. Only available for type `eSIM`.  <!-- theme: warning -->  > Be careful how you share this URL, it can be accessed publicly without authentication. |
| `sim` | string | Yes | Unique identifier for the SIM this credentials are for. |

#### 404 — The requested resource doesn't exist.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- theme: info --> > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

---

## Search for SIMs

`POST /projects/{project}/sims/search`

Searches for existing SIMs matching the given parameters.

### Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `iccid` | string | Yes | The ICCID (integrated circuit card identifier) associated with the SIM. |
| `type` | array,null | No | Optional type of the SIM card, either `eSIM`, `pSIM` or both. |

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). |

### Responses

#### 200 — Returns a list schema response with all found SIMs.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `list`. |
| `items` | object[] | Yes | List of objects of type `sim`. |
| `moreItemsAfter` | string,null | Yes | A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items. |
| `moreItemsBefore` | string,null | Yes | A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items. |

#### 422 — The request can't be processed, often due to an invalid parameter or incompatible system state.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- theme: info --> > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

---