Send Non-IP Data (NIDD) to a Device

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)	object	Identifies the device that you want to send NIDD data to using a kind and id value.
id (required for deviceId)	string	device identifier value.
kind (required for deviceId)	string	The type of identifier (IMEI, IMSI, MDN, MIN, MSISDN, ICCID, EID).
accountName (required)	string	The name of a billing account, 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 between 2 secs and 2592000 secs (30 days).
messsage (required)	string	A base64-encoded binary message. The maximum size of the data can be 10864 bits or 1358 bytes.

Example Request Body

{    "deviceIds": [        {            "id": "10-digit phone number",            "kind": "MDN"        }    ],    "accountName": "0000123456-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 (UUID) 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 for individual requests have the same `requestId`.

Example Success Response

Status 200

{  "requestId": "595ffce4-eeee-ffff-gggg-020a1545a84d"}

niddMT delivery Callback Parameters

Common parameters for each callback

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 for an individual query have the same `requestId`.
deviceIds	object	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	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	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	niddResponse object
accountName	string	The name of a billing account, in the format of 10 digits, a hyphen and then five more digits. Must include any leading zeros.
acknowledgeTime	string	Identifies the absolute time at which the device receiving data is acknowledged by the Service Capability Exposure Function (SCEF). The format should be aligned with RFC3339. Example: "2017-12-19T16:39:57-08:00" (in UTC passed as a String).
firstAttemptDeliveryTime	string	Identifies the absolute time at which the data send is attempted to the device for the first time, as device becomes reachable.
niddMTDeliveryResponse	string	will show as Success if delivery completes or Failed if delivery does not complete.
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

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
username	string	The user name making the request.
password	string	The password of the user making the request.
requestId	string	The UUID of the request made.
deviceIds	array	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	object	`NiddService` response object.
niddMONotificationResponse	object	The response data.
accountName	string	The name of a billing account, in the format of 10 digits, a hyphen and then five more digits. Must include any leading zeros.
acknowledgeTime	string	Identifies the absolute time at which the device receiving data is acknowledged by the Service Capability Exposure Function (SCEF). The format should be aligned with RFC3339. Example: "2017-12-19T16:39:57-08:00" (in UTC passed as a String).
deviceIds	array	An array of objects with {kind,id} showing additional/alternate kind values to the one used in the initial request. kind: the type of identifier (IMEI, IMSI, MDN, MIN, MSISDN, ICCID, EID) id: a device identifier value.
status	string	Indicates if the data has been delivered or not. Valid responses include Queued, Deliveed or DeliveryFailed.
callbackCount	integer	The number of callbacks associated with this request ID.
maxCallbackThreshold	integer	The maximum number of callbacks allowed for this request ID.

Example Success Callback Responses

Data Delivered Acknowledgement (device is reachable immediately)

{    "username": "user",    "password": "pwd",    "requestId": "595ffce4-eeee-ffff-gggg-020a1545a84d",    "deviceIds": [        {            "id": "10-digit phone number",            "kind": "MDN"        }    ],    "niddResponse": {        "niddMTDeliveryResponse": {            "accountName": "0000123456-00001",            "acknowledgeTime": "2017-12-19T16:39:57-08:00",            "deviceIds": [                {                    "id": "15-digit IMEI",                    "kind": "IMEI"                },                {                    "id": "15-digit IMSI",                    "kind": "IMSI"                },                {                    "id": "10-digit phone number",                    "kind": "MDN"                },                {                    "id": "10-digit phone number",                    "kind": "MIN"                },                {                    "id": "1+ 10-digit phone number",                    "kind": "MSISDN"                },                {                    "id": "20-digit ICCID",                    "kind": "ICCID"                }            ]        }    },    "status": "Delivered",    "callbackCount": 1,    "maxCallbackThreshold": 4}

Data is Buffered (device is not reachable immediately)

{    "username": "user",    "password": "pwd",    "requestId": "595ffce4-eeee-ffff-gggg-020a1545a84d",    "deviceIds": [        {            "id": "10-digit phone number",            "kind": "MDN"        }    ],    "niddResponse": {        "niddMTDeliveryResponse": {            "accountName": "0000123456-00001",            "firstAttemptDeliveryTime": "2020-08-24T20:06:15Z",            "reason": "Buffered, device not reachable",            "deviceIds": [                {                    "id": "15-digit IMEI",                    "kind": "IMEI"                },                {                    "id": "15-digit IMSI",                    "kind": "IMSI"                },                {                    "id": "10-digit phone number",                    "kind": "MDN"                },                {                    "id": "10-digit phone number",                    "kind": "MIN"                },                {                    "id": "1+ 10-digit phone number",                    "kind": "MSISDN"                },                {                    "id": "20-digit ICCID",                    "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": "595ffce4-eeee-ffff-gggg-020a1545a84d",    "deviceIds": [        {            "id": "10-digit phone number",            "kind": "MDN"        }    ],    "niddResponse": {        "niddMTDeliveryResponse": {            "accountName": "0000123456-00001",            "reason": "unknown",            "deviceIds": [                {                    "id": "15-digit IMEI",                    "kind": "IMEI"                },                {                    "id": "15-digit IMSI",                    "kind": "IMSI"                },                {                    "id": "10-digit phone number",                    "kind": "MDN"                },                {                    "id": "10-digit phone number",                    "kind": "MIN"                },                {                    "id": "1+ 10-digit phone number",                    "kind": "MSISDN"                },                {                    "id": "20-digit ICCID",                    "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": "595ffce4-eeee-ffff-gggg-020a1545a84d",    "deviceIds": [        {            "id": "15 digit IMEI",            "kind": "IMEI"        }    ],    "niddResponse": {        "niddMONotificationResponse": {            "accountName": "0000123456-00001",            "message": "QUJD",            "deviceIds": [                {                    "id": "15-digit IMEI",                    "kind": "IMEI"                },                {                    "id": "15-digit IMSI",                    "kind": "IMSI"                },                {                    "id": "10-digit phone number",                    "kind": "MDN"                },                {                    "id": "10-digit phone number",                    "kind": "MIN"                },                {                    "id": "1+ 10-digit phone number",                    "kind": "MSISDN"                },                {                    "id": "20-digit ICCID",                    "kind": "ICCID"                }            ]        }    },    "callbackCount": 1,    "maxCallbackThreshold": 4}

Alternate Success Response

Status 200

Success Response with no body

Failure Response

Typical error responses include:

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.

## Send Non-IP Data (NIDD) to a Device ### 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)* | object | Identifies the device that you want to send NIDD data to using a kind and id value. | | **id** *(required for deviceId)* | string | device identifier value. | | **kind** *(required for deviceId)* | string | The type of identifier (IMEI, IMSI, MDN, MIN, MSISDN, ICCID, EID). | | **accountName** *(required)* | string | The name of a billing account, 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 between 2 secs and 2592000 secs (30 days). | | **messsage** *(required)* | string | A base64-encoded binary message. The maximum size of the data can be 10864 bits or 1358 bytes. | ### Example Request Body ```json { "deviceIds": [ { "id": "10-digit phone number", "kind": "MDN" } ], "accountName": "0000123456-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 (UUID) 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 for individual requests have the same `requestId`. | ### Example Success Response **Status 200** ```json { "requestId": "595ffce4-eeee-ffff-gggg-020a1545a84d" } ``` ### niddMT delivery Callback Parameters Common parameters for each callback | 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 for an individual query have the same `requestId`. | | **deviceIds** | object | 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** | 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 | 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 | niddResponse object | | **accountName** | string | The name of a billing account, in the format of 10 digits, a hyphen and then five more digits. Must include any leading zeros. | | **acknowledgeTime** | string | Identifies the absolute time at which the device receiving data is acknowledged by the Service Capability Exposure Function (SCEF). The format should be aligned with [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339). Example: "2017-12-19T16:39:57-08:00" (in UTC passed as a String). | | **firstAttemptDeliveryTime** | string | Identifies the absolute time at which the data send is attempted to the device for the first time, as device becomes reachable. | | **niddMTDeliveryResponse** | string | will show as Success if delivery completes or Failed if delivery does not complete. | | **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 | ### 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 | |----------------------------------|-----------------------------------|-----------------------------------| | **username** | string | The user name making the request. | | **password** | string | The password of the user making the request. | | **requestId** | string | The UUID of the request made. | | **deviceIds** | array | 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** | object | `NiddService` response object. | | **niddMONotificationResponse** | object | The response data. | | **accountName** | string | The name of a billing account, in the format of 10 digits, a hyphen and then five more digits. Must include any leading zeros. | | **acknowledgeTime** | string | Identifies the absolute time at which the device receiving data is acknowledged by the Service Capability Exposure Function (SCEF). The format should be aligned with [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339). Example: "2017-12-19T16:39:57-08:00" (in UTC passed as a String). | | **deviceIds** | array | An array of objects with {kind,id} showing additional/alternate kind values to the one used in the initial request. kind: the type of identifier (IMEI, IMSI, MDN, MIN, MSISDN, ICCID, EID) id: a device identifier value. | | **status** | string | Indicates if the data has been delivered or not. Valid responses include **Queued**, **Deliveed** or **DeliveryFailed**. | | **callbackCount** | integer | The number of callbacks associated with this request ID. | | **maxCallbackThreshold** | integer | The maximum number of callbacks allowed for this request ID. | ### Example Success Callback Responses Data Delivered Acknowledgement (device is reachable immediately) ```json { "username": "user", "password": "pwd", "requestId": "595ffce4-eeee-ffff-gggg-020a1545a84d", "deviceIds": [ { "id": "10-digit phone number", "kind": "MDN" } ], "niddResponse": { "niddMTDeliveryResponse": { "accountName": "0000123456-00001", "acknowledgeTime": "2017-12-19T16:39:57-08:00", "deviceIds": [ { "id": "15-digit IMEI", "kind": "IMEI" }, { "id": "15-digit IMSI", "kind": "IMSI" }, { "id": "10-digit phone number", "kind": "MDN" }, { "id": "10-digit phone number", "kind": "MIN" }, { "id": "1+ 10-digit phone number", "kind": "MSISDN" }, { "id": "20-digit ICCID", "kind": "ICCID" } ] } }, "status": "Delivered", "callbackCount": 1, "maxCallbackThreshold": 4 } ``` Data is Buffered (device is not reachable immediately) ```json { "username": "user", "password": "pwd", "requestId": "595ffce4-eeee-ffff-gggg-020a1545a84d", "deviceIds": [ { "id": "10-digit phone number", "kind": "MDN" } ], "niddResponse": { "niddMTDeliveryResponse": { "accountName": "0000123456-00001", "firstAttemptDeliveryTime": "2020-08-24T20:06:15Z", "reason": "Buffered, device not reachable", "deviceIds": [ { "id": "15-digit IMEI", "kind": "IMEI" }, { "id": "15-digit IMSI", "kind": "IMSI" }, { "id": "10-digit phone number", "kind": "MDN" }, { "id": "10-digit phone number", "kind": "MIN" }, { "id": "1+ 10-digit phone number", "kind": "MSISDN" }, { "id": "20-digit ICCID", "kind": "ICCID" } ] } }, "status": "Queued", "callbackCount": 1, "maxCallbackThreshold": 4 } ``` Data cannot be delivered (device is not reachable within max delivery time) ```json { "username": "user", "password": "pwd", "requestId": "595ffce4-eeee-ffff-gggg-020a1545a84d", "deviceIds": [ { "id": "10-digit phone number", "kind": "MDN" } ], "niddResponse": { "niddMTDeliveryResponse": { "accountName": "0000123456-00001", "reason": "unknown", "deviceIds": [ { "id": "15-digit IMEI", "kind": "IMEI" }, { "id": "15-digit IMSI", "kind": "IMSI" }, { "id": "10-digit phone number", "kind": "MDN" }, { "id": "10-digit phone number", "kind": "MIN" }, { "id": "1+ 10-digit phone number", "kind": "MSISDN" }, { "id": "20-digit ICCID", "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. ```json { "username": "user", "password": "pwd", "requestId": "595ffce4-eeee-ffff-gggg-020a1545a84d", "deviceIds": [ { "id": "15 digit IMEI", "kind": "IMEI" } ], "niddResponse": { "niddMONotificationResponse": { "accountName": "0000123456-00001", "message": "QUJD", "deviceIds": [ { "id": "15-digit IMEI", "kind": "IMEI" }, { "id": "15-digit IMSI", "kind": "IMSI" }, { "id": "10-digit phone number", "kind": "MDN" }, { "id": "10-digit phone number", "kind": "MIN" }, { "id": "1+ 10-digit phone number", "kind": "MSISDN" }, { "id": "20-digit ICCID", "kind": "ICCID" } ] } }, "callbackCount": 1, "maxCallbackThreshold": 4 } ``` ### Alternate Success Response **Status 200** Success Response with no body ### Failure Response Typical error responses include: | 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. |

Verizon 5G Edge API Portal

Send Non-IP Data (NIDD) to a Device