Retrieve Reachability Status

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

Contents

Uses and Requirements

This API allows a calling application to request near real time status of reachability of a device within a stipulated time. This is a single device API (does not support bulk request operation). It provides a 200 OK synchronous response followed by a callback that conditionally provides a status in this callback if the device is indeed reachable. If a status is not provided in this callback (for example if the device is not reachable at the time of the request) , a second callback following the first one will provide the status (the application should be programmed accordingly in order to handle this scenario).

Request

HTTP Request

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

Query Parameters

None.

Header Parameters

Parameter Name Mandatory or Optional Data Type Description
Authorization Mandatory string HTTP Authorization bearer token.
VZ-M2M-Token Mandatory string A valid session token returned by POST /api/m2m/v1/session/login.
Content-Type Mandatory string Must be application/json.

Request Body

Parameter Name Mandatory or Optional Data Type Description
accountName Mandatory 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.
device Mandatory device identifier object Object identifies the 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: device identifier value; Required for IoT devices; not needed for consumer devices.
requestType Mandatory String REACHABLE_FOR_DATA, REACHABLE_FOR_SMS, LOSS_OF_CONNECTIVITY
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)

Limit to 10 years max (3650 days, to be precise).

Optional, if not included, ThingSpace will start a timer for 1 hour (default value).

Example Request Body

{
  "accountName": "0242072320-00001",
  "requestType": "REACHABLE_FOR_DATA",
  "requestExpirationTime": "2019-12-02T15:00:00-08:00Z",
  "device": {
    "id": "12016560696",
    "kind": "msisdn"
  }
}

Success Response

Status 200

Success Response with the body of the response includes request ID that can be used to correlate the callbacks.

Parameter Name Mandatory or Optional Data Type Description
requestID Mandatory 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 will send a separate callback message for each device that was in the request. All of the callback messages will have the same requestID.

Example Success Response

Status 200

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

Error response

Status 400

Failure Response with the body of the response includes errorResponse.

Parameter Name Mandatory or Optional Data Type Description
errorResponse Optional 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 Parameters

reachabilityStatus CallBack Parameters

Parameter Name Mandatory or Optional Data Type Description
requestId Mandatory string

A unique string that associates the request with the reachability information that is sent in asynchronous callback message.

ThingSpace will send a separate callback message for each device that was in the request. All of the callback messages will have the same requestId.

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, MDN, MSISDN, ICCID)
  • id: a device identifier value
status Mandatory String Success, Failed
diagnosticsResponse.deviceReachabilityResponse.deviceIdentifierCollection Optional 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 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.

diagnosticsResponse.deviceReachabilityResponse.accountName Mandatory 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 Mandatory 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 Optional String

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 Optional String

“Internal error”, “Device doesn’t belong to the account”

Only included if status is Failed

diagnosticsResponse.deviceReachabilityResponse.notificationReport Optional String REACHABLE_FOR_DATA
REACHABLE_FOR_SMS
LOSS_OF_CONNECTIVITY
STATUS_REQUEST_TIMEOUT

Example Success Callback Responses

Register Success for DATA with callback (Device Sleeping):

{
  "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 Connection Loss with callback (Device Sleeping):

{
  "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):

{
  "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):

{
  "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",
      "notificationReport" : "REACHABLE_FOR_DATA"
    }
  },
  "status" : "Success",
  "callbackCount" : 1,
  "maxCallbackThreshold" : 4
}

Register Success for SMS with callback (Device Awake):

{
  "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",
      "notificationReport" : "REACHABLE_FOR_SMS"
    }
  },
  "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.

{
  "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"
    }
  },
  "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.

{
  "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"
    }
  },
  "status" : "Success",
  "callbackCount" : 1,
  "maxCallbackThreshold" : 4
}

Reachability Notification Timeout with callback:

{
  "username" : "user",
  "password" : "pwd",
  "requestId" : "9dc93b95-b06f-42f2-b684-bf8051a8f303",
  "deviceIds" : [ {
    "id" : "89148001114434333820",
    "kind" : "ICCID"
  } ],
  "diagnosticsResponse" : {
    "deviceReachabilityResponse" : {
      "monitorId" : "fa06edc8-5093-4b52-a7d3-b815da712609",
      "accountName" : "0242123520-00001",
      "reportedTime" : "10/21/2019 9:00:00 PM",
      "notificationReport" : "STATUS_REQUEST_TIMEOUT"
    }
  },
  "status" : "Success",
  "callbackCount" : 1,
  "maxCallbackThreshold" : 4
}

Status 200

Success Response with no body.

Try It Out!