Retrieve Active Reachablity Monitoring

Retrieve All Active Reachability Monitoring Events:
POST /diagnostics/basic/devicereachability/monitors

This API enables a calling application to retrieve active reachability monitoring events.

Contents

Uses and Requirements

Using this API, an enterprise application shall be able to retrieve all outstanding (active) requested reachability monitoring (DATA, SMS, LOSS_OF_CONN) events.

Request

HTTP Request

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

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 retrieve active reachability monitoring status
devices.deviceIds
required
array of device identifiers The identifiers of the devices for which you wish to retrieve active reachability monitoring 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

Example Request Body

{
  "accountName": "string",
  "requestType": "string",
  "devices": [
    {
      "deviceIds": [
        {
          "id": "string",
          "kind": "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.
requestID
required
string A unique string that associates the request with the monitor information.
deviceMonitorReportList
required
Array of deviceMonitorReport objects Optional - Included only if there is atleast one active monitor to report deviceIds Mandatory 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
monitoringEventType
optional
string Type of reachability monitoring request.
  • REACHABLE_FOR_DATA,
  • REACHABLE_FOR_SMS,
  • LOSS_OF_CONNECTIVITY
This is not needed if monitoringEventType is specified in Original Request. As then this report would contain monitorIDs for only that specific monitorEventType anyways (as requested in Original devicemonitorreport Request) and is implied.
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
monitorStartTime
required
string Identifies the absolute time at which the monitoring was started. The format should be aligned with RFC3339, example: “2017-12-19T16:39:57-08:00” (in UTC passed as String).
monitorEndTime
required
string Identifies the absolute time at which the monitoring will end. The format should be aligned with RFC3339, example: “2017-12-19T16:39:57-08:00” (in UTC passed as String).
pageNumber
required
integer Index of the current block of 1000 monitors included in this callback report. if there are no active monitors for the set of devices requested by user, then this shall be set to 1.
totalPages
required
integer Total number of blocks in entire report; if there are no active monitors for the set of devices requested by user, then this shall be set to 1.

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!