Retrieve Active Reachablity Monitoring

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

Contents

Uses and Requirements

Using this API, an enterprise application shall be able to retrieve All outstanding (Active) Monitoring Events—that is, to retrieve all requested 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 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.
devices Mandatory 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 Optional String 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 Mandatory or Optional Data Type Description
requestID Mandatory 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 will send a separate callback message for each device that was in the request. All of the callback messages will 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 will end.

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!