If you have already read our initial article (introduction to the EMnify API), you may want to check how to use the most common API calls:

1. How to create multiple Connected Devices (Endpoints) using the API
2. How to send and receive SMS via API
3. How to reset the connectivity of an Endpoint (Connected Device) via API

How to create multiple Connected Devices (Endpoints) using the API

Our API documentations describes how to create one endpoint. By using Postman we will explain how to create x number of endpoints at once. Let's first take a look at the information we need to gather about an endpoint in order to create one (point 1). We'll then send two APIs requests to create multiple endpoints (point 2)  at once and we will finally create them (point 3).

1. Necessary information to create an endpoint

According to the API documentation, the POST API used to create one endpoint on the EMnify platform, needs to have the following information:

• Name of the endpoint (required);
• Tags (optional) - You have the possibility to add specific information for each endpoint;
• Status: activate or not (required) - is the endpoint activated or disable;
• Service profile (required) - ID of the Service Profile assigned to the endpoint. To find this information, navigate to the "Service Profiles" tab in the EUI or run this API;
• Tariff profile (required) - ID of the tariff Profile assigned to the endpoint. To find this information, navigate to the "Tariff Profiles" tab in the EUI or run this API;
• SIM (optional) - if we want to directly assign a SIM to the created endpoint, we need to enter here the SIM ID.  To find this information, navigate to the SIMs tab in the EUI;

For each endpoint we want to create, the above mentioned information need to be entered. In order to create several of them at once, we can use the "Runner" option in Postman. To do so, create a .csv file (separated with comma) and enter the information as follow:

 You should have as many lines as endpoints you wish to create and the column headers in the same order.

2. Preparing the APIs to run

To run any API on our platform, you need to authenticate (point 2.1) and then run the endpoint creation API (point 2.2)

 2.1 Authentication

POST https://cdn.emnify.net/api/v1/authenticate

An article about the API authentication methods is available on our developer hub.

 2.2 Creating the endpoints based on these information

POST https://cdn.emnify.net/api/v1/endpoint

Header :
Content-type: application/json
Authorization: Bearer {{auth_token}}

Body: 

{
"name": "{{endpointname}}",
"tags": "{{tag}}",
"status": {
 "id": 0
},
"service_profile": {
 "id": {{serviceprofile}}
},
"tariff_profile": {
 "id": {{tariffprofile}}
},
"sim": {
 "id": {{sim_id}},
 "activate": true
}
}

The {{variables}} need to be created based on the information in our .csv file before the API is called . For this, we use the "Pre-request Script" option available in Postman.

Pre-request Script (in Postman this is used to create these variables based on the .csv file we created before running the API):

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); 

Running the different APIs at once

We are now ready to run the APIs multiple times and create several endpoints at once. In Postman, click on "Runner", select a collection, an environment, and your .csv file. The number of iterations should then automatically be detected. Please make sure that the ''delay'' is at least 50 ms. Also, click the checkbox of ''Keep variable values''. You can preview your file to be sure that everything is fine before clicking on "start run". This is how the preview should look like: 

 
Responses if everything went fine

Authentication post API: 200 OK
Create endpoint post API: 201 Created

Responses when you have an issue

If your authentication API failed, nothing will work.
If the endpoint creation API failed, check the following:

• Is your .csv file comma delimited (excel can be a bit messy sometimes, you can try another program like notepad++);
• Check the spelling of your variables: they should be written exactly the same way in the .csv file and in Postman;
• Check the format of the API body where it is easy to forget a character.

How to send and receive SMS via API

To submit SMS directly from your application to an endpoint using our API, the following API call needs to be made:

POST https://cdn.emnify.net/api/v1/endpoint/{endpointId}/sms

Required Headers:

Content-Type: application/json

Authorization: Bearer {auth_token}

JSON Body:

{

    "source_address": "12345",

    "payload": "This is the message text!"

}

To receive SMS on your application server from the device you will need to first set up a Callback URL in the Service profile assigned to that endpoint:

• Set the API URL on the "SMS" tab - select "RestAPI" on the drop-down menu for “Interface”

• Select the “configuration icon” next to “RestAPI”, input a purpose (name of your choosing) and the URL
• You can also set up a "Secret" (optional)

The EMnify system will then send the MO SMS as a JSON payload if the destination address of the SMS is an invalid MSISDN (7 digits or less).

A2P / P2P Routing

Our system distinguishes A2P SMS (application-to-person) from P2P SMS (person-to-person) based on the length of the source (MO SMS) or the destination (MT SMS) address.

• If there are 7 digits or less (i.e. an invalid MSISDN), an SMS will be considered A2P.
• If there are 8 digits or more, an SMS will be processed as MSISDN and will be considered P2P.

To dispatch SMS MO to your application (A2P) and at the same time have P2P SMS enabled, the destination number (dest_address) must be limited to 8 digits or less.

A detailed description of the SMS API you can find in our API Documentation.

How to reset the connectivity of an Endpoint (Connected Device) via API

Note: If your SIM cards are in Factory Test mode, resetting the connectivity will change their status to activated.

For troubleshooting purposes, you might need to reset the connectivity of an endpoint. The device would restart the network connection procedure. You can do so via the EUI by selecting it and clicking on "Reset Connectivity". To do the same via API, four APIs need to be called:

1. Disabling the endpoint
2. Enabling the endpoint
3. Suspending the SIM card attributed to the endpoint
4. Activating the SIM card attributed to the endpoint

Let's take a look at each API.

1. Disabling the Endpoint

Patch https://cdn.emnify.net/api/v1/endpoint/{endpoint_id}

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

2. Enabling the Endpoint

Patch https://cdn.emnify.net/api/v1/endpoint/{endpoint_id}

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

3. Suspending the SIM

Patch https://cdn.emnify.net/api/v1/sim/{sim_id}

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

4. Activating the SIM

Patch https://cdn.emnify.net/api/v1/sim/{sim_id}

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

NOTES:

• SIM status 0: "Issued"
  • A SIM once activated cannot be brought back to the initial state.
• SIM status 3: "Deleted"
  • This status will remove the SIM from your repository - to be used only if the SIM was lost or damaged. The SIM needs to be released from the endpoint.
• Endpoint status 0: "Enable"
• Endpoint status 1: "Disable"