# Test SIMs

Test SIMs can be used for testing purposes or to get you going with the Gigs API while you are waiting on real SIMs to be made available to you.
These SIMs use a test provider and behave like any other API SIM resource, but don't provide actual connectivity.

## How to Use Test SIMs

The following Gigs API endpoints support the use of test SIMs:

- [Create a subscription][create-a-subscription]
- [Create a device][create-a-device]
- [Update a device][update-a-device]
- [Search for SIMs][sim-search-endpoint]

A new test SIM instance will automatically be created when you use a special placeholder SIM in a POST request such as: `sim_test_psim`.
This new test SIM instance will be generated with a unique resource ID as well a unique ICCID, starting with `8942424242` followed by 9 characters, for example: `"iccid": "89424242428486763002"`.

**Example: Creating a Subscription**

To use a test SIM in a subscription, you create a subscription with a special placeholder SIM ID in the request.
A new test SIM instance will be automatically created and associated to the newly created user's subscription.
For example, the request to create a new subscription with a test `pSIM` (using placeholder SIM ID: `sim_test_psim`) is:

<CodeGroup title="Creating a subscription using the placeholder physical SIM with the Gigs Core API - cURL.">

    ```bash
    curl --request POST \
    --url "https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptions" \
    --header "Accept: application/json" \
    --header "Authorization: Bearer ${GIGS_TOKEN}" \
    --header "Content-Type: application/json" \
    --data '{
    "plan": "...",
    "sim": "sim_test_psim"
    "user": "...",
}'
    ```

</CodeGroup>

This will result in a response similar to:

<CodeGroup title="Create subscription with placeholder sim response.">

    ```json
    {
        "object": "subscription",
        "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
        "currentPeriod": {...},
        "phoneNumber": "+25411865216434",
        "plan": {...},
        "sim": {
        "object": "sim",
        "id": "sim_0SNlurA049MEWV3clHBExvxoU22R",
        "type": "pSIM",
        "iccid": "89424242428486763002",
        "provider": "test",
        "status": "inactive",
        "createdAt": "2021-01-21T19:38:34Z"
    },
        "status": "pending",
        "user": {...},
        ...
    }
    ```

</CodeGroup>

The response contains the unique `id` and `ìccid` of the new SIM resource.

**Example: Searching for a test SIM**

To find the placeholder SIMs, you can search for them using the [SIM search endpoint][sim-search-endpoint] with the fixed ICCIDs, for example looking up the placeholder `eSIM` - `8942400090000000010`:

<CodeGroup title="Find the placeholder eSIM with the Gigs Core API - cURL.">

    ```bash
    curl --request "POST" \
    --url "https://api.gigs.com/projects/${GIGS_PROJECT}/sims/search" \
    --header "Accept: application/json" \
    --header "Authorization: Bearer ${GIGS_TOKEN}" \
    --header "Content-Type: application/json" \
    --data '{"iccid": "8942400090000000010"}'
    ```

</CodeGroup>

The response provides the details of the placeholder eSIM with the placeholder SIM ID:

<CodeGroup title="A test eSIM returned in the response.">

    ```json
    {
        "object": "list",
        "items": [
    {
        "object": "sim",
        "id": "sim_test_esim",
        "iccid": "8942400090000000010",
        "provider": "test",
        "status": "inactive",
        "type": "eSIM",
        "createdAt": "2021-01-01T00:00:00Z"
    }
        ],
        "moreItemsAfter": null,
        "moreItemsBefore": null
    }
    ```

</CodeGroup>

## Overview of Test SIMs

For testing purposes, the Gigs API supports both embedded and physical SIMs with various behaviors and delays.
Test SIMs with a delay mimic real-world subscription flows, whereas test SIMs without delays are ideal for automated testing.

For example, a test SIM ID with a delay such as `sim_test_psim_delayed_up_to_one_min` or `sim_test_esim_delayed_four_hours` will result in a created subscription which starts off in the status of "pending" before transitioning to a status of "active".
The transition time depends on the defined delay for the corresponding SIM.

<Note type="info">
    The delay specified in the test SIM ID applies both to initial subscription activation, and to replacement of an existing SIM via a subscription change.
</Note>

To make use of a test SIM, insert one of the below placeholder SIM IDs in a supported create request.
The placeholder SIM IDs are organized by provider.

<ProviderTestSimsTable
    data={{
        test: [
            {
                type: 'pSIM',
                id: 'sim_test_psim',
                iccid: '8942400090000000028',
                description: 'A pSIM which activates immediately',
            },
            {
                type: 'eSIM',
                id: 'sim_test_esim',
                iccid: '8942400090000000010',
                description: 'An eSIM which activates immediately',
            },
            {
                type: 'pSIM Delayed (up to 60 seconds)',
                id: 'sim_test_psim_delayed_up_to_one_min',
                iccid: '8942400090000000044',
                description:
                    'A pSIM with an activation delay between 30 and 60 seconds',
            },
            {
                type: 'eSIM Delayed (up to 60 seconds)',
                id: 'sim_test_esim_delayed_up_to_one_min',
                iccid: '8942400090000000036',
                description:
                    'An eSIM with an activation delay between 30 and 60 seconds',
            },
            {
                type: 'pSIM Delayed (4 hours)',
                id: 'sim_test_psim_delayed_four_hours',
                iccid: '8942400090000000069',
                description: 'A pSIM with an activation delay of four hours',
            },
            {
                type: 'eSIM Delayed (4 hours)',
                id: 'sim_test_esim_delayed_four_hours',
                iccid: '8942400090000000051',
                description: 'An eSIM with an activation delay of four hours',
            },
            {
                type: 'pSIM Delayed (24 hours)',
                id: 'sim_test_psim_delayed_twenty_four_hours',
                iccid: '8942400090000000085',
                description: 'A pSIM with an activation delay of 24 hours',
            },
            {
                type: 'eSIM Delayed (24 hours)',
                id: 'sim_test_esim_delayed_twenty_four_hours',
                iccid: '8942400090000000077',
                description: 'An eSIM with an activation delay of 24 hours',
            },
        ],
        t11: [
            {
                type: 'pSIM',
                id: 'sim_t11_psim',
                iccid: '8942401190000000025',
                description: 'A pSIM which activates immediately',
            },
            {
                type: 'eSIM',
                id: 'sim_t11_esim',
                iccid: '8942401190000000017',
                description: 'An eSIM which activates immediately',
            },
            {
                type: 'pSIM Delayed (up to 60 seconds)',
                id: 'sim_t11_psim_delayed_up_to_one_min',
                iccid: '8942401190000000041',
                description:
                    'A pSIM with an activation delay between 30 and 60 seconds',
            },
            {
                type: 'eSIM Delayed (up to 60 seconds)',
                id: 'sim_t11_esim_delayed_up_to_one_min',
                iccid: '8942401190000000033',
                description:
                    'An eSIM with an activation delay between 30 and 60 seconds',
            },
            {
                type: 'pSIM Delayed (4 hours)',
                id: 'sim_t11_psim_delayed_four_hours',
                iccid: '8942401190000000066',
                description: 'A pSIM with an activation delay of four hours',
            },
            {
                type: 'eSIM Delayed (4 hours)',
                id: 'sim_t11_esim_delayed_four_hours',
                iccid: '8942401190000000058',
                description: 'An eSIM with an activation delay of four hours',
            },
            {
                type: 'pSIM Delayed (24 hours)',
                id: 'sim_t11_psim_delayed_twenty_four_hours',
                iccid: '8942401190000000082',
                description: 'A pSIM with an activation delay of 24 hours',
            },
            {
                type: 'eSIM Delayed (24 hours)',
                id: 'sim_t11_esim_delayed_twenty_four_hours',
                iccid: '8942401190000000074',
                description: 'An eSIM with an activation delay of 24 hours',
            },
            {
                type: 'pSIM subscription canceled (blocked device)',
                id: 'sim_t11_psim_device_blocked',
                iccid: '8942401190000000108',
                description: 'A pSIM resulting in a subscription cancellation because the used device is blocked',
            },
            {
                type: 'eSIM subscription canceled (blocked device)',
                id: 'sim_t11_esim_device_blocked',
                iccid: '8942401190000000090',
                description: 'An eSIM resulting in a subscription cancellation because the used device is blocked',
            },
            {
                type: 'pSIM subscription canceled (blocked device)',
                id: 'sim_t11_psim_device_blocked_delayed',
                iccid: '8942401190000000124',
                description: 'A pSIM resulting in a subscription cancellation because the used device is blocked. Flow includes delays up to a few minutes.',
            },
            {
                type: 'eSIM subscription canceled (blocked device)',
                id: 'sim_t11_esim_device_blocked_delayed',
                iccid: '8942401190000000116',
                description: 'An eSIM resulting in a subscription cancellation because the used device is blocked. Flow includes delays up to a few minutes.',
            },
        ],
        t12: [
            {
                type: 'pSIM',
                id: 'sim_t12_psim',
                iccid: '8942401290000000023',
                description: 'A pSIM which activates immediately',
            },
            {
                type: 'eSIM',
                id: 'sim_t12_esim',
                iccid: '8942401290000000015',
                description: 'An eSIM which activates immediately',
            },
            {
                type: 'pSIM Delayed (up to 60 seconds)',
                id: 'sim_t12_psim_delayed_up_to_one_min',
                iccid: '8942401290000000049',
                description:
                    'A pSIM with an activation delay between 30 and 60 seconds',
            },
            {
                type: 'eSIM Delayed (up to 60 seconds)',
                id: 'sim_t12_esim_delayed_up_to_one_min',
                iccid: '8942401290000000031',
                description:
                    'An eSIM with an activation delay between 30 and 60 seconds',
            },
            {
                type: 'pSIM Delayed (4 hours)',
                id: 'sim_t12_psim_delayed_four_hours',
                iccid: '8942401290000000064',
                description: 'A pSIM with an activation delay of four hours',
            },
            {
                type: 'eSIM Delayed (4 hours)',
                id: 'sim_t12_esim_delayed_four_hours',
                iccid: '8942401290000000056',
                description: 'An eSIM with an activation delay of four hours',
            },
            {
                type: 'pSIM Delayed (24 hours)',
                id: 'sim_t12_psim_delayed_twenty_four_hours',
                iccid: '8942401290000000080',
                description: 'A pSIM with an activation delay of 24 hours',
            },
            {
                type: 'eSIM Delayed (24 hours)',
                id: 'sim_t12_esim_delayed_twenty_four_hours',
                iccid: '8942401290000000072',
                description: 'An eSIM with an activation delay of 24 hours',
            },
        ],
    }}
/>

<Note type="info">
    When you set the `sim` parameter to `auto` while creating a subscription, we’ll automatically provision an eSIM with a delay of up to 60 seconds.
    If you need faster activation times in automated end-to-end tests, use a test SIM which activates immediately.
</Note>

[sim-search-endpoint]: /core/sims#search-for-sims
[create-a-subscription]: /core/subscriptions#create-a-subscription
[create-a-device]: /core/devices#create-a-device
[update-a-device]: /core/devices#update-a-device