Retrieve All Active Reachability Monitoring Events:

POST /diagnostics/basic/devicereachability/monitors

Retrieves all active all outstanding (Active) Monitoring events.

Contents

Uses and Requirements

An enterprise application can use this API to retrieve All outstanding (Active) Monitoring Reachability (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

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.
devices
required		 Array of device objects

Each object in the array identifies a 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: a device identifier value; Required for IoT devices; not needed for consumer devices.

Note: the kind must be the same across the list—mixed kind is currently not supported.
requestType String Valid values include:
  • REACHABLE_FOR_DATA
  • REACHABLE_FOR_SMS
  • LOSS_OF_CONNECTIVITY

Example Request Body

Retrieve all monitors for given devices:

{
  "accountName": "0242123520-00001",
  "devices": [
    {
      "deviceIds": [
        {
          "id": "12016560696",
          "kind": "msisdn"
        }
      ]
    }
  ]
}

Retrieve all monitors of a certain type for given devices:

{
  "accountName": "0242123520-00001",
  "requestType": "REACHABLE_FOR_DATA",
  "devices": [
    {
      "deviceIds": [
        {
          "id": "12016560696",
          "kind": "msisdn"
        }
      ]
    }
  ]
}

Success Response

Status 200

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

Parameter Name Data Type Description
requestID
required		 string

A unique string that associates the retrieve request with the results that are sent via a 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 (tansactionID).

Example Success Response

Status 200

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

Parameters

Reachability deviceMonitorReport Callback Parameters

Parameter Name Mandatory or Optional Data Type Description
requestId Mandatory String A unique string that associates the request with the monitor information.
status Mandatory String Success, Failed
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.
monitors[ ].deviceIds (monitorResponse)* Optional 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
monitors[ ].monitorId (monitorResponse)* Mandatory String The ID of the registered monitor (UUID), which could be used by the customer when stopping the monitoring on this particular monitor
monitors[ ].monitorType (monitorResponse)* Optional String

REACHABLE_FOR_DATA, REACHABLE_FOR_SMS, LOSS_OF_CONNECTIVITY

This is not needed (or is Optional) if monitorType is specified in Original Request. This report would then contain monitorIds for only that specific monitorType (as requested in devicemonitorreport Request) and is implied.
monitors[ ].creationTime (monitorResponse)* Mandatory 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)
monitors[ ].expirationTime (monitorResponse)* Mandatory String

Identifies the absolute time at which the monitoring ends.

The format should be aligned with RFC3339, example: “2017-12-19T16:39:57-08:00” (in UTC passed as String)
pageNumber (monitorResponse) Mandatory Integer Index of the current block of 2000 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 (monitorResponse) Mandatory 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.

Note: * Array of monitors parameter is optional. Included only if there is at least one active monitor to report

Example:

{
  "username" : "user",
  "password" : "pwd",
  "requestId" : "c93239df-b8a6-45e1-a063-27ab3c9b4b10",
  "diagnosticsResponse" : {
    "monitorResponse" : {
      "accountName" : "0242123520-00001",
      "monitors" : [ {
        "deviceIds": [
        {
          "id": "12016560696",
          "kind": "msisdn"
        }
      ],
  "monitorId" : "7e05e020-a1cd-4dc5-ad88-c48051798a85",
        "monitorType" : "LOSS_OF_CONNECTIVITY",
        "creationTime" : "2019-10-29T19:46:41.467Z",
        "expirationTime" : "2019-10-31T22:00:00.000Z"
      } ],
      "pageNumber" : "1",
      "totalPages" : "1"
    }
  },
  "status" : "Success",
  "callbackCount" : 1,
  "maxCallbackThreshold" : 4
}

Status 200

Success Response with no body.

Try It Out!