Manage Devices

To change your device’s connectivity, you need to execute two distinct API calls—one for the SIM and another for the endpoint. It’s important to run both APIs to keep the statuses aligned and consistent.

For getting your device online, this entails patching the SIM status to Activated and the endpoint status to Enabled. With the emnify REST API, you can also change the statuses of multiple devices at once.

Update the SIM status

After registration, the SIMs move between the different states depending on your needs and requirements.

The Update a SIM API call lets you to manage device connectivity by patching the SIM status. You can patch SIMs to the following statuses and respective IDs using the API:

• Issued ("id": 0) to either Activated ("id": 1) or Factory Test ("id": 4)
• Factory Test ("id": 4) to Activated ("id": 1)
• Switch between Activated ("id": 1) and Suspended ("id": 2)

For definitions of each SIM status and how they relate to each other, see SIM lifecycle management in the emnify Product Documentation.

Activate a SIM

To create a new request in Postman, click +New in the upper left corner. Name the request Update status and add it to the SIMs collection you created in Register SIMs.

Then follow these steps to set up your request:

1. Select the PATCH HTTP method.
2. Set the request URL as https://cdn.emnify.net/api/v1/sim/{sim_id}, replacing {sim_id} with the ID of the SIM you want to update.
3. Navigate to the Headers tab. Insert Content-Type and Authorization as Keys and add the respective Values application/json and Bearer TOKEN. Replace TOKEN with your auth_token and make sure there’s a non-breaking space between Bearer and the token value.
   
4. Go to the Body tab and select raw. Make sure the format is set to JSON. Then, set the status to Activated to get them online immediately:

{
    "status": {
        "id": 1
    }
}

Suspend a SIM

To suspend a SIM card, follow the same steps from the preceding “Activate the SIM” section. Then, in the Body tab, set the status to Suspended:

{
    "status": {
        "id": 2
    }
}

Update the endpoint status

Similar to SIMs, the Update an Endpoint API call lets you to manage device connectivity by patching the endpoint status.

You can patch endpoints to the following statuses and respective IDs using the API:

• Enabled ("id": 0)
• Disabled ("id": 1)

Enable an endpoint

To create a new request in Postman, click +New in the upper left corner. Name the request Update status and add it to the Endpoints collection you created in Create Endpoints.

Then follow these steps to set up your request:

1. Select the PATCH HTTP method.
2. Set the request URL as https://cdn.emnify.net/api/v1/endpoint/{endpoint_id}, replacing {endpoint_id} with the ID of the endpoint you want to update.
3. Navigate to the Headers tab. Insert Content-Type and Authorization as Keys and add the respective Values application/json and Bearer TOKEN. Replace TOKEN with your auth_token and make sure there’s a non-breaking space between Bearer and the token value.
   
4. Go to the Body tab and select raw. Make sure the format is set to JSON. Then, set the status to Enabled to get your device online immediately:

{
    "status": {
        "id": 0
    }
}

Disable an endpoint

To disable an endpoint and , follow the same steps from the preceding “Activate the endpoint” section. Then, in the Body tab, set the status to Disabled:

{
    "status": {
        "id": 1
    }
}

Bulk updates on multiple devices

Prepare your data

The most efficient way to update multiple devices simultaneously via the emnify REST API is to have your data prepared in a comma-separated values (CSV) file.

One way to generate a CSV file is to create a table in Excel that includes the necessary details for your SIMs or endpoints. After you create your file, do the following:

1. In the first row, insert the required properties as columns (for example, sim_id or endpoint_id).
2. Fill in the corresponding data. Each row should represent one SIM or endpoint.
3. Once complete, save it as a CSV file (.csv).

Run the API in bulk with Postman

If you haven’t already, set up your Update status request using the process outlined in the preceding sections. Then, follow these steps:

1. Click Runner in the lower right corner.
2. Choose how to run your collection and set your Run configuration:
   • Iterations: Number of devices you want to create (also the number of rows from your CSV file).
   • Delay: Time between calls. Best practice is 1000 ms regardless of how many devices you’re creating.
   • Data: Upload your CSV file with the Data File Type set to text/csv.
3. Adjust any other settings as necessary, then click Start Run.

Where to find the necessary IDs

SIM ID

To get your sim_id, run the List SIMs API call. Then, locate the ID of the SIM you want to update.

Alternatively, you can find the ID and other SIM details in the SIM Inventory page of the emnify Portal. For specifics, see the emnify Product Documentation.

Endpoint ID

To get your endpoint_id, run the List Endpoints API call. Then, locate the ID of the endpoint you want to update.

Alternatively, you can find the ID and other endpoint details in the Connected Devices page of the emnify Portal. For specifics, see the emnify Product Documentation.

To get a list of all your devices, follow these steps:

1. Log in to your emnify account.
2. Navigate to Reports and select Device list.
3. Hover over Endpoint Repository. Click the hamburger menu (labelled More Options) in the upper right corner of the sheet.
4. In the menu, click Download Data to download a CSV file of the device list.

To use this file in the Runner, keep the endpoint_id column and delete the rest.