Create a Data Usage Trigger (Device Group Level)

POST /v2/triggers

Create a new trigger to send an alert based on the device group usage. The trigger may also suspend usage of specified devices.

See also:
Create a data usage trigger (account level)
Update a data usage trigger (account level)
Update a data usage trigger (device group level)
Get rate plan list
Delete trigger

Request Components

HTTP Request

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

Resource Path and Query Parameters

 

None.

Header Parameters

The request header must contain a current ThingSpace authorization bearer token and a valid VZ-M2M session token, and must set the content-type to JSON.

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

Request Body

The request body specifies the information about the Device Group usage trigger that you want to create.

Parameter Name Data Type Description
triggerName
required		 string The user defined name of the trigger. 
ecpdId
 string The Enterprise Customer Profile Database ID (ECPD ID), also known as the Verizon profile ID.
triggerCategory
required		 object The category of trigger being created. For this request the category is DeviceGroupUsage.


dataTrigger
required

 object The parameters and actions of the trigger.
dataTrigger.accountLevel
required		 object

Defines the account information that will be using the trigger.
dataTrigger.accountLevel.filterCriteria
required		 object

Defines separate or combined and the account names associated.
dataTrigger.accountLevel.filterCriteria.accountNames
required		 object The accounts that the trigger will act upon.
dataTrigger.accountLevel.filterCriteria.accountNames.accountNameList
required		 array an array of accountNames that will use this trigger. An account name is usually numeric and must include any leading zeros.
dataTrigger.accountLevel.filterCriteria.accountNames.individualOrCombined
required		 string

Determines whether or not to aggregate usage of multiple accounts together, or separate by account.

  • Individual
  • Combined

If this is null or not present, then the trigger will be for the Individual Line.
dataTrigger.condition
required		 object Defines the trigger condition to monitor for notification.
dataTrigger.condition.comparator
required		 string

The type of comparison to be made against the threshold:

  • gt - Greater Than
  • lt - Less Than
dataTrigger.condition.threshold
required		 integer The number of units defining the threshold.
dataTrigger.condition.thresholdUnit
required		 string

The units the threshold is measured in:

  • KB - Kilobits
  • MB - Megabits
  • GB - Gigabits
  • TB - Terabits
dataTrigger.condition.cycletype
required		 string

The accumulation cycle of the trigger.

  • Daily
  • Weekly
  • Monthly

Weekly cycles start on Monday, and monthly cycles are based on the account billing cycle.
dataTrigger.action
required		 object When the trigger activates, this is the action taken.
dataTrigger.action.suspend boolean

Suspend the devices from further usage:

  • true - suspend devices when trigger is activated
  • false - do not suspend devices when trigger is activated
dataTrigger.action.suspendDetails object suspendDetails is required if suspend boolean is true
dataTrigger.accountLevel.action.suspendDetails.suspendDuration string

Number of days to suspend service:

  • 30
  • 60
  • 90
  • NextBillCycle
dataTrigger.accountLevel.action.suspendDetails.suspendOption string
  • WithBilling
  • WithoutBilling
dataTrigger.accountLevel.action.suspendDetails.threshold integer The number of units that cause suspension.
dataTrigger.action.thresholdUnit string

The units the threshold is measured in:

  • KB - Kilobits
  • MB - Megabits
  • GB - Gigabits
  • TB - Terabits
notification
required		 object

Defines the type and frequency of notification:
notification.notificationType string
  • PerEvent
  • DailySummary
notification.callback boolean

Indicates if a callback will be generated by the notification or not:

  • true - callback generated
  • false - callback will not be generated
notification.emailNotification boolean

Indicates if the notification will send an email or not:

  • true - notification generates an email
  • false - notification does not generate an email
notification.notificationGroupName string A user defined name for a group to notify.
notification.notificationFequencyFactor integer The number of reminder notifications to send after the trigger is activated.
notification.notificationFrequencyInterval string

The frequency of the reminder notifications.

  • Hourly
  • Daily
  • Weekly
notification.externalEmailRecipients string A comma separated list of email addresses to notify if Email notification is used.
notification.smsNotification boolean

Indicates if a notification Short Messaging Service (SMS) message will be sent:

  • true - a text message (sms) will be sent
  • false - a text message will not be sent
notification.smsNumbers array An array of mobile numbers to send text messages to.
notification.smsNumbers.number string The 10-digit mobile number to send an SMS message to.
notification.smsNumbers.carrier string The service provider for that mobile number.
notification.reminder boolean

If a reminder will be sent at the defined intervals:

  • true - reminder sent
  • false - reminder not sent
notification.severity string

The severity associated with the notification:

  • Notice
  • Minor
  • Major
  • Critical
active boolean

Indicates the trigger is active or not:

  • true - trigger is active
  • false - trigger is not active

Example Request

{
   "triggerName":"user assigned trigger name",
   "ecpdId":"Verizon profile ID",
   "triggerCategory":"DeviceGroupUsage",
   "dataTrigger":{
      "deviceGroup":{
         "filterCriteria":{
            "deviceGroupName": "User defined group name",
            "IndividualOrCombined": "Combined",
            "accountName": ""
            }
         },
         "condition":{
            "comparator":"gt",
            "threshold":100,
            "thresholdUnit":"KB",
            "cycleType":"Daily"
         },
         "action":{
            "suspend":true,
            "suspendDetails":{
               "suspendDuration":"90",
               "suspendOption":"withBilling",
               "threshold":50,
               "thresholdUnit":"KB"
            }
         }
      }
   },
   "notification":{
      "notificationType":"PerEvent",
      "callback":true,
      "emailNotification":false,
      "notificationGroupName":"NotificationGroupName",
      "notificationFrequencyFactor":3,
      "notificationFrequencyInterval":"Daily",
      "externalEmailRecipients":"ExternalEmailRecipients",
      "smsNotification":true,
      "smsNumbers":[
         {
            "number":"10-digit mobile number",
            "carrier":"mobile service provider"
         },
         {
            "number":"10-digit mobile number",
            "carrier":"mobile service provider"
         }
      ],
      "reminder":true,
      "severity":"Notice"
   },
   "active":true
}

Success Response

Status 200

Example Success Response:

{
  "triggerId": "b9cc1da6-89d8-4b52-b91a-7eba8859ab5e"
}

Failure Responses

Status 400

All error messages are returned in this format:

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

Callback Example

{
    "username": "user making the request",
    "password": "user's password",
    "requestId": "system generated request ID",
    "deviceResponse": {
        "alertServiceResponse": {
            "triggerId": "b9cc1da6-89d8-4b52-b91a-7eba8859ab5e",
            "triggerName": "user assigned trigger name",
            "triggerCategory": "DeviceGroupUsage",
            "accountName": "0000123456-00001",
            "deviceGroup": {
                "deviceGroupName": "deviceGroupName"
                "deviceIdentifierCollection": [
                    {
                        "id": "15-digit IMEI",
                        "kind": "IMEI"
                    }
                ],
                "category": "DeviceGroupUsage",
                "triggerDateTime": "2022-04-13T00:07:54.7410000Z",
                "triggerValue": 2,
                "cycleType": "DAILY",
                "threshold": 1,
                "thresholdUnit": "KB",
                "message": "Usage in KB > 1.00 KBDAILY (Usage in KB = 2.00 on device {device ID})"
            }
        }
    },
    "callbackCount": 1,
    "maxCallbackThreshold": 4
}

Callback Body Parameters

Parameter Name Data Type Description
username
 string The name of the user making the request.
password
 string The user's password.
requestId string System generated ID of the request being made.

deviceResponse

 object All of the trigger information details.
deviceResponse.alertServiceResponse
 object All of the trigger information details.
deviceResponse.alertServiceResponse.triggerId string

The trigger ID being queried
deviceResponse.alertServiceResponse.triggerName string The user defined name of the trigger.
deviceResponse.alertServiceResponse.triggerCategory string Device Group triggers will always have the type           DeviceGroupUsage.
deviceResponse.alertServiceResponse.accountName string The billing ID. Account names are usually numeric and must include the leading zeros.
deviceResponse.alertServiceResponse.deviceGroup object Details about the Device Group usage Trigger
deviceResponse.alertServiceResponse.deviceGroup.deviceGroupName string The name of the device group.
deviceResponse.alertServiceResponse.deviceGroup.deviceIdentifierCollection array An array of device ID objects
deviceResponse.alertServiceResponse.deviceGroup.deviceIdentifierCollection.id string The device's ID value
deviceResponse.alertServiceResponse.accountLevel.kind string

The type of ID. Valid values include:

  • IMEI (International Mobile Equipment Identifier)
  • MSISDN (Mobile Station Integrated Services Digital Network)
  • MDN (Mobile Device Number)
deviceResponse.alertServiceResponse.deviceGroup.category string

Device Group triggers will always have the type

DeviceGroupUsage.
deviceResponse.alertServiceResponse.deviceGroup.triggerDateTime string($date-time) The date and time that the trigger was activated
deviceResponse.alertServiceResponse.deviceGroup.triggerValue integer The value for when the trigger activates as set by the threshold. 
deviceResponse.alertServiceResponse.deviceGroup.cycleType string

The accumulation cycle of the trigger:

  • Daily
  • Weekly
  • Monthly

Weekly cycles start on Monday, and monthly cycles are based on the account billing cycle.
deviceResponse.alertServiceResponse.deviceGroup.threshold integer The number of units measured as a threshold for the trigger.
deviceResponse.alertServiceResponse.deviceGroup.thresholdUnits string

The units the threshold is measured in:

  • KB - Kilobits
  • MB - Megabits
  • GB - Gigabits
  • TB - Terabits
deviceResponse.alertServiceResponse.deviceGroup.message string A message to be sent once the trigger activates.
callbackCount integer The number of callbacks returned from the request.
maxCallbackThreshold integer The maximum number of callbacks allowed per request.

For more information about callbacks, please visit About Callback Services

 

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

Try It Out!