## Asynchronous Request for Monitoring Reachability and Loss-Of-Connectivity Status of the Devices Over a Duration ### Uses and Requirements The API allows specifying reachability for IP Data, SMS, and Loss of Connectivity in any combination in a single API request. The API also allows the application to specify the monitoring expiration time, which could amount to up to 10 years (3650 days) of monitoring duration for a set of devices. The API can be used in bulk mode, where multiple device identifiers can be supplied in the API request. All devices detected as duplicates are considered a single request for all such devices for the purpose of the API call instance. The API first provides a synchronous (200 OK) response after which it sends an asynchronous callback confirming the registration of the monitoring request for the duration. Those asynchronous callback notifications [require a callback to be registered](https://thingspace.verizon.com/documentation/api-documentation.html#/http/connectivity-management/api-endpoints/connectivity-callbacks/register-callback/api-reference) using **DiagnosticService**. This callback may contain the reachability status of the device only if the device is reachable. The calling application gets individual (per device) callbacks providing updates to the reachability status (as specified in the request) for the entire duration of monitoring. The expected frequency of such updates from a single device is dependent on the sleep mode timer settings for the device (using the worst-case assumption that the device does not initiate data itself). ### Request Components HTTP Request [POST https://thingspace.verizon.com/api/m2m/v1/diagnostics/basic/devicereachability](/docs/standard-apis/connectivity-management/api-endpoints/device-monitoring/device-reachability/devicereachability) Query Parameters None. ### 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 | |:-------------------------------:|:----------------------------------:|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:| | **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. | | **devices** *(required)* | Array of device identifier objects | Each object in the array identifies a device that you want to know reachability: kind: the type of the identifier (IMEI, MDN, MSISDN, ICCID); Required for IoT devices; not needed for consumer devices. id: a device identifier value; Required for IoT devices; not needed for consumer devices. Note: the kind has to be the same across the list, mixed kind is not supported today. | | **requestType** *(required)* | String | Valid values include: **REACHABLE_FOR_DATA REACHABLE_FOR_SMS REACHABLE_FOR_DATA_SMS LOSS_OF_CONNECTIVITY REACHABLE_FOR_DATA_AND_LOSS REACHABLE_FOR_SMS_AND_LOSS REACHABLE_FOR_DATA_SMS_AND_LOSS** | | **monitorExpirationTime** *(required)* | String | Identifies the absolute time at which the reachability request is considered to expire, from 6 months to 10 years. The format should be aligned with RFC3339, example: “2017-12-19T16:39:57-08:00” (in UTC passed as a String) Minimum 6 months to 10 years Maximum (up to 3650 days). | Example Request Body: ```json { "accountName": "0000123456-00001", "requestType": "REACHABLE_FOR_DATA", "devices": [ { "deviceIds": [ { "id": "89148000004292933820", "kind": "ICCID" }, { "id": "89148000003164287919", "kind": "ICCID" } ] } ], "monitorExpirationTime": "2019-12-02T15:00:00-08:00Z" } ``` ### Success Response **Status 200** Success Response with the body of the response includes requestID that can be used to correlate the callbacks. | Parameter Name | Data Type | Description | |:--------------:|:---------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:| | **requestID** | string | A unique string that associates the request with the reachability information that is sent in asynchronous callback message (Callback Service set to “DiagnosticsService”). ThingSpace sends a separate callback message for each device that was in the request. All of the callback messages have the same requestID (tansactionID). | Example Success Response: Status 200 ```json { "requestId": "595f5c44-c31c-4552-8670-020a1545a84d" } ``` ### Error response Status 400 Failure Response with the body of the response includes errorResponse. | Parameter Name | Data Type | Description | |:--------------:|:--------------------:|:----------------------------------------------------------:| | **errorResponse** | object | errorResponse object contains: errorCode errorMessage | Error codes and messages are listed on the Error Codes page, along with explanations and suggestions for corrective actions. ### Reachability Callback Parameters | Parameter Name | Data Type | Description | | ------------------------------------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **requestId** | string | A unique string that associates the request with the reachability information that is sent in asynchronous callback message. ThingSpace sends a separate callback message for each device that was in the request. All of the callback messages have the same requestId. | | **deviceIds** | array | Only An array of objects with {kind, id} where kind shall be same as the one in initial request from customer: **kind**: the type of the identifier (IMEI, MDN, MSISDN, ICCID) **id**: a device identifier value | | **status** | String | Success, Failed | | diagnosticsResponse.deviceReachabilityResponse.deviceIdentifierCollection | Array of device identifier objects | All the non-null device identifiers for the device: kind: the type of the identifier (IMEI, MDN, MSISDN, ICCID) id: a device identifier value Only included in Initial Callback of registration of event | | diagnosticsResponse.deviceReachabilityResponse.monitorId | String | The ID of the registered monitor (UUID), which could be used by the customer when stopping the monitoring on this particular monitor. This field is present only if status is SUCCESS. | | diagnosticsResponse.deviceReachabilityResponse.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. | | diagnosticsResponse.deviceReachabilityResponse.reportedTime required | String | Identifies the absolute time at which the reachability report is received from SCEF. The format should be aligned with RFC3339, example: “2017-12-19T16:39:57-08:00” (in UTC passed as String) | | diagnosticsResponse.deviceReachabilityResponse.registrationType | String | Valid values include: EVENT_REGISTER_FOR_DATA EVENT_REGISTER_FOR_SMS EVENT_REGISTER_FOR_CONNECTION_LOSS Only included in Initial Callback of registration of event | | diagnosticsResponse.deviceReachabilityResponse.reason | String | “Internal error”, “Device doesn’t belong to the account” Only included if status is Failed | | diagnosticsResponse.deviceReachabilityResponse.notificationReport | String | Valid values include: REACHABLE_FOR_DATA REACHABLE_FOR_SMS LOSS_OF_CONNECTIVITY | | diagnosticsResponse.deviceReachabilityResponse.MaxUEAvailabilityTime | DateTime | The timestamp (UTC) until which a device using a power-saving mechanism (CAT M or NB-IoT device) is expected to be reachable for DATA/SMS Delivery. Only sent when notificationReport value is REACHABLE_FOR_DATA/REACHABLE_FOR_SMS. This parameter will not be present if the device is anything other than a CAT-M or NB-IOT device. For CAT-M or NB-IOT device, this parameter may only be present if it is generated for PSM/eDRX wakeups; it may not be provided in other cases. | Example Success Callback Responses Register Success for DATA with callback (Device Sleeping): ```json { "username" : "user", "password" : "pwd", "requestId" : "7a110138-9532-400e-bdb9-29c1b7309446", "deviceIds" : [ { "id" : "89148001113852613236", "kind" : "ICCID" } ], "diagnosticsResponse" : { "deviceReachabilityResponse" : { "deviceIdentifierCollection" : [ { "id" : "865284098763723", "kind" : "IMEI" }, { "id" : "311270000033319", "kind" : "IMSI" }, { "id" : "6197823337", "kind" : "MDN" }, { "id" : "6194013229", "kind" : "MIN" }, { "id" : "16197825597", "kind" : "MSISDN" }, { "id" : "89148004443852613236", "kind" : "ICCID" } ], "monitorId" : "c3dfe020-816d-4656-843f-a2cc3d42bbdf", "accountName" : "0242666520-00001", "reportedTime" : "10/9/2019 6:18:08 PM", "registrationType" : "EVENT_REGISTER_FOR_DATA" } }, "status" : "Success", "callbackCount" : 1, "maxCallbackThreshold" : 4 } ``` Register Success for DATA with callback (Device Sleeping): ```json { "username" : "user", "password" : "pwd", "requestId" : "7a110138-9532-400e-bdb9-29c1b7309446", "deviceIds" : [ { "id" : "89148001113852613236", "kind" : "ICCID" } ], "diagnosticsResponse" : { "deviceReachabilityResponse" : { "deviceIdentifierCollection" : [ { "id" : "865284098763723", "kind" : "IMEI" }, { "id" : "311270000033319", "kind" : "IMSI" }, { "id" : "6197823337", "kind" : "MDN" }, { "id" : "6194013229", "kind" : "MIN" }, { "id" : "16197825597", "kind" : "MSISDN" }, { "id" : "89148004443852613236", "kind" : "ICCID" } ], "monitorId" : "c3dfe020-816d-4656-843f-a2cc3d42bbdf", "accountName" : "0242666520-00001", "reportedTime" : "10/9/2019 6:18:08 PM", "registrationType" : "EVENT_REGISTER_FOR_CONNECTION_LOSS" } }, "status" : "Success", "callbackCount" : 1, "maxCallbackThreshold" : 4 } ``` Register Failed for SMS with callback (Device Sleeping): ```json { "username" : "user", "password" : "pwd", "requestId" : "7a110138-9532-400e-bdb9-29c1b7309446", "deviceIds" : [ { "id" : "89148001113852613236", "kind" : "ICCID" } ], "diagnosticsResponse" : { "deviceReachabilityResponse" : { "monitorId" : "5e84365e-0a6f-41de-9476-074e89cb7f63", "accountName" : "0242666520-00001", "reportedTime" : "10/9/2019 6:18:09 PM", "registrationType" : "EVENT_REGISTER_FOR_SMS", "reason" : "Internal error" } }, "status" : "Failed", "callbackCount" : 1, "maxCallbackThreshold" : 4 } ``` Register Success for DATA with callback (Device Awake): ```json { "username" : "user", "password" : "pwd", "requestId" : "7a110138-9532-400e-bdb9-29c1b7309446", "deviceIds" : [ { "id" : "89148001113852613236", "kind" : "ICCID" } ], "diagnosticsResponse" : { "deviceReachabilityResponse" : { "deviceIdentifierCollection" : [ { "id" : "865284098763723", "kind" : "IMEI" }, { "id" : "311270000033319", "kind" : "IMSI" }, { "id" : "6197823337", "kind" : "MDN" }, { "id" : "6194013229", "kind" : "MIN" }, { "id" : "16197825597", "kind" : "MSISDN" }, { "id" : "89148004443852613236", "kind" : "ICCID" } ], "monitorId" : "c3dfe020-816d-4656-843f-a2cc3d42bbdf", "accountName" : "0242666520-00001", "reportedTime" : "10/9/2019 6:18:08 PM", "registrationType" : "EVENT_REGISTER_FOR_DATA", "notificationReport" : "REACHABLE_FOR_DATA", "MaxUEAvailabilityTime" : "10/9/2019 6:22:08 PM" } }, "status" : "Success", "callbackCount" : 1, "maxCallbackThreshold" : 4 } ``` Register Success for SMS with callback (Device Awake): ```json { "username" : "user", "password" : "pwd", "requestId" : "7a110138-9532-400e-bdb9-29c1b7309446", "deviceIds" : [ { "id" : "89148001113852613236", "kind" : "ICCID" } ], "diagnosticsResponse" : { "deviceReachabilityResponse" : { "deviceIdentifierCollection" : [ { "id" : "865284098763723", "kind" : "IMEI" }, { "id" : "311270000033319", "kind" : "IMSI" }, { "id" : "6197823337", "kind" : "MDN" }, { "id" : "6194013229", "kind" : "MIN" }, { "id" : "16197825597", "kind" : "MSISDN" }, { "id" : "89148004443852613236", "kind" : "ICCID" } ], "monitorId" : "c3dfe020-816d-4656-843f-a2cc3d42bbdf", "accountName" : "0242666520-00001", "reportedTime" : "10/9/2019 6:18:08 PM", "registrationType" : "EVENT_REGISTER_FOR_SMS", "notificationReport" : "REACHABLE_FOR_SMS", "MaxUEAvailabilityTime" : "10/9/2019 6:22:08 PM" } }, "status" : "Success", "callbackCount" : 1, "maxCallbackThreshold" : 4 } ``` Reachability Notification for DATA with callback (When Device comes out of Sleep): Note: Reachability Notification callback to have an original identifier ONLY that was passed in the request. ```json { "username" : "user", "password" : "pwd", "requestId" : "7a110138-9532-400e-bdb9-29c1b7309446", "deviceIds" : [ { "id" : "89148001113852613236", "kind" : "ICCID" } ], "diagnosticsResponse" : { "deviceReachabilityResponse" : { "monitorId" : "c3dfe020-816d-4656-843f-a2cc3d42bbdf", "accountName" : "0242666520-00001", "reportedTime" : "10/9/2019 6:18:08 PM", "notificationReport" : "REACHABLE_FOR_DATA", "MaxUEAvailabilityTime" : "10/9/2019 6:22:08 PM" } }, "status" : "Success", "callbackCount" : 1, "maxCallbackThreshold" : 4 } ``` Reachability Notification for SMS with callback (When Device comes out of Sleep): Note: Reachability Notification callback to have an original identifier ONLY that was passed in the request. ```json { "username" : "user", "password" : "pwd", "requestId" : "7a110138-9532-400e-bdb9-29c1b7309446", "deviceIds" : [ { "id" : "89148001113852613236", "kind" : "ICCID" } ], "diagnosticsResponse" : { "deviceReachabilityResponse" : { "monitorId" : "c3dfe020-816d-4656-843f-a2cc3d42bbdf", "accountName" : "0242666520-00001", "reportedTime" : "10/9/2019 6:18:08 PM", "notificationReport" : "REACHABLE_FOR_SMS", "MaxUEAvailabilityTime" : "10/9/2019 6:22:08 PM" } }, "status" : "Success", "callbackCount" : 1, "maxCallbackThreshold" : 4 } ```