API Reference

Retrieve the Status of a Device Based on the Request Type

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 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 provides the status. (The application should be programmed accordingly to handle this scenario).

Request Components

HTTP Request

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

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.
device required	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 required	string	Valid values include: REACHABLE_FOR_DATA REACHABLE_FOR_SMS LOSS_OF_CONNECTIVITY Note: REACHABLE_FOR_SMS is not supported for Higher Category LTE devices (IMS devices).
requestExpirationTime	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 starts 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"
  }
}

uccess Response

Status 200

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

Parameter Name	Data Type	Description
requestID required	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.

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	Data Type	Description
errorResponse	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	Data Type	Description
requestId required	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 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, MDN, MSISDN, ICCID) id: a device identifier value
status required	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	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	REACHABLE_FOR_DATA REACHABLE_FOR_SMS LOSS_OF_CONNECTIVITY STATUS_REQUEST_TIMEOUT
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

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

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

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

{
  "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",
      "maxUEAvailabilityTime":"10/9/2019 6:22:08 PM"
    }
  },
  "status" : "Success",
  "callbackCount" : 1,
  "maxCallbackThreshold" : 4
}

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

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

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

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
}

Retrieve the Status of a Device Based on the Request TypeCopy Anchor Link

Uses and RequirementsCopy Anchor Link

Request ComponentsCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Example Request BodyCopy Anchor Link

uccess ResponseCopy Anchor Link

Example Success ResponseCopy Anchor Link

Error responseCopy Anchor Link

Reachability ParametersCopy Anchor Link

Example Success Callback ResponsesCopy Anchor Link

On this page