IoT Connectivity API

The CLX IoT connectivity service offers SIM cards with data, SMS and voice capabilities. This HTTP REST API provides a client facing management interface for those SIM cards.

The intended audience of this specification, are those who want to connect their IoT devices using the CLX IoT SIM card and integrate their applications to the CLX IoT connectivity service.

Parameter Guide

Here is a list of useful placeholders, and some examples, used throughout the documentation.

Token Type Example Description
api_access_token parameter 0102030405060708090a0b0c0d0e0f10 Your secure key to the API, used for authentication
service_plan_id parameter acmeiot001 Identity of your ordered group of SIM cards
sim_iccid parameter 89461100000000000000 Identity of a SIM card, printed on the physical card
application_id body 654321 Receiving number of SMS sent to your application
job_id parameter x_XVTug4bRMk1PX0 Identity of a Job that is returned by most API operations
batch_job_id parameter yXW8oY_clluy51GE Identity of a Batch Job that is returned by every batch operation

Get Started

This guide will help you get your devices connected using your CLX IoT SIM card.

Some steps require interaction with our HTTP REST API and include cURL examples for the needed API operations. Please note that every cURL example should be written as one line and <> should not be used around parameters, this is only used to highlight the parameters you need to replace with your own unique account information.

Before starting, please ensure that you have the following account details provided by your CLX Account Manager available:

  • API Access Token
  • Service Plan ID
  • SIM Card IDs (known as ICCID)
  • Application ID (if you’re going to Send an SMS)

1. Activate Your SIM Card

SIM cards are shipped in state test which only allows 500kB of data, 5 SMS and 5 min of voice calls to be used. When a SIM card is activated it is put in state active where traffic usage is no longer restricted. The purpose with the test state is to protect our customers from fraudulent usage until an authorized user decides that the SIM card is ready to be taken into use.

To activate your SIM card and enable full traffic usage, the following command is to be used:

curl -v -XPOST -H "Authorization: Bearer <api_access_token>” https://api.clxcommunications.com/iot/v1/<service_plan_id>/simcards/<sim_iccid>/activate

For more information, see the API documentation for Activate SIM card.

2. Connect Your SIM Card

You have now activated your SIM card, put it in your device and you are ready to connect it.

Below steps will guide you on what is required to connect your device using the different supported traffic types.

Data

All you need to do is to set the APN in your device to “connect”, and the data service will work.

The APN (Access Point Name) needs to be correctly configured in the mobile device to enable a data connection to the internet. The APN setting is done in the device and not on the SIM card. The method to configure the APN in a device is unique for each type of device, but is normally done using an AT-command, a GUI or SMS.

If you have ordered a private APN, use that instead. No user name or password is required for the APN.

SMS

SMS can be sent between your device with a CLX IoT SIM cards and an http end-point in your application.

Send SMS to device

The only way to send an SMS to a device with a CLX SIM card is through the CLX IoT API.

Use the below example to send an SMS to your device:

curl -H "Authorization: Bearer <api_access_token>” https://api.clxcommunications.com/iot/v1/<service_plan_id>/simcards/<sim_iccid>/send_sms -d { "from": "<application_id>", "message": "Hello world!" }

For more information, see the API documentation for Send an SMS.

Send SMS from device

To send an SMS from the device to your application, you first need to define the receiving http end-point in your application.

You register the receiving http end-point using the following command:

curl -H "Authorization: Bearer <api_access_token>” https://api.clxcommunications.com/iot/v1/<service_plan_id>/callbackurl -d { ”url": "“https://www.mydomain.com/iot/my_callback_url_endpoint" }

url is the address to your http end-point, typically in the form of “https://www.mydomain.com/iot/my_callback_url_endpoint

Once the http end-point is defined, you send the SMS from your device with your Application ID as the receiving number.

The SMS can now be retrieved from your defined http end-point.

For more information on SMS sent from the device, see the API documentation for Receive an SMS and Update the callback URL.

Voice

Voice is supported between your device and a SIP end-point in your infrastructure, typically a SIP client or an IP-PBX.

Voice is an optional feature that needs to be ordered through your CLX Account Manager. If not specifically requested at SIM order or after, voice will not work.

The first thing you need to do is to connect your SIP end-point to the SIP trunk CLX provide. This is done by configuring your SIP end-point with voice credentials received from your CLX Account Manager. It includes a key, a secret and the URL to the host.

Even when voice is provisioned on your account, it is still disabled by default on the SIM card. To enable voice, use the following command:

curl -H "Authorization: Bearer <api_access_token>” https://api.clxcommunications.com/iot/v1/<service_plan_id>/simcards/<sim_iccid>/voice -d { ”enabled": true }

You are now ready to make a voice call between your device and SIP end-point.

3. Monitor Status and Usage

After using the SIM card, you might be interested in querying a SIM card’s details to follow up on usage and status. SIM card details can also be used to validate that all SIM settings are correct in case of any problems to connect your device.

Query the details of a SIM card using the following API command:

curl -H "Authorization: Bearer <api_access_token>” https://api.clxcommunications.com/iot/v1/<service_plan_id>/simcards/<sim_iccid>

The response to the API call will look something like this:

{
    "id": "89463189999999999999",
    "status": "ACTIVE",
    "imei": "35974101123454",
    "blocked": false,
    "data": {
        "enabled": true,
        "limit": 1024,
        "usage": 234
    },
    "sms": {
        "enabled": true,
        "limit": 1024,
        "usage": 234
    },
    "voice": {
        "enabled": false
    },
    "location": {
        "network_id":"244001"
    },
    "created_at": "2016-07-01T09:00:00Z",
    "updated_at": "2016-07-01T09:00:00Z"
}

The below information will help you understand the SIM card information and guide you to ensure that your SIM card settings allows traffic to be sent and received from the SIM card.

ID is the ICCID, the identity of your SIM card that is printed on the physical SIM card.

Status will return one of the following states: Test, Active or Terminated. If the SIM is in state Test, allowed traffic usage is limited to 500 KB, 5 SMS and 5 voice minutes. Once these limits are reached, the SIM card needs to be activated for any further use. Use the API to activate the SIM card. If the state is Terminated, the SIM card will not send any traffic. There is no way to make a terminated SIM card active again.

IMEI is the identity of the hardware of your device. If this information is exposed to the network, it will be displayed.

Blocked will return true if the SIM card is blocked and false if the SIM card is not blocked. If the SIM card is blocked it will not send any traffic. Use the API to block or unblock the SIM card.

Enabled will return true if the specific traffic type is enabled on the SIM card and false if the traffic type is disabled. If the traffic type you are trying to use is disabled, it will not allow any traffic. Use the API command update SMS or update voice to enable the desired traffic type on the SIM card. Data is always enabled.

Limit defines the allowed traffic usage of a specific traffic type on a SIM card and usage states the total usage in the current month. If the usage value has reached the value in limit for any of the available traffic types, the SIM card has reached its limits and will not allow for any more traffic to be used of this type. The usage limit is reset every new calendar month and the SIM card will then be allowed to send traffic again. If connectivity needs to be enabled immediately, the usage limit can be extended using the API commands update data, update SMS or update voice. Please note that the limit is only valid if the SIM card is in state Active, if the SIM card is in state Test the default limits of 500 KB, 5 SMS and 5 voice minutes are applied.

Network ID specifies the network that your device is currently attached to. A network is identified by its MCC/MNC number, meaning Mobile Country Code which specifies the country and Mobile Network Code which specifies the operator. MCC is the first 3 digits in the number, and MNC is the last 2 or 3 digits.

Authentication

All requests towards the IoT API need a valid API access token for your specific Service Plan ID. Authentication tokens are passed through an HTTP header in the following format:

Authorization: Bearer <api_access_token>

JSON Schemas

JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and a web application. The CLX IoT API uses JSON to transmit data objects consisting of a number of attributes with different values.

Error

{
    "code": "1234"
    "text": "an error"
}
JSON Attribute JSON Type Description
code String Code representing error
text String Human readable message

Batch Error

{
    "simcard_id": "89461100000000000000"
    "text": "an error"
}
JSON Attribute JSON Type Description
simcard_id String ID of the SIM card
text String Human readable message

SIM Card

{
    "id": "89463189999999999999",
    "status": "ACTIVE",
    "imei": "35974101123454",
    "blocked": false,
    "data": {
        "enabled": true,
        "limit": 2880,
        "usage": 234
    },
    "sms": {
        "enabled": true,
        "limit": 1024,
        "usage": 234
    },
    "voice": {
        "enabled": true,
        "limit": 3600,
        "usage": 240
    },
    "location": {
        "network_id":"244001"
    },
    "created_at": "2016-07-01T09:00:00Z",
    "updated_at": "2016-10-05T13:40:00Z"
}
JSON Attribute JSON Type Description
id String Unique SIM card ID
status String Current SIM card state; possible values are: TEST, ACTIVE, SUSPENDED, TERMINATED
imei String Current device IMEI or IMEISV; may be empty if not available
blocked Boolean true if this SIM card has been blocked
data.enabled Boolean Data is always enabled, so this is always true
data.limit Integer Optional monthly data limit in KB
data.usage Integer Data usage in KB for this calendar month
sms.enabled Boolean true if SMS capability has been enabled for this SIM card
sms.limit Integer Optional monthly SMS limit, in number of messages
sms.usage Integer Total number of sent and recieved messages for this calendar month
voice.enabled Boolean true if voice capability has been enabled for this SIM card
voice.limit Integer Optional monthly voice limit, in minutes
voice.usage Integer Total number of minutes consumed for this calendar month
location.network_id String The current network ID (MCC/MNC); may be empty or partially available
created_at Timestamp ISO-8601 timestamp for when this SIM card was created (registered)
updated_at Timestamp ISO-8601 timestamp for when the metadata representing this SIM card was last updated

Job

{
    "id": "123e4567e89b12d3a456426655440000",
    "status": "PROCESSING",
    "type": "SMS_SERVICE_UPDATE",
    "created_at": "2016-07-01T09:00:00Z",
    "closed_at": "2016-07-01T09:00:01Z",
    "simcard_id": "89463189999999999999"
}
JSON Attribute JSON Type Description
id String Unique job ID
status String The current status of this job; possible status are: SUCCESS, ERROR, PROCESSING
type String The type of job
error String Only present if status is ERROR: give details about the error
created_at Timestamp ISO-8601 timestamp for when this job was started
closed_at Timestamp ISO-8601 timestamp for when this job was closed
simcard_id String The ID of the SIM card that this job relates to
batch_id String Only present if job is part of a batch

Batch Job

{
    "id": "123e4567e89b12d3a456426655440000",
    "status": "PROCESSING",
    "type": "BATCH_SMS_SERVICE_UPDATE",
    "created_at": "2016-07-01T09:00:00Z",
    "closed_at": "2016-07-01T09:00:01Z"
}
JSON Attribute JSON Type Description
id String Unique batch job ID
status String The current status of this job; possible status are: SUCCESS, ERROR, PROCESSING
type String The type of job
created_at Timestamp ISO-8601 timestamp for when this job was started
closed_at Timestamp ISO-8601 timestamp for when this job was closed

API Operations

List SIM Cards

This request lists all SIM cards, SIM cards with a specific state and/or blocked or unblocked SIM cards.

Request

GET /iot/v1/<service_plan_id>/simcards?status=ACTIVE&blocked=true&page=4&page_size=10
Parameter Type Optional Default Description
status query true N/A Comma-separated list of statuses to filter on
blocked query true N/A true to only include blocked SIM cards, false to only include unblocked SIM cards
page query true 0 Page to return; first page is 0
page_size query true 30 Number of elements to return per page, up to 100

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "count": 100,
    "simcards": [
        <sim_card>
    ],
    "page": 4,
    "page_size": 10
}

For the token <sim_card> see the JSON Schema SIM Card .

JSON Attribute JSON Type Description
count Integer Total number of available SIM cards
simcards Array List of available SIM cards in this page
page Integer Current page size
page_size Integer Number of available SIM cards in this page

Example

$ curl -H "Authorization: Bearer 0102030405060708090a0b0c0d0e0f10" https://api.clxcommunications.com/iot/v1/acmeiot001/simcards
{
    "count": 1,
    "simcards": [
        {
            "id": "89463189999999999999",
            "status": "TEST",
            "imei": "49015420323751",
            "blocked": false,
            "data": {
                "enabled": true,
                "usage": 0
            },
            "sms": {
                "enabled": true,
                "usage": 0
            },
            "voice": {
                "enabled": false
            },
            "location": {
                "network_id":"244001"
            },
            "created_at": "2016-07-01T09:00:00Z",
            "updated_at": "2016-10-05T13:40:00Z"
        }
    ],
    "page": 0,
    "page_size": 30
}

Get Details of a SIM Card

This operation can be used to get details of a single SIM card.

Request

GET /iot/v1/<service_plan_id>/simcards/<sim_iccid>

Response

HTTP/1.1 200 OK
Content-Type: application/json

<sim_card>

For the token <sim_card> see the JSON Schema SIM Card

Example

$ curl -H "Authorization: Bearer 0102030405060708090a0b0c0d0e0f10" https://api.clxcommunications.com/iot/v1/acmeiot001/simcards/89463189999999999999
{
    "id": "89463189999999999999",
    "status": "ACTIVE",
    "imei": "35974101123454",
    "blocked": false,
    "data": {
        "enabled": true,
        "usage": 50
    },
    "sms": {
        "enabled": true,
        "usage": 2
    },
    "voice": {
        "enabled" false
    },
    "location": {
        "network_id":"244001"
    },
    "created_at": "2016-07-01T09:00:00Z",
    "updated_at": "2016-10-05T13:40:00Z"
}

Activate SIM Card

This operation activates the specified SIM card.

When the IoT SIM cards are delivered, they are in state test. In state test, the usage is restricted to 500KB of data, a total of 5 SMS and a total of 5 min of voice calls and free of charge. This will allow you to configure the correct APN settings, attach the SIM card to the mobile network and finally test the service without being billed for the service charges. It also protects you from fraudulent usage before the device is ready to be taken into production and activated by an authorized user.

To allow for traffic use above the limited usage allowed in test state, you need to activate the SIM card. Activation will change the state from test to active and the test usage cap on the service will be removed and service charges will apply.

Request

POST /iot/v1/<service_plan_id>/simcards/<sim_iccid>/activate

Response

HTTP/1.1 202 ACCEPTED
Location: /iot/v1/<service_plan_id>/jobs/<job_id>

Example

$ curl -v -XPOST -H "Authorization: Bearer 0102030405060708090a0b0c0d0e0f10" https://api.clxcommunications.com/iot/v1/acmeiot001/simcards/89463189999999999999/activate

Block SIM Card

Blocks the specified SIM card from attaching to the mobile network and thereby no mobile services will be available for the SIM card. If the SIM card is already attached to a network, it will be detached.

Request

POST /iot/v1/<service_plan_id>/simcards/<sim_iccid>/block

Response

HTTP/1.1 202 ACCEPTED
Location: /iot/v1/<service_plan_id>/jobs/<job_id>

Unblock SIM Card

This operation is used to unblock the specified SIM card. The SIM card will be fully functional after the operation and all enabled capabilities will be available. Please note that some devices might require a reboot after unblock.

Request

POST /iot/v1/<service_plan_id>/simcards/<sim_iccid>/unblock

Response

HTTP/1.1 202 ACCEPTED
Location: /iot/v1/<service_plan_id>/jobs/<job_id>

Reconnect SIM Card

When a device has connection problems and it is suspected that they are network related, reconnect can be used to reset the SIM card’s network connection and correct possible network registration problems. At reconnect, the SIM card is disconnected from the network and the most recent registration information in the network is deleted. Please note that some devices might require a reboot after reconnect.

Request

DELETE /iot/v1/<service_plan_id>/simcards/<sim_iccid>/reconnect

Response

HTTP/1.1 200 OK
Content-Length: 0

Terminate SIM Card

This operation terminates the specified SIM card. Please note that it’s not possible to re-activate a terminated SIM card.

Request

POST /iot/v1/<service_plan_id>/simcards/<sim_iccid>/terminate

Response

HTTP/1.1 202 ACCEPTED
Location: /iot/v1/<service_plan_id>/jobs/<job_id>

Update Data

This operation is used to set the maximum data usage limit for the specified SIM card (per month). The counter will be reset and it will start from zero at the beginning of each calender month.

Request

POST /iot/v1/<service_plan_id>/simcards/<sim_iccid>/data
{
    "limit": 512
}
JSON Attribute JSON Type Optional Default Description
limit Integer false N/A Limit of data allowed to be downloaded/uploaded from this SIM card, displayed in kilobytes, in a calendar month

Response

HTTP/1.1 202 ACCEPTED
Location: /iot/v1/<service_plan_id>/jobs/<job_id>

Update SMS

This operation is used to update the SMS service.

Request

POST /iot/v1/<service_plan_id>/simcards/<sim_iccid>/sms
{
    "enabled": true,
    "limit": 512
}
JSON Attribute JSON Type Optional Default Description
enabled Boolean false N/A true to activate the SMS service, false to deactivate
limit Integer true N/A Limit of SMS allowed to be sent, or recieved, from this SIM card, in a calendar month

Response

HTTP/1.1 202 ACCEPTED
Location: /iot/v1/<service_plan_id>/jobs/<job_id>

Update Voice

This operation is used to update the voice service. Voice is supported between the SIM card and a SIP end-point on the customer side, typically a SIP client or an IP-PBX. Voice is an add on service that needs to be ordered through your CLX account manager. Once voice is provisioned for the customer account, you will receive the necessary information to register your SIP end-point.

In order to make and receive voice calls:

  • Voice must be provisioned for the customer account, this is done through your CLX account manager.
  • Once voice is provisioned, customer must register their SPI end-point according to instructions received.
  • In addition, your SIM card must:
    • be activated.
    • have the voice feature enabled, using the API call described below.

Request

POST /iot/v1/<service_plan_id>/simcards/<sim_iccid>/voice
{
    "enabled": true,
    "limit": 300
}
JSON Attribute JSON Type Optional Default Description
enabled Boolean false N/A true to activate the Voice service, false to deactivate
limit Integer true N/A Number of allowed voice minutes for calls made or received for this SIM card, in a calendar month

Response

HTTP/1.1 202 ACCEPTED
Location: /iot/v1/<service_plan_id>/jobs/<job_id>

Send an SMS

The CLX IoT connectivity service supports sending of SMS between the SIM card and an http end-point in customer’s own application. In order to send and receive SMS, your SIM card must:

  • be activated.
  • have the SMS feature enabled.

Operation to send an SMS to one of your SIM cards is described in the request below. It will send the message from the API, through the network to your SIM card. Delivery Receipt of the sent SMS is retrieved from the callback URL, see further information in the Update the callback URL chapter below.

Request

POST /iot/v1/<service_plan_id>/simcards/<sim_iccid>/send_sms
{
    "from": "555555",
    "message": "This is the content of the message."
}
JSON Attribute JSON Type Optional Default Description
from String false N/A The Application ID where the SMS is originating from, application ID is provided by your account manager
message String false N/A The content of the SMS

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "message_id": "abcd1234"
}
JSON Attribute JSON Type Description
message_id String The unique tracking number of the sent SMS

Delivery Receipt

When an SMS is received and opened by the device hosting the SIM card, a Delivery Receipt will be returned through the network. This Delivery Receipt will land in the IoT API and is retrieved through the callback URL.

The IoT API reaches the callback URL, and sends the following payload:

{
    "message_id": "abcd1234",
    "state": "DELIVRD",
    "received_at": "2017-07-05T12:30:00Z",
    "type": "DR"
}
JSON Attribute JSON Type Description
message_id String Tracking number of the sent message
state String SMPP status of the message
received_at String Timestamp when the end device received and opened the message
type String Type is always DR (Delivery Receipt)

Receive an SMS

When sending an SMS from a SIM card to the application, the SMS lands in the IoT API and is retrieved from the callback URL. A callback URL must be configured to receive the SMS, see further information in the Update the callback URL chapter below.

The IoT API will reach the callback URL, and send the following payload:

{
    "from": "89463189999999999999",
    "to": "12345",
    "message": "Copy that, roger.",
    "type": "MO"
}
JSON Attribute JSON Type Description
from String SIM card ID
to String Application ID
message String Message sent by the SIM card
type String Type is always MO (Mobile Originating)

Update the Callback URL

A callback URL is an endpoint on the customer side, which is able to receive HTTP requests from the IoT API. The callback URL is used to receive SMS sent from the SIM card to the application or to receive Delivery Receipts of SMS sent from the application to the SIM card.

The design of the callback URL must respect the following requirements:

  • accept HTTP POST requests.
  • accept JSON Payloads.
  • return HTTP 2xx on success.

This operation is used to update the callback URL.

Request

POST /iot/v1/<service_plan_id>/callbackurl
{
    "url": "https://www.mydomain.com/iot/my_callback_url_endpoint"
}
JSON Attribute JSON Type Optional Default Description
url Query false N/A Endpoint on your side, to receive both DR and MO events from the IoT API

Response

HTTP/1.1 200 OK

Get the Callback URL

Operation to retrieve the current callback URL.

Request

GET /iot/v1/<service_plan_id>/callbackurl

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "url": "https://www.mydomain.com/iot/my_callback_url_endpoint"
}
JSON Attribute JSON Type Optional Default Description
url Query false N/A Endpoint on your side, to receive both DR and MO events from the IoT API

List Jobs

Lists all available jobs.

Request

GET /iot/v1/<service_plan_id>/jobs?status=ERROR&page=0&page_size=30
Parameter Type Optional Default Description
status query true N/A Comma-separated list of statuses to filter on
page query true 0 Page to return; first page is 0
page_size query true 30 Number of elements to return per page, up to 100

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "count": 100,
    "jobs": [
        <job>
    ],
    "page": 0,
    "page_size": 30
}

For the token <job> see the JSON Schema Job

JSON Attribute JSON Type Description
count Integer Total number of available jobs
jobs Array List of available jobs in this page
page Integer Current page size
page_size Integer Number of available jobs in this page

Fetch job

Since the API operations are asynchronous, you need to fetch the job status to verify if an operation is completed.

Request

GET /iot/v1/<service_plan_id>/jobs/<job_id>

Response

HTTP/1.1 200 OK
Content-Type: application/json

<job>

For the token <job> see the JSON Schema Job

Example

$ curl -H "Authorization: Bearer 0102030405060708090a0b0c0d0e0f10" https://api.clxcommunications.com/iot/v1/acmeiot001/jobs/123e4567e89b12d3a456426655440000
{
    "id": "123e4567e89b12d3a456426655440000",
    "simcard_id": "89463189999999999999",
    "status": "SUCCESS",
    "created_at": "2016-10-01T00:00:00Z",
    "closed_at": "2016-10-01T0:00:01Z",
    "type": "activation",
    "error": null
}

Fetch batch job

Request

GET /iot/v1/<service_plan_id>/batchjobs/<batch_job_id>

Response

HTTP/1.1 200 OK
Content-Type: application/json

<batch_job>

For the token <batch_job> see the JSON Schema Batch Job

List Jobs of a Batch Job

Request

GET /iot/v1/<service_plan_id>/batchjobs/<batch_job_id>/jobs?page=2&page_size=20
Parameter Type Optional Default Description
page query true 0 Page to return; first page is 0
page_size query true 30 Number of elements to return per page, up to 100

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "count": 100,
    "jobs": [
        <job>
    ],
    "page": 2,
    "page_size": 20
}

For the token <job> see the JSON Schema Job

JSON Attribute JSON Type Description
count Integer Total number of available jobs
jobs Array List of available jobs in this page
page Integer Current page size
page_size Integer Number of available jobs in this page

Batch Operations

Most API Operations are available as batch operations, to be used on an array of multiple SIM cards instead of on an individual SIM card. Available batch commands are listed below.

Batch Activate

See Activate SIM card.

POST /iot/v1/<service_plan_id>/simcards/activate

{
    "simcard_ids": [
                "89461100000000000000",
    ]           "89461100000000000001"
}
JSON Attribute JSON Type Optional Default Description
simcard_ids Array false N/A List of SIM card IDs to perform the operation on, up to 100

Batch Block

See Block SIM card.

POST /iot/v1/<service_plan_id>/simcards/block

{
    "simcard_ids": [
                "89461100000000000000",
    ]           "89461100000000000001"
}
JSON Attribute JSON Type Optional Default Description
simcard_ids Array false N/A List of SIM card IDs to perform the operation on, up to 100

Batch Unblock

See Unblock SIM card.

POST /iot/v1/<service_plan_id>/simcards/unblock

{
    "simcard_ids": [
                "89461100000000000000",
    ]           "89461100000000000001"
}
JSON Attribute JSON Type Optional Default Description
simcard_ids Array false N/A List of SIM card IDs to perform the operation on, up to 100

Batch Terminate

See Terminate SIM card.

POST /iot/v1/<service_plan_id>/simcards/terminate

{
    "simcard_ids": [
                "89461100000000000000",
    ]           "89461100000000000001"
}
JSON Attribute JSON Type Optional Default Description
simcard_ids Array false N/A List of SIM card IDs to perform the operation on, up to 100

Batch Update Data

See Update Data.

POST /iot/v1/<service_plan_id>/simcards/data
{
    "simcard_ids": [
                "89461100000000000000",
    ],          "89461100000000000001"
    "limit": 512
}
JSON Attribute JSON Type Optional Default Description
simcard_ids Array false N/A List of SIM card IDs to perform the operation on, up to 100
limit Integer false N/A Limit of data allowed to be downloaded/uploaded from this SIM card, displayed in kilobytes, in a calendar month

Batch Update SMS

See Update SMS.

POST /iot/v1/<service_plan_id>/simcards/sms
{
    "simcard_ids": [
                "89461100000000000000",
    ],          "89461100000000000001"
    "enabled": true,
    "limit": 512
}
JSON Attribute JSON Type Optional Default Description
simcard_ids Array false N/A List of SIM card IDs to perform the operation on, up to 100
enabled Boolean false N/A true to activate the SMS service, false to deactivate
limit Integer true N/A Limit of SMS allowed to be sent, or received, from this SIM card, in a calendar month

Batch Update Voice

See Update Voice.

POST /iot/v1/<service_plan_id>/simcards/voice
{
    "simcard_ids": [
                "89461100000000000000",
                "89461100000000000001"
    ],
    "enabled": true,
    "limit": 512
}
JSON Attribute JSON Type Optional Default Description
simcard_ids Array false N/A List of SIM card IDs to perform the operation on, up to 100
enabled Boolean false N/A true to activate the Voice service, false to deactivate
limit Integer true N/A Number of allowed voice minutes for calls made or received for this SIM card, in a calendar month

Batch Response

This is the response for all batch requests.

HTTP/1.1 202 ACCEPTED
Location: /iot/v1/<service_plan_id>/batchjobs/<batch_job_id>
{
    "errors": [
            <batch_error>
    ]
}

For the token <batch_error> see the JSON Schema Batch Error

JSON Attribute JSON Type Description
errors Array List of SIM card IDs, and corresponding error messages, that were not valid for for the batch operation

HTTP Status Codes

The following HTTP status codes are used by the API.

Status Description
200 OK The request was successful.
201 Created The request was successful and a new resource was created.
400 Bad Request The request does not conform to the API. The request body should provide more information.
401 Unauthorized Authentication token is invalid for this service plan
403 Forbidden The request syntax is valid but cannot be performed. This could for example be because a referenced resource doesn’t exist.
404 Not Found The path is invalid or no resource exists with the given ID.
405 Method Not Allowed The path is valid but not for this method.
415 Unsupported Media Type The request Content-Type is missing or unsupported. Most operations expect application/json.
500 Internal Server Error An unexpected internal error occurred and the request was not processed.
503 Service Unavailable The service is unable to perform the request at this point. Most likely due to a required subsystem being unavailable.