Send Non-IP Data (NIDD) to a Device

POST /devices/nidd/message

Allows you to send Non-IP data to an NB-IoT device or from an NB-IoT Device to an application in a single API request.

Uses and Requirements

The API also allows the application to specify the maximum delivery time that the user wants to wait for the delivery of the data to the device.

The API has various responses and callbacks:

  • The API first provides a synchronous (200 OK) response after which it sends an asynchronous callback confirming the delivery of the data, if the device is immediately reachable. If the device is not reachable, then the asynchronous callback will inform the calling application that the data is buffered (queued) and will be sent when the device is reachable again.
  • The calling application gets another asynchronous callback, on NiddService, when the data is delivered to the device, as the device becomes reachable. If the data cannot be delivered to the device within the maximum delivery time, then the calling application gets the asynchronous callback informing that data could not be delivered in the time specified.
  • The calling application gets an aysnchronous callback, on NiddService, when the NB-IoT device sends data back to the application. This data is typically small amounts of data that is typical for small-data, low-power devices, such as gas meters, water meters or other devices that use less than 50kb of data. These transmissions require minimal power.

You must register the NiddService as a callback listener.

NOTE: This API currently supports NB-IoT devices only.

HTTP Request

POST https://thingspace.verizon.com/api/m2m/v1/devices/nidd/message

Header Parameters

Parameter Name Data Type Description
Authorization
required 		string HTTP Authorization bearer token.
VZ-M2M Token
required		 string A valid session token returned by POST /api/m2m/v1/session/login
Content Type
required		 string Must be application/json

Request Body

Parameter Name Data Type Description
deviceIds
required		 device identifier object Object identifies the device that you want to send NIDD data to:
  • id: device identifier value; Required for IoT devices; not needed for consumer devices.
  • kind: the type of identifier (IMEI, IMSI, MDN, MIN, MSISDN, ICCID, EID); Required for IoT devices; not needed for consumer devices.
accountName
required		 string The name of a billing account, which is usually in the form of 10 digits, a hyphen, and then five more digits. Must include any leading zeros.
maximumDeliveryTime
required		 integer

Identifies the maximum time for the delivery of the data to the device, in units of seconds.

The allowed range is 2 secs -- 2592000 secs (30 days)
messsage
required		 string(byte)

Base64-encoded binary message.

The maximum size of the data can be 10864 bit or 1358 bytes.

Example Request Body

{
    "deviceIds": [
        {
            "id": "9998501090",
            "kind": "MDN"
        }
    ],
    "accountName": "9999080353-00001",
    "maximumDeliveryTime": "400",
    "message": "SEVMTE8="
}

HTTP Response

Status 200

Success Response with the body of the response includes transaction ID that can be used to correlate the callbacks.

Parameter Name Data Type Description
requestId string

A unique string that associates the request with the NIDD information that is sent in asynchronous callback messages.

ThingSpace sends a separate callback message for each device that was in the request. All of the callback messages have the same requestId.

Example Success Response

Status 200

{
  "requestId": "595ffce4-c31c-4552-8670-020a1545a84d"
}

niddMT delivery Callback Parameters

Common parameters for each callback

Parameter Name Data Type Description
requestId
required 		string

A unique string that associates the request with the NIDD information that is sent in asynchronous callback messages.

ThingSpace sends a separate callback message for each device that was in the request. All of the callback messages have the same requestId.
deviceIds
required		 array of device identifer objects

Only one object with {kind,id}, where "kind" shall be the same as the one in the initial request.

  • kind: the type of the identifier (IMEI, IMSI, MDN, MIN, MSISDN, ICCID, EID)
  • id: a device identifier value
Status
required		 string

Valid values include: 

  • Delivered
  • Queued
  • DeliveryFailed
callbackCount integer Total number of callback requests.
maxCallbackThreshold integer Maximum number of callbacks allowed.

nidd Mobile-terminating(MT) DeliveryResponse Parameters

Parameter Name Data Type Description
deviceIds Array of device identifier objects

All of the non-null device identifers for the device:

  • kind: the type of the identifier (IMEI, IMSI, MDN, MIN, MSISDN, ICCID, EID)
  • id: a device identifier value
niddResponse array of niddResponse objects niddResponse object
niddResponse.niddMTDeliveryResponse.accountName
required		 string The name of a billing account, which is usually in the format of 10 digits, a hyphen, and then five more digits. Must include any leading zeros    
niddResponse.niddMTDeliveryResponse.acknowledgeTime
required		 string

Identifies the absolute time at which the device receiving data is acknowledged by Network (SCEF).

The format should be aligned with RFC3339, example: "2017-12-19T16:39:57-08:00" (in UTC passed as String)    
niddResponse.niddMTDeliveryResponse.firstAttemptDeliveryTime string Identifies the absolute time at which the data is attempted to send data to the device for the first time, as device becomes reachable then.
niddResponse.niddMTDeliveryResponse.reason string

This displays only if the status is Failed. Valid values include:

  • Buffered, device not reachable
  • Timeout, could not deliver data
  • Unknown
  • NIDD MT payload exceeds the defined limit

Receive Non-IP Data  (NIDD) from a Device

nidd Mobile-originating(MO) Callback Parameters

This callback allows you to receive non-IP data from an NB-IoT device in an asynchronous callback to the NiddService.

Parameter Name Data Type Description
deviceIds
 array of device identifer objects

Only one object with {kind,id} where kind shall be the same as the one in the initial request.

  • kind: the type of identifier (IMEI, IMSI, MDN, MIN, MSISDN, ICCID, EID)
  • id: a device identifier value.
niddResponse niddResponse object NiddService response object
niddResponse.niddMONotificationResponse.accountName string The name of a billing account, which is usually in the format of 10 digits, a hyphen, and then five more digits. Must include any leading zeros.
niddResponse.niddMONotificationResopnse.message string(byte) Base64-encoded binary message.
niddResponse.niddMONotificationResponse.deviceIds array of device identifer objects

Only one object with {kind,id} where kind shall be the same as the one in the initial request.

  • kind: the type of identifier (IMEI, IMSI, MDN, MIN, MSISDN, ICCID, EID)
  • id: a device identifier value.

Example Success Callback Responses

Data Delivered Acknowledgement (device is reachable immediately)

{
    "username": "user",
    "password": "pwd",
    "requestId": "aeb0ed2f-76fa-4bc3-b8fd-034c980a9130",
    "deviceIds": [
        {
            "id": "9996991028",
            "kind": "MDN"
        }
    ],
    "niddResponse": {
        "niddMTDeliveryResponse": {
            "accountName": "9999080353-00001",
            "acknowledgeTime": "Mon Aug 24 19:57:23 GMT 2020",
            "deviceIds": [
                {
                    "id": "999402461083796",
                    "kind": "IMEI"
                },
                {
                    "id": "311270005681999",
                    "kind": "IMSI"
                },
                {
                    "id": "9996991028",
                    "kind": "MDN"
                },
                {
                    "id": "9996991028",
                    "kind": "MIN"
                },
                {
                    "id": "19996991028",
                    "kind": "MSISDN"
                },
                {
                    "id": "99948000005795977263",
                    "kind": "ICCID"
                }
            ]
        }
    },
    "status": "Delivered",
    "callbackCount": 1,
    "maxCallbackThreshold": 4
}

Data is Buffered (device is not reachable immediately)

{
    "username": "user",
    "password": "pwd",
    "requestId": "a5beeef6-3086-412e-ba15-689ba866e525",
    "deviceIds": [
        {
            "id": "9996991028",
            "kind": "MDN"
        }
    ],
    "niddResponse": {
        "niddMTDeliveryResponse": {
            "accountName": "9999080353-00001",
            "firstAttemptDeliveryTime": "2020-08-24T20:06:15Z",
            "reason": "Buffered, device not reachable",
            "deviceIds": [
                {
                    "id": "999402461083796",
                    "kind": "IMEI"
                },
                {
                    "id": "311270005681999",
                    "kind": "IMSI"
                },
                {
                    "id": "9996991028",
                    "kind": "MDN"
                },
                {
                    "id": "9996991028",
                    "kind": "MIN"
                },
                {
                    "id": "19996991028",
                    "kind": "MSISDN"
                },
                {
                    "id": "99948000005795977263",
                    "kind": "ICCID"
                }
            ]
        }
    },
    "status": "Queued",
    "callbackCount": 1,
    "maxCallbackThreshold": 4
}

Data cannot be delivered (device is not reachable within max delivery time)

{
    "username": "user",
    "password": "pwd",
    "requestId": "ddeeeaa3-f58a-423c-a348-f52512dc0873",
    "deviceIds": [
        {
            "id": "9998501090",
            "kind": "MDN"
        }
    ],
    "niddResponse": {
        "niddMTDeliveryResponse": {
            "accountName": "9999080353-00001",
            "reason": "unknown",
            "deviceIds": [
                {
                    "id": "999402461083754",
                    "kind": "IMEI"
                },
                {
                    "id": "311480852590999",
                    "kind": "IMSI"
                },
                {
                    "id": "9998501090",
                    "kind": "MDN"
                },
                {
                    "id": "9998501090",
                    "kind": "MIN"
                },
                {
                    "id": "19998501090",
                    "kind": "MSISDN"
                },
                {
                    "id": "99948000004347398194",
                    "kind": "ICCID"
                }
            ]
        }
    },
    "status": "DeliveryFailed",
    "callbackCount": 1,
    "maxCallbackThreshold": 4
}

Mobile-originating(MO) Callback Response

This callback allows you to receive non-IP data from an NB-IoT device in an asynchronous callback to the NiddService.

 

{
    "username": "user",
    "password": "pwd",
    "requestId": "a0fff7d6-6b30-45eb-84d7-0bc103d319c0",
    "deviceIds": [
        {
            "id": "999402461083754",
            "kind": "IMEI"
        }
    ],
    "niddResponse": {
        "niddMONotificationResponse": {
            "accountName": "9999080353-00001",
            "message": "QUJD",
            "deviceIds": [
                {
                    "id": "999402461083754",
                    "kind": "IMEI"
                },
                {
                    "id": "311480852590999",
                    "kind": "IMSI"
                },
                {
                    "id": "9998501090",
                    "kind": "MDN"
                },
                {
                    "id": "9998501090",
                    "kind": "MIN"
                },
                {
                    "id": "19998501090",
                    "kind": "MSISDN"
                },
                {
                    "id": "99948000004347398194",
                    "kind": "ICCID"
                }
            ]
        }
    },
    "callbackCount": 1,
    "maxCallbackThreshold": 4
}

Success Response

Status 200

Success Response with no body

Failure Response

Status 400:

Error Code Error Message  Occurs When Resolution
INPUT_INVALID.Message.Null     Message cannot be null.    The NIDD Message request did not include a value for message.

Set the message value to the string that you want to send to the devices, and then retry the request.
INPUT_INVALID.DeviceNotProvided deviceIds cannot be null. The NIDD message request did not include a value for deviceIds.

Set the deviceIds value to the device that you want to send to, and then retry the request.
INPUT_INVALID. DeliveryTimeout.InvalidFormat     maximumDeliveryTime can only be Integer     The NIDD message request did not include valid value for maximumDeliveryTime.    

Set the maximumDeliveryTime value in Integer format only, and then retry the request.