bg-gradient-orange
bg-gradient-orange-post-mobile
Feb, 3 2021

How to use Rest-API via Postman

api

You can use Postman as a powerful tool for testing and running EMnify’s Rest-API and perform operations in bulk.

Contents:

  • Create an Application Token
  • Getting Started with Postman
  • Retrieve Authentication Token
  • Register SIMs via API
  • Create Multiple Endpoints via API
  • Update SIMs via API
    • Activate 1 SIM
    • Activate multiple SIMs

Create an Application Token

The Application Token or “API-Key” is necessary for Authentication

  1. Visit the Technical Settings page in the EMnify UI
  2. Select “Create new Application Token”
  3. Save the application token in a secure place

Getting Started with Postman

  1. To create a new Environment in Postman click on the settings icon



  2. Add a Variable named “api_key” and paste the application token into the field under Initial Value. This enables you to save and use the application token within Postman.

  3. To save your API calls in Postman, click on Collections on the left side and then +New Collection. Name the Collection “Authentication” for the next step.

Retrieve Authentication Token

  1. Paste https://cdn.emnify.net/api/v1/authenticate into the URL field in Postman and set the call type to POST

    (
    see all API Calls in our API Documentation)

  2. In the Headers tab, create a Key called “Content-Type” and add “application/json” as the Value. All API calls to the EMnify API must have this content type.

  3. In the Body tab, select raw and insert the code below:
    {
    "application_token": ""
    }

  4. Since the authentication token is only valid for 240 minutes upon creation, it can be captured and used in further API calls when an authentication token is required. To capture the authentication token, create a new variable Auth_Token with an empty initial value. Click on the Tests tab and insert the following:

    var jsonData = JSON.parse(responseBody);
    setEnvironmentVariable("Auth_Token",jsonData.auth_token)

  5. Save your API Call to your previously created collection in Postman.

  6. click Send. A “200 OK” response status indicates a successful retrieval of the authentication token.

Register SIMs via API

To update (activate, suspend or delete) your SIMs you must first register them via the EMnify UI using the BIC-Code.

Alternatively, you can register one or multiple SIMs using the following API Call (Example BIC “ABCD1234EFGH6789”):

  1. Click the +New Button in the top left corner of Postman to create a new request.
    Name the request “SIM Registration” and add it to a new collection called “SIMs”.

  2. API Call: GET https://cdn.emnify.net/api/v1/sim_batch/bic/ABCD1234EFGH6789

  3. Insert “Content-Type” and “Authorization” as Keys in the Header tab and add the Values “application/json” and “Bearer ” as shown below.


  4. Click Send. A “200 OK” Response Status indicates successful Registration of the SIMs.

Create Endpoints via API

Creating multiple endpoints at once can be done using Postman. Furthermore, the API Call allows you to assign a SIM directly to a created endpoint.

  1. Click the the +New Button in the top left corner of Postman to create a new request.
    Name the request “Create Endpoints” and add it a new collection called “Endpoints”.

  2. Copy https://cdn.emnify.net/api/v1/sim/endpoint into Postman and set the call type to POST

  3. Insert “Content-Type” and “Authorization” as Keys in the Header tab and add the Values “application/json” and “Bearer ” as shown below.

  4. In the Body tab select raw insert the following JSON body:
    {

"name": "",

"tags": "",

"status": {

"id": 0

},

"service_profile": {

"id":

},

"tariff_profile": {

"id":

},

"sim": {

"id": ,

"activate": true

}

}

 

  1. In the Pre-request Script tab insert the following JSON body:

console.log("sim_id" + data.sim_id);

console.log("endpointname" + data.endpointname);

console.log("tag" + data.tag);

console.log("serviceprofile" + data.serviceprofile);

console.log("tariffprofile" + data.tariffprofile);

  1. To create multiple endpoints, a .csv file needs to be created containing all information needed to create an endpoint. The required information includes:
    1. Name of the endpoint
    2. Service Profile ID assigned to the endpoint (Found in the “Service Profiles” tab in the EMnify UI or via the following API Call: GET https://cdn.emnify.net/api/v1/sim/service_profile, Headers tab same input as Step 3)
    3. Tariff Profile ID assigned to the endpoint (Found in the “Tariff Profiles” tab in the EMnify UI or via the following API Call: GET https://cdn.emnify.net/api/v1/sim/tariff_profile, Headers tab same input as Step 3)
    4. The SIM ID of the SIM that should be assigned to the specific Endpoint (Found in the “SIMs” tab in the EMnify UI)

  2. The .csv file should look like this. The Column headers in the .csv file must be in the same order as shown below:

sim_id

endpointname

Serviceprofile

Tariffprofile

123123

exampleEndpoint1

456456

789789

111111

exampleEndpoint2

222222

333333

 

  1. Click Runner in the top left of Postman. A new Window will open.

 

  1. On the left side in the new window, click on the collection where the request is saved in (here collection “Endpoints”) and select the right environment, in this example “Introduction to Postman”.
    If you have more than one request within the selected collection, only tick the request that should be executed, in this case “SIM Update”.

 

  1. Click select File and choose the .csv file from Step 7.


 

  1. Add a Delay of 50ms if you are creating more than 200 Endpoints. The Program should automatically detect the number of iterations after you selected the .csv file.

 

  1. Click Preview to see how Postman interprets the .csv file. If you see an “iterations” column and four additional columns with the headers from Step 7, the .csv file is correct.

 

  1. Scroll down and click Run Endpoints. A 204 No Content” Status indicates successful creation of all the Endpoints and assignment of the SIMs to the endpoints.


Update SIMs via API

Activate 1 SIM

 

  1. Click the the +New Button in the top left corner of Postman to create a new request.
    Name the request “SIM Update” and add it the new collection called “SIMs”.

  2. Copy https://cdn.emnify.net/api/v1/sim/{sim_id} into Postman and set the call type to PATCH

  3. Insert “Content-Type” and “Authorization” as Keys in the Header tab and add the Values “application/json” and “Bearer ” as shown below.

 

  1. In the Body tab select raw insert the following JSON body:
    {
    "status": {

               "id": 1

              }

}

 

  1. To activate a specific SIM, copy its ID from the list of SIMs in the EUI and replace the “{sim_id}” with the SIM ID in the API Call URL.

  2. Click Send. A “204 No Content” Response Status indicates successful activation of the specific SIM.

Bulk Operations - Activate 100s of SIMS

To activate multiple SIMs with one API call in Postman, the software needs a variable containing an ID list of the SIMs which you want to activate.

  1. follow the steps 1-4 of activating 1 SIM via API. If you have already done so, you do not need to create a new request and repeat the steps.

  2. Create a .csv file containing all the SIM IDs you want to activate in one column. The First Cell in that column must be the variable name, i.e. “sim_id”.
    The .csv file should look like this:
    sim_id

123123
321321
456456
654654

  1. In Postman, copy log(“sim_id” + data.sim_id) into the Pre-request Script tab and replace the “{sim_id}” in the API Call URL with “” so Postman recognizes the variable as shown below.

  1. Click Runner in the top left of Postman. A new Window will open.

 

  1. On the left side in the new window, click on the collection where the request is saved in (here collection “SIMs”) and select the right environment, in this example “Introduction to Postman”.
    If you have more than one request within the selected collection, only tick the request that should be executed, in this case “SIM Update”.

 

  1. Click select File and choose the .csv file from Step 2.

  1. Add a Delay of 50ms if you are activating more than 200 SIMs. The Program should automatically detect the number of iterations after you selected the .csv file.

 

  1. Click Preview to see how Postman interprets the .csv file. If you see an “iterations” column and a “sim_id” column, the .csv file is correct.

 

  1. Scroll down and click Run SIMs. A 204 No Content” Status indicates successful activation of all the SIMs corresponding to the IDs in the .csv file. (The file in this example contained 3 SIM IDs)


Mass management with Postman

Do you want to create endpoints for all the SIMs you activated or receive detailed information on connectivity and network status via our Data Streamer? Try all our API Calls using Postman to mass manage and automate your processes.

Review our API Documentation