Retrieve Reachability Status

Request for the Status of a Device Based on the Request Type:
POST /diagnostics/basic/devicereachability/status

This API enables a calling application to request the reachability status of a device based on the request type.

Contents

Uses and Requirements

Using this API, an enterprise application shall be able to request the reachability monitoring status of a device based on the request type.

Request

HTTP Request

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

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.
monitorType
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
requestExpirationTime
optional
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).
device
required
array of device objects The device for which you wish to retrieve the reachability report status.
device.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",
  "monitorType": "string",
  "requestExpirationTime": "string",
  "device": {
    "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.
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!