# Create a Data Usage Trigger (Account Level) ### `POST /v2/triggers` Create a new trigger to send an alert based on the account usage. The trigger may also suspend usage of specified devices. ## Header Parameters The request header must set the content-type to JSON, contain a current ThingSpace authorization token and a current VZ-M2M session token. For more details on how to get these tokens, visit [Getting Started](https://thingspace.verizon.com/documentation/api-documentation.html#/http/session-management/guides/getting-started). | Parameter Name | Data Type | Description | | :------------------------------ | :--------- | :---------------------------------------------------------------- | | **Authorization** *(required)* | string | HTTP Authorization bearer token: `Authorization: Bearer {token}` | | **VZ-M2M-Token** *(required)* | string | A valid session token: `VZ-M2M-Token: {M2Mtoken}` | | **Content-Type** *(required)* | string | Must be application/json `Content-Type: application/json` | ## HTTP Request [POST https://thingspace.verizon.com/api/m2m/v2/triggers](/docs/standard-apis/rules-engine-2-0/api-endpoints/create-triggers/createtriggerrules) **Note**: Please use the indicated drop down value in the Code Playground for the JSON listed ## Request Parameters The request body specifies the information about the Account Level data usage trigger that you want to create. Please note that all parameters are required unless marked *optional* | Parameter Name | Data Type | Description | |----------------|-----------|---------------------------------| | **triggerName** | 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** | object | The category of trigger being created. For these requests the category is `pricePlanDataUsage`. | | **pricePlanTrigger** | object | The parameters and actions of the trigger. | | **accountLevel** | object | Details of the Account Level price plan trigger | | **filterCriteria** | object | Defines separate (individual device or group) or combined (all groups or devices on the account) and the account names associated. | | **carrierServicePlanCode** | integer | The Service Plan ID. | | **accountNameList** | array | an array of `accountName` values using the service plan that the trigger will act upon. | | **condition** | object | Defines the trigger condition to monitor for notification. | | **conditionType** *(optional)* | string | The condition type defines how the trigger will evaluate the usage: <br> **Individual** - Per Device, with respect to defined threshold <br> **AccountLevel** - Aggregated per account, with respect to defined threshold <br> **UsageAllowance** - Per Account, with respect to the plan pool allowance <br> **Aging** - rather than usage, trigger will be activated based on how long a device has been on the specified plan. <br> **Note**: If this field is left blank, the `conditionType` will be "Individual"| | **comparator** *(optional)* | string | The type of comparison to be made against the threshold. The point reached relative to the threshold that the trigger activates: <br> **gt** - Greater Than, <br> **lt** - Less Than, <br> **eq** - Equal To <br>Required for "Individual" and "AccountLevel" `conditionTypes`. | | **threshold** *(optional)* | integer | The number of units defining the threshold. Required for "Individual" and "AccountLevel" `conditionTypes`. | | **cycleType** *(optional)* | string | The accumulation cycle of the trigger. <br>Required for "Individual" and "AccountLevel" `conditionTypes`: **Daily**, **Weekly** or **Monthly**. <br>Weekly cycles start on Monday and monthly cycles are based on the account billing cycle. Default is **Daily**. | | **separateOrCombined** *(optional)* | string | Only applicable for the "AccountLevel" `conditionType`. Determines whether or not to aggregate usage of multiple accounts together or separate by account: `Separate` or `Combined`. | | **percentage50** <br> **percentage75** <br> **percentage90** <br> **percentage100** | boolean | Indicates whether the trigger should be activated when usage reaches the specified percentage of the plan allowance: <br> **true** - trigger should be activated at percentage threshold <br> **false** - trigger should not be activated at percentage threshold. | | **action** | object | When the trigger activates, this is the action taken. | | **suspend** *(optional)* | boolean | Suspend the devices / account from further usage: <br> **true** - suspend devices when trigger is activated, account suspended <br> **false** - do not suspend devices when trigger is activated, account not suspended. <br> **Note**: Suspend and changePlan cannot both be true. | | **suspendDetails** | object | `suspendDetails` is required if the suspend boolean is **true**. | | **suspendFromAccounts** | array | An array of `accountNames` to suspend from usage. | | **suspendDuration** | string | Number of days to suspend service: 30, 60, 90 or NextBillCycle. | | **suspendOption** | string | `WithBilling` or `WithoutBilling`. This option depends on the service plan. | | **threshold** *(optional)* | integer | The number of units that cause suspension. Required if `suspend` is **true** and `conditionType` is "AccountLevel". | | **thresholdUnit** *(optional)* | string | The units the threshold is measured in: <br> **KB** - Kilobits, <br> **MB** - Megabits, <br> **GB** - Gigabits, <br> **TB** - Terabits. <br> Required if `suspend` is **true** and `conditionType` is "AccountLevel". | | **changePlan** *(optional)* | boolean | Changes the plan of the device upon activation of the trigger: <br> **true** - change plan when trigger is activated <br> **false** - do not change plan when trigger is activated. <br> **Note**: Suspend and changePlan cannot both be true. | | **changePlanDetails** | object | `changePlanDetails` is required if changePlan boolean is **true** and `conditionType` is "Individual". | | **toCarrierServicePlanCode** | string | The service plan ID to change the plan of the device to. | | **agingDetails** *(optional)* | object | `agingDetails` is required if `conditionType` is **Aging**. | | **onNumberOfBillCycle** | integer | The number of bill cycles that a device can be on the price plan before an alert is sent. | | **toCarrierServicePlanCode** *(optional)* | string | The service plan ID to change the plan of the device to. Required if `changePlan` is **true**. | | **notification** | object | Defines the type and frequency of notification. | | **notificationType** | string | This will be `PerEvent` or `DailySummary`. | | **callback** | boolean | Indicates if a callback will be generated by the notification or not: <br> **true** - A callback is generated <br> **false** - A callback will not be generated. | | **emailNotification** *(optional)* | boolean | Indicates if the notification will send an email or not: <br> **true** - notification generates an email <br> **false** - notification does not generate an email | | **notificationGroupName** *(optional)* | string | A user defined name for a group to notify. | | **notificationFequencyFactor** | integer | The number of reminder notifications to send after the trigger is activated. | | **notificationFrequencyInterval** | string | The frequency of the reminder notifications. **Hourly**, **Daily** or **Weekly**. | | **externalEmailRecipients** *(optional)* | string | A comma separated list of email addresses to notify if Email notification is used. | | **smsNotification** *(optional)* | boolean | Indicates if a notification Short Messaging Service (SMS) message will be sent: <br> **true** - a text message (sms) will be sent <br> **false** - a text message will not be sent | | **smsNumbers** | array | An array of mobile numbers to send text messages to if `smsNotification` is **true**. | | **number** | string | The 10-digit mobile number to send an SMS message to. | | **carrier** | string | The service provider for that mobile number. | | **reminder** | boolean | If a reminder will be sent at the defined intervals: <br> **true** - A reminder is sent <br> **false** - A reminder is not sent. | | **severity** | string | The severity associated with the notification: **Notice**, **Minor**, **Major** or **Critical**. | | **active** | boolean | Indicates the trigger is active or not: <br> **true** - trigger is active <br> **false** - trigger is not active | | ## Request Body Example Request Body using the dropdown for "Create Account Level Triggers": ```json { "triggerName": "user assigned trigger name", "ecpdId": "Verizon profile ID", "triggerCategory": "AccountUsage", "dataTrigger": { "accountLevel": { "filterCriteria": { "separateOrCombined": "Separate", "accountNames": { "accountNameList": [ "0000123456-00001" ] } }, "condition": { "comparator": "gt", "threshold": 100, "thresholdUnit": "KB", "cycleType": "Daily" }, "action": { "suspend": true, "suspendDetails": { "suspendFromAccounts": [ "0000123456-00001" ], "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 Responses **Status 200** Example Success Response: ```json { "triggerId": "b9cc1da6-ffff-eeee-gggg-7eba8859ab5e" } ``` ## Failure Responses All error messages are returned in this format: ```json { "error": "error code string", "error_description": "error message string", } ``` Error codes and messages are listed on the [Error Messages page](https://thingspace.verizon.com/documentation/api-documentation.html#/http/connectivity-management/guides/error-messages/synchronous-errors), along with explanations and suggestions for corrective actions. ## Callback Response 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](https://thingspace.verizon.com/documentation/api-documentation.html#/http/connectivity-management/guides/working-with-verizon-wireless/about-callback-services). Example callback response: ```json { "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": "AccountUsage", "accountName": "0000123456-00001", "accountLevel": { "allAccounts": false, "accountNames": [ "0000123456-00001" ], "deviceIds": [ { "id": "15-digit IMEI", "kind": "IMEI" } ], "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 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 UUID of the request being made. | | **deviceResponse** | object | All of the trigger information details. | | **alertServiceResponse** | object | All of the trigger information details returned by the responding device(s). | | **triggerId** | string | The trigger ID being queried. | | **triggerName** | string | The user assigned name of the trigger. | | **triggerCategory** | string | Price plan triggers will always have the type `PricePlanDataUsage`. | | **accountName** | string | The billing ID. Account names are numeric and must include the leading zeros. | | **accountShare** | object | Details about the account share Trigger. | | **carrierServicePlanCode** | string | The service plan ID. | | **servicePlanDescription** | string | A short description of the service plan. | | **deviceIds** | array | An array of device ID objects associated with the trigger. | | **id** | string | The device's ID value. | | **kind** | string | The type of ID. Valid types include: <br> **IMEI** (International Mobile Equipment Identifier) <br> **MSISDN** (Mobile Station Integrated Services Digital Network) <br> **MDN** (Mobile Device Number). | | **triggerDateTime** | string($date-time) | The date and time that the trigger was activated. | | **triggerValue** | integer | The value for when the trigger activates as set by the threshold. | | **cycleType** | string | The accumulation cycle of the trigger, for “Individual” and “AccountLevel” `conditionTypes`: **Daily**, **Weekly** and **Monthly**. <br> Weekly cycles start on Monday and monthly cycles are based on the account billing cycle. | | **threshold** | integer | The number of units measured as a threshold for the trigger. | | **thresholdUnits** | string | The units the threshold is measured in: <br> **KB** - Kilobits, <br> **MB** - Megabits, <br> **GB** - Gigabits and <br> **TB** - Terabits. | | **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. |