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 integrate their applications to the CLX IoT connectivity service.

Get Started

This chapter gives you a few cURL examples to quickly get started with the API. A full list of API operations are found further down in this document or can be easily accessed through the menu to the left.

Before starting, please ensure that you have:

  • the API access token from your account manager. The access token looks like 0102030405060708090a0b0c0d0e0f10.
  • the IoT Service Plan ID that is assigned for the group of SIM cards you ordered. The service plan ID looks like acmeiot001.

List my SIM cards

The first thing you want to do is likely to list all the SIM cards you ordered:

$ 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": true,
                "usage": 0
            },
            "location": {
                "network_id":"244001"
            },
            "created_at": "2016-07-01T09:00:00Z",
            "updated_at": "2017-10-05T14:09:00Z"
        }
    ],
    "page": 0,
    "page_size": 30
}

Activate a SIM card

When the IoT SIM cards are delivered, they are in status TEST. In status TEST, the usage is restricted to 500KB of data, a total of 5 SMS and a total of 5 min of voice calls. This will allow you to attach a SIM card to a mobile network, configure the correct APN settings and finally test the services without being billed for the service charges.

To put the SIM card in production and allow for traffic use above the limited usage allowed in TEST status, you need to activate the SIM card via the API:

  • the status will change from TEST -> ACTIVE.
  • the TEST usage cap on the services will be removed and service charges will apply.
$ curl -v -XPOST -H "Authorization: Bearer 0102030405060708090a0b0c0d0e0f10" \
https://api.clxcommunications.com/iot/v1/acmeiot001/simcards/89463189999999999999/activate
*   Trying 52.73.17.89...
* Connected to api.clxcommunications.com (52.73.17.89) port 443 (#0)
* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
* Server certificate: api.clxcommunications.com
* Server certificate: GlobalSign Organization Validation CA - SHA256 - G2
* Server certificate: GlobalSign Root CA
> POST / HTTP/1.1
> Host: api.clxcommunications.com
> User-Agent: curl/7.43.0
> Accept: */*
>
< HTTP/1.1 202 Accepted
< Date: Thu, 1 Oct 2016 00:00:00 GMT
< Location: /iot/v1/acmeiot001/jobs/123e4567e89b12d3a456426655440000
< Connection: close
< Content-Length: 0
<
* Closing connection 0\u00a0

Asynchronous Actions

Since the activation is asynchronous, you then need to poll the job status:

$ 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
}

SIM card status

After using the SIM card for a while, you might be interested in querying a SIM card’s status to check for example usage and network location:

$ 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-07-01T09:00:00Z"
}

Send and receive SMS

The CLX IoT connectivity service supports sending of SMS between the SIM card and the application. In order to send and receive SMS, your SIM card must:

  • be activated.
  • have the SMS feature enabled.

To send an SMS to a SIM card:

$ curl -H "Authorization: Bearer 0102030405060708090a0b0c0d0e0f10" \
 https://api.clxcommunications.com/iot/v1/acmeiot001/simcards/89463189999999999999/send_sms \
 -d { "from": "12345", "message": "Hello world!" }

The API will send the message through the network to your SIM card. If it succeeds, it will return the following HTTP OK response:

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

{
    "message_id": "abcd1234"
}

This message_id is the unique identifier of your outbound SMS. It will help you to track this message later.

A callback URL is an endpoint on your end, 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. Further information on the callback URL and related functionality is found in the API Operations chapter.

The rest of this document will cover details on authentication, JSON schemas for error, SIM card, job entities and the list of operations that can be performed on the SIM card and job entities.

Make and receive voice calls

The CLX IoT connectivity service supports voice calls between the SIM card and customer’s IP-PBX - a phone switch on the customer side. Voice is an add on service that needs to be ordered through your CLX account manager. Once voice is provisioned for the customer account, customer will receive the necessary information to register its IP-PBX.

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 IP-PBX according to instructions received.
  • In addition, your SIM card must:
    • be activated.
    • have the voice feature enabled.

Batch API operations

Most API Operations are also 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 under Batch Operations.

Authentication

All requests towards the IoT API need a valid authentication token for that service plan ID. Authentication tokens are passed through an HTTP header in the following format:

Authorization: Bearer <auth_token>

JSON Schemas

Error

{
    "code": <string>
    "text": <string>
}
Parameter Description
code Code representing error
text Human readable message

Batch error

{
    "simcard_id": <string>
    "text": <string>
}
Parameter Description
simcard_id ID of the SIM card
text 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"
}
Parameter Description
id Unique SIM card ID
status Current SIM card status; possible values are: TEST, ACTIVE, SUSPENDED, TERMINATED
imei Current device IMEI or IMEISV; may be empty if not available
blocked true if this SIM card has been blocked
data.enabled Data is always enabled, so this is always true
data.limit Optional monthly data limit in KB
data.usage Data usage in KB for this calendar month
sms.enabled true if SMS capability has been enabled for this SIM card
sms.limit Optional monthly SMS limit, in number of messages
sms.usage Total number of sent and recieved messages for this calendar month
voice.enabled true if voice capability has been enabled for this SIM card
voice.limit Optional monthly voice limit, in minutes
voice.usage Total number of minutes consumed for this calendar month
location.network_id The current network ID (MCC/MNC); may be empty or partially available
created_at ISO-8601 timestamp for when this SIM card was created (registered)
updated_at ISO-8601 timestamp for when the metadata representing this SIM card was last updated

Job

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

API Operations

List SIM cards

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

Request

GET /iot/v1/:service_id/simcards?status=ACTIVE&blocked=true&page=4
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": [
        <simcard>
    ],
    "page": 4,
    "page_size": 10
}
Parameter 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_id/simcards/:simcard_id
Parameter Type Optional Default Description
simcard_id query false N/A SIM card ID

Response

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

<simcard>

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.

Request

POST /iot/v1/:service_id/simcards/:simcard_id/activate
Parameter Type Optional Default Description
simcard_id query false N/A SIM card ID

Response

HTTP/1.1 202 ACCEPTED
Location: /iot/v1/:service_id/jobs/:job_id

Example

$ curl -v -XPOST -H "Authorization: Bearer 0102030405060708090a0b0c0d0e0f10" \
https://api.clxcommunications.com/iot/v1/acmeiot001/simcards/89463189999999999999/activate
*   Trying 52.73.17.89...
* Connected to api.clxcommunications.com (52.73.17.89) port 443 (#0)
* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
* Server certificate: api.clxcommunications.com
* Server certificate: GlobalSign Organization Validation CA - SHA256 - G2
* Server certificate: GlobalSign Root CA
> POST / HTTP/1.1
> Host: api.clxcommunications.com
> User-Agent: curl/7.43.0
> Accept: */*
>
< HTTP/1.1 202 Accepted
< Date: Thu, 1 Oct 2016 00:00:00 GMT
< Location: /iot/v1/acmeiot001/jobs/123e4567e89b12d3a456426655440000
< Connection: close
< Content-Length: 0
<
* Closing connection 0\u00a0

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_id/simcards/:simcard_id/block
Parameter Type Optional Default Description
simcard_id query false N/A SIM card ID

Response

HTTP/1.1 202 ACCEPTED
Location: /iot/v1/:service_id/jobs/:jobid

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_id/simcards/:simcard_id/unblock
Parameter Type Optional Default Description
simcard_id query false N/A SIM card ID

Response

HTTP/1.1 202 ACCEPTED
Location: /iot/v1/:service_id/jobs/:jobid

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_id/simcards/:simcard_id/reconnect
Parameter Type Optional Default Description
simcard_id query false N/A SIM card ID

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_id/simcards/:simcard_id/terminate
Parameter Type Optional Default Description
simcard_id query false N/A SIM card ID

Response

HTTP/1.1 202 ACCEPTED
Location: /iot/v1/:service_id/jobs/:jobid

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_id/simcards/:simcard_id/data
{
    "limit": 512
}
Parameter Type Optional Default Description
simcard_id query false N/A SIM card ID
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_id/jobs/:job_id

Update SMS

This operation is used to update the SMS service.

Request

POST /iot/v1/:service_id/simcards/:simcard_id/sms
{
    "enabled": true,
    "limit": 512
}
Parameter Type Optional Default Description
simcard_id query false N/A SIM card ID
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_id/jobs/:jobid

Update Voice

This operation is used to update the Voice service. In order to enable voice, the customer account needs to be provisioned for voice. This is done through your CLX account manager. Once voice is provisioned, customer can register its IP-PBX according to received instructions.

Request

POST /iot/v1/:service_id/simcards/:simcard_id/voice
{
    "enabled": true,
    "limit": 300
}
Parameter Type Optional Default Description
simcard_id query false N/A SIM card ID
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_id/jobs/:jobid

Send an SMS

Operation to send an SMS to one of your SIM cards is described in the request below. 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_id/simcards/:simcard_id/send_sms
{
    "from": "555555",
    "message": "This is the content of the message."
}
Parameter Type Optional Default Description
simcard_id query false N/A SIM card ID
from query false N/A The Application ID where the SMS is originating from, application ID is provided by your account manager
message query false N/A The content of the SMS

Response

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

{
    "message_id": "abcd1234"
}
Parameter Type Description
message_id string The tracking number of the 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"
}
Parameter Description
message_id Tracking number of the sent message
state SMPP status of the message
received_at Timestamp when the end device received and opened the message
type 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"
}
Parameter Description
from SIM card ID
to Application ID
message Message sent by the SIM card
type 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_id/callbackurl
{
    "url": "https://www.mydomain.com/iot/my_callback_url_endpoint"
}
Parameter Type Optional Default Description
url query false N/A Endpoint on customer 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 configured callback URL.

Request

GET /iot/v1/:service_id/callbackurl

Response

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

{
    "url": "https://www.mydomain.com/iot/my_callback_url_endpoint"
}
Parameter 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

Request

GET /iot/v1/:service_id/jobs?status=ERROR
Parameter Type Optional Default Description
status query true N/A Comma-separated list of statuses to filter on
simcard query true N/A Comma-separated list of SIM card IDs 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
}
Parameter 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

Request

GET /iot/v1/:service_id/jobs/:job_id
Parameter Type Optional Default Description
job_id query false N/A Job ID

Response

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

<job>

Fetch batch job

Request

GET /iot/v1/:service_id/batchjobs/:batch_job_id
Parameter Type Optional Default Description
batch_job_id query false N/A Batch Job ID

Response

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

<batch_job>

List jobs of a batch job

Request

GET /iot/v1/:service_id/batchjobs/:batch_job_id/jobs
Parameter Type Optional Default Description
batch_job_id query false N/A Batch Job ID
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
}
Parameter 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

Requests

See Activate SIM card.

POST /iot/v1/:service_id/activate

{
    "simcard_ids": [
                <string>
    ]
}
Parameter Type Optional Default Description
simcard_ids array false N/A List of SIM card IDs to perform the operation on, up to 100

See Block SIM card.

POST /iot/v1/:service_id/block

{
    "simcard_ids": [
                <string>
    ]
}
Parameter Type Optional Default Description
simcard_ids array false N/A List of SIM card IDs to perform the operation on, up to 100

See Unblock SIM card.

POST /iot/v1/:service_id/unblock

{
    "simcard_ids": [
                <string>
    ]
}
Parameter Type Optional Default Description
simcard_ids array false N/A List of SIM card IDs to perform the operation on, up to 100

See Terminate SIM card.

POST /iot/v1/:service_id/terminate

{
    "simcard_ids": [
                <string>
    ]
}
Parameter Type Optional Default Description
simcard_ids array false N/A List of SIM card IDs to perform the operation on, up to 100

See Update Data.

POST /iot/v1/:service_id/data
{
    "simcard_ids": [
                <string>
    ],
    "limit": 512
}
Parameter 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

See Update SMS.

POST /iot/v1/:service_id/sms
{
    "simcard_ids": [
                <string>
    ],
    "enabled": true,
    "limit": 512
}
Parameter 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

See Update Voice.

POST /iot/v1/:service_id/voice
{
    "simcard_ids": [
                <string>
    ],
    "enabled": true,
    "limit": 512
}
Parameter 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

Response

This is the response for all batch requests.

HTTP/1.1 202 ACCEPTED
Location: /iot/v1/:service_id/batchjobs/:batch_job_id
{
    "errors": [
            <batch_error>
    ]
}
Parameter Type Description
errors array List of SIM card IDs, and corresponding error messages, that were not valid for for the batch operation

HTTP Code Status

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.

Notes

  • Where there is a pending job for a SIM card, e.g. activation, any further operations on the same SIM, e.g. blocking, will fail.