Create a Trigger for Anomaly Detection

POST /v2/triggers

Creating a trigger for anomaly detection is similar to creating any trigger in Connectivity Management. The only difference is a few new values added for Anomaly Detection. This page will cover the new values and provide examples of what requests look like with the new values. The API Reference page for creating a trigger can be found at Create a Trigger for Usage Notifications.

Request Body

Parameter Name Data Type Description
triggerCategory
required		 string UsageAnomaly - This is the value to use in the request body to detect anomalous behaivior. The values in this table will only be relevant when this parameter is set to this value.
anomalyTriggerRequest
 object The details of the UsageAnomaly trigger.
anomalyTriggerRequest.accountNames
either accountNames or deviceGroup is required		 string

The Verizon billing accounts associated with the anomaly triggers for this trigger to be active for devices in those accounts. 

An account name is usually numeric, and must include any leading zeros.

anomalyTriggerRequest.deviceGroups
either accountNames or deviceGroup is required

 string The names of device groups associated with the anomaly triggers for this trigger to be active for devices in those groups.

anomalyTriggerRequest.includeAbnormal
required

 boolean

Whether or not to include  anomalies classified as “abnormal".

  • true
  • false

Classification is set as part of ThingSpace Intelligence anomaly detection settings.

anomalyTriggerRequest.includeVeryAbnormal
required

 boolean

Whether or not to include anomalies classified as “very abnormal”.

  • true
  • false

Classification is set as part of ThingSpace Intelligence anomaly detection settings.

anomalyTriggerRequest.includeUnderExpectedUsage
required

 boolean

Whether or not to include anomalies that are directionally under the expected usage.

  • true
  • false

anomalyTriggerRequest.includeOverExpectedUsage
required

 boolean

Whether or not to include anomalies that are directionally over the expected usage. 

  • true
  • false

notification
required

 object The notification details of the trigger.

notification.notificationType
required

 string The type of notification, i.e. "DailySummary".

notification.callback
required

 boolean

Whether or not the notification should be sent via callback.

  • true
  • false

notification.emailNotification
required

 boolean

Whether or not the notification should be sent via e-mail.

  • true
  • false

notification.externalEmailRecipients
required when emailNotification = true

 string E-mail address(es) where the notification should be delivered.
notification.notificationGroupName string Name for the notification group
notification.severity string

Severity level associated with the notification. Examples would be:

  • Major
  • Minor
  • Critical
  • NotApplicable
active boolean

Indicates Anomaly Detection is active

  • True - Anomaly Detection is active
  • False - Anomaly Detection is not active
active boolean

Indicates if the trigger is active

  • True - trigger is active
  • False - trigger is not active

HTTP Request

POST https://thingspace.verizon.com/api/m2m/v2/triggers

Example Request

Example of a trigger created at an account level:
{
   "name":"Anomaly Daily Usage REST Test-Patch 1",
   "triggerCategory":"UsageAnomaly",
   "accountName":"0000123456-00001",
   "anomalyTriggerRequest":{
      "accountNames":["0000123456-00001"],
      "includeAbnormal":true,
      "includeVeryAbnormal":true,
      "includeUnderExpectedUsage":true,
      "includeOverExpectedUsage":true
   },
   "notification":{
      "notificationType":"DailySummary",
      "callback":true,
      "emailNotification":false,
      "notificationGroupName":"Anomaly Test API",
      "notificationFrequencyFactor":3,
      "notificationFrequencyInterval":"20",
      "externalEmailRecipients":"placeholder@verizon.com",
      "smsNotification":true,
      "smsNumbers":"12345",
      "reminder":true,
      "severity":"Critical"
   },
   "active":true
}
   "active":true
}

Success Response

A successful request will return a trigger ID to identify the request in a callback. For more information about callbacks, please visit Register a Callback Listener.

Status 200

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

Failure Response

All failure responses are in this format:

{
    "errorCode": "error code string",
    "errorMessage": "error message string"
}

Callback Examples

These endpoints send responses asynchronously. In order to read the results a callback is required. To learn more about callbacks, please visit About Callback Services. The callback service to be subscribed to is AlertService.

Example of a callback for a daily summary of anomaly alerts:

{
   "username":"rv",
   "password":"123",
   "requestId":"824b1321-fc93-4864-a559-68ffebeba0bb",
   "deviceResponse":{
      "alertServiceResponse":{
         "triggerId":"595f5c44-c31c-4552-8670-020a1545a84d",
         "triggerName":"Rule Anomaly Daily Summary21Oct_18",
         "triggerDateTime":"10/26/2021 4:27:37 AM",
         "message":"Usage Anomaly Alert : Daily Summary for Account Number 0000123456-00001 on 10/26/2021 ",
         "accountName":"0000123456-00001",
         "anomaly":{
            "anomalyDevicesCount":3,
            "abnormalEventsCount":5,
            "veryAbnormalEventsCount":0
         },
         "notificationType":"Daily Summary"
      }
   },
   "callbackCount":1,
   "maxCallbackThreshold":4
}

Error codes and messages are listed on the Error Messages page, along with explanations and suggestions for corrective actions.

Try It Out!