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!