Create Account Level Triggers

`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.

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.

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

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: Individual - Per Device, with respect to defined threshold AccountLevel - Aggregated per account, with respect to defined threshold UsageAllowance - Per Account, with respect to the plan pool allowance Aging - rather than usage, trigger will be activated based on how long a device has been on the specified plan. 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: gt - Greater Than, lt - Less Than, eq - Equal To 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. Required for "Individual" and "AccountLevel" `conditionTypes`: Daily, Weekly or Monthly. 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 percentage75 percentage90 percentage100	boolean	Indicates whether the trigger should be activated when usage reaches the specified percentage of the plan allowance: true - trigger should be activated at percentage threshold 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: true - suspend devices when trigger is activated, account suspended false - do not suspend devices when trigger is activated, account not suspended. 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: KB - Kilobits, MB - Megabits, GB - Gigabits, TB - Terabits. Required if `suspend` is true and `conditionType` is "AccountLevel".
changePlan (optional)	boolean	Changes the plan of the device upon activation of the trigger: true - change plan when trigger is activated false - do not change plan when trigger is activated. 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: true - A callback is generated false - A callback will not be generated.
emailNotification (optional)	boolean	Indicates if the notification will send an email or not: true - notification generates an email 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: true - a text message (sms) will be sent 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: true - A reminder is sent 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: true - trigger is active false - trigger is not active

Request Body

Example Request Body using the dropdown for "Create Account Level Triggers":

{
    "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:

{
    "triggerId": "b9cc1da6-ffff-eeee-gggg-7eba8859ab5e"
}

Failure Responses

All error messages are returned in this format:

{
  "error": "error code string",
  "error_description": "error message string",
}

Error codes and messages are listed on the Error Messages page, 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.

Example callback response:

{
    "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: IMEI (International Mobile Equipment Identifier) MSISDN (Mobile Station Integrated Services Digital Network) 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. 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: KB - Kilobits, MB - Megabits, GB - Gigabits and 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.

`POST /v2/triggers`

Header Parameters

HTTP Request

Request Parameters

Request Body

Success Responses

Failure Responses

Callback Response

Callback Parameters

On this page

Create Account Level Triggers

POST /v2/triggersCopy Anchor Link

Header ParametersCopy Anchor Link

HTTP RequestCopy Anchor Link

Request ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Success ResponsesCopy Anchor Link

Failure ResponsesCopy Anchor Link

Callback ResponseCopy Anchor Link

Callback ParametersCopy Anchor Link

On this page

`POST /v2/triggers`

Header Parameters

HTTP Request

Request Parameters

Request Body

Success Responses

Failure Responses

Callback Response

Callback Parameters