Monitor Device Reachability

Asynchronous Request for Monitoring Reachability and Loss-Of-Connectivity Status of the Devices Over a Duration:
POST /diagnostics/basic/devicereachability

This API enables a calling application to make an asynchronous request to begin monitoring the reachability status of 4G devices.

Contents

Uses and Requirements

The API can be used in bulk mode (i.e., multiple device identifiers can be supplied in the API request). 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 of monitoring duration for a set of devices. 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. This callback may contain the reachability status of the device only if the device is reachable. The calling application will get 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 (assuming the device does not initiate data itself).

Request

HTTP Request

POST https://thingspace.verizon.com/api/m2m/v1/diagnostics/basic/devicereachability

Query Parameters

None.

Header Parameters

The request header must contain a current ThingSpace authorization bearer token and a valid VZ-M2M session token, and must set the content-type to JSON.

Parameter Name Data Type Description
Authorization
required
string HTTP Authorization bearer token.
VZ-M2M-Token
required
string A valid session token returned by POST /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. An account name is usually numeric, and must include any leading zeros.
requestType
required
string Type of reachability monitoring request.
  • 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
devices
required
array of device objects The devices for which you wish to monitor reachability and loss-of-connectivity status
devices.deviceIds
required
array of device identifiers The identifiers of the devices for which you wish to monitor reachability and loss-of-connectivity status
devices.deviceIds.kind,
id

required
strings The type and value of the device identifier.
  • ESN - decimal, 11 digits
  • ICCID - decimal, up to 20 digits
  • IMEI - decimal, up to 15 digits
  • MDN - decimal, 10 digits
  • MEID - hexadecimal, 14 characters
  • MSISDN - decimal, 11 digits
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 String). This parameter is optional. If not included, ThingSpace will start a timer for 1 hour (default value).

Example Request Body

{
  "accountName": "string",
  "requestType": "string",
  "devices": [
    {
      "deviceIds": [
        {
          "id": "string",
          "kind": "string"
        }
      ]
    }
  ],
  "monitorExpirationTime": "string"
}

Success Response

Status 200

Parameter Name Data Type Description
requestId string A unique string that associates the request with the results that are sent via a callback service.
The ThingSpace Platform will send a separate callback message for each device that matched the request criteria, indicating whether the operation succeeded for that device and containing any requested information. All of the callback messages will have the same requestId.

Example Success Response

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

Reachability Report Callback

Reachability Report Callback Parameters

Parameter Name Data Type Description
accountName
required
string The name of a billing account. An account name is usually numeric, and must include any leading zeros.
requestType
required
string Type of reachability monitoring request.
  • 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
devices
required
array of device objects The devices for which you wish to monitor reachability and loss-of-connectivity status
devices.deviceIds
required
Array of device identifier objects Only one object with {kind, id} where kind shall be same as the one in initial request from customer:
  • kind: the type of the identifier (IMEI, MSISDN, or External-ID)
  • id: a device identifier value
deviceIdentifierCollection
optional
string All the non-null device identifiers for the device:
  • kind: the type of the identifier (IMEI, MSISDN, or External-ID)
  • id: a device identifier value
Only included in Initial Callback of registration of event
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).
status
required
string
  • SUCCESS
  • FAILED
reason
optional
string
  • “monitoringExpirationTime is in the past”,
  • “monitoringExpirationTime cannot be more than 10 years in the future”,
  • “invalid reachabilityReqType”,
  • “deviceIdentifiers array cannot have size > 10000”,
  • “internal processing failure”,
  • “device not found”
registrationType
optional
string
  • EVENT_REGISTER_FOR_DATA
  • EVENT_REGISTER_FOR_SMS
  • EVENT_REGISTER_FOR_CONNECTION_LOSS
Only included in Initial Callback of registration of event
monitorID
optional
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
notificationReport
required
string
  • REACHABLE_FOR_DATA
  • REACHABLE_FOR_SMS
  • LOSS_OF_CONNECTIVITY

Example Success Callback Response #1

{
   "username":"user",
   "password":"user",
   "requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
   "deviceIds":[
      {
         "id":"666456789014008",
         "kind":"Imei"
      }
   ],
   "diagnosticsResponse":{
      "deviceReachabilityResponse":{
         "deviceIdentifierCollection":[
            {
               "id":"666456789014008",
               "kind":"imei"
            },
            {
               "id":"11245055053268336886",
               "kind":"iccid"
            },
            {
               "id":"2022326360",
               "kind":"mdn"
            },
            {
               "id":"666456789123456789123456784008",
               "kind":"eid"
            }
         ],
         "accountName":"SomeAccountName",
         "reportedTime":"2018-11-11T16:39:57-08:00",
         "monitorId":"12345-ece4-42ef-9f02-4434001",
         "registrationType":"data"
      }
   },
   "status":"success",
   "callbackCount":1,
   "maxCallbackThreshold":4
}

Example Success Callback Response #2

{
   "username":"user",
   "password":"user",
   "requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
   "deviceIds":[
      {
         "id":"666456789014008",
         "kind":"Imei"
      }
   ],
   "diagnosticsResponse":{
      "deviceReachabilityResponse":{
         "deviceIdentifierCollection":[
            {
               "id":"666456789014008",
               "kind":"imei"
            },
            {
               "id":"11245055053268336886",
               "kind":"iccid"
            },
            {
               "id":"2022326360",
               "kind":"mdn"
            },
            {
               "id":"666456789123456789123456784008",
               "kind":"eid"
            }
         ],
         "accountName":"SomeAccountName",
         "reportedTime":"2018-11-11T16:39:58-08:00",
         "monitorId":"12345-ece4-42ef-9f02-4434002",
         "registrationType":"sms"
      }
   },
   "status":"success",
   "callbackCount":1,
   "maxCallbackThreshold":4
}

Example Register Failure Callback Response #1

{
   "username":"user",
   "password":"user",
   "requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
   "deviceIds":[
      {
         "id":"666456789014008",
         "kind":"Imei"
      }
   ],
   "diagnosticsResponse":{
      "deviceReachabilityResponse":{
         "accountName":"SomeAccountName",
         "reportedTime":"2018-11-11T16:39:57-08:00",
         "reason":"Device not found",
         "registrationType":"data"
      }
   },
   "status":"failed",
   "callbackCount":1,
   "maxCallbackThreshold":4
}

Example Register Failure Callback Response #2

{
   "username":"user",
   "password":"user",
   "requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
   "deviceIds":[
      {
         "id":"666456789014008",
         "kind":"Imei"
      }
   ],
   "diagnosticsResponse":{
      "deviceReachabilityResponse":{
         "accountName":"SomeAccountName",
         "reportedTime":"2018-11-11T16:39:57-08:00",
         "reason":"Device not found",
         "registrationType":"sms"
      }
   },
   "status":"failed",
   "callbackCount":1,
   "maxCallbackThreshold":4
}

SCEF Registration Success with Notification Callback (when device is awake)

Callback #1 Register success with notification report - device awake

{
   "username":"user",
   "password":"user",
   "requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
   "deviceIds":[
      {
         "id":"666456789014008",
         "kind":"Imei"
      }
   ],
   "diagnosticsResponse":{
      "deviceReachabilityResponse":{
         "deviceIdentifierCollection":[
            {
               "id":"666456789014008",
               "kind":"imei"
            },
            {
               "id":"11245055053268336886",
               "kind":"iccid"
            },
            {
               "id":"2022326360",
               "kind":"mdn"
            },
            {
               "id":"666456789123456789123456784008",
               "kind":"eid"
            }
         ],
         "accountName":"SomeAccountName",
         "reportedTime":"2018-11-11T16:39:58-08:00",
         "monitorId":"12345-ece4-42ef-9f02-4434002",
         "registrationType":"data",
         "notificationReport":"data-reachable"
      }
   },
   "status":"success",
   "callbackCount":1,
   "maxCallbackThreshold":4
}

Callback #2 SCEF Register success with notification

{
   "username":"user",
   "password":"user",
   "requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
   "deviceIds":[
      {
         "id":"666456789014008",
         "kind":"Imei"
      }
   ],
   "diagnosticsResponse":{
      "deviceReachabilityResponse":{
         "deviceIdentifierCollection":[
            {
               "id":"666456789014008",
               "kind":"imei"
            },
            {
               "id":"11245055053268336886",
               "kind":"iccid"
            },
            {
               "id":"2022326360",
               "kind":"mdn"
            },
            {
               "id":"666456789123456789123456784008",
               "kind":"eid"
            }
         ],
         "accountName":"SomeAccountName",
         "reportedTime":"2018-11-11T16:39:58-08:00",
         "monitorId":"12345-ece4-42ef-9f02-4434002",
         "registrationType":"sms",
         "notificationReport":"sms-reachable"
      }
   },
   "status":"success",
   "callbackCount":1,
   "maxCallbackThreshold":4
}

2b Post SCEF Register Notification Callback (when the device comes out of sleep)

(Reachability Notification callback to have an original identifier that was passed in the request ONLY.)

Callback #1 Notification Callbacks

{
   "username":"user",
   "password":"user",
   "requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
   "deviceIds":[
      {
         "id":"666456789014008",
         "kind":"Imei"
      }
   ],
   "diagnosticsResponse":{
      "deviceReachabilityResponse":{
         "accountName":"SomeAccountName",
         "reportedTime":"2018-11-11T16:39:58-08:00",
         "notificationReport":"data-reachable"
      }
   },
   "status":"success",
   "callbackCount":1,
   "maxCallbackThreshold":4
}

Callback #2 Notification Callback

{
   "username":"user",
   "password":"user",
   "requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
   "deviceIds":[
      {
         "id":"666456789014008",
         "kind":"Imei"
      }
   ],
   "diagnosticsResponse":{
      "deviceReachabilityResponse":{
         "accountName":"SomeAccountName",
         "reportedTime":"2018-11-11T16:39:58-08:00",
         "notificationReport":"sms-reachable"
      }
   },
   "status":"success",
   "callbackCount":1,
   "maxCallbackThreshold":4
}

Failure Response

Status 400

All error messages are returned in this format:

{
  "errorCode": "error code string",
  "errorMessage": "error message string",
  "errorUrl": "error URL string"
}

Error codes and messages are listed on the Error Messages page, along with explanations and suggestions for corrective actions.

Try It Out!