Create a Price Plan Trigger (Pay as you Go)

POST /v2/triggers

Create a new trigger to send an alert based on Pay As You Go price plan usage. The trigger may also suspend usage or change the service plan of specified devices.

See also:
Update price plan triggers (Pay as you Go)
Create Price Plan Triggers (Stand alone)
Create Price Plan Triggers (Profile share)
Create Price Plan Triggers (Account share)
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 Pay As You Go price plan 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 PricePlanDataUsage.


pricePlanTrigger
required

object The parameters and actions of the trigger.
pricePlanTrigger.payAsYouGo
required
object

Details of the Pay As You Go price plan trigger

pricePlanTrigger.payAsYouGo.filterCriteria
required
object

Defines separate or combined and the account names associated.

pricePlanTrigger.payAsYouGo.filterCriteria.carrierServicePlanCode
required
string The service plan ID
pricePlanTrigger.payAsYouGo.filterCriteria.accountNameList array of strings an array of accountNames using the service plan that the trigger will act upon.
pricePlanTrigger.payAsYouGo.condition
required
object Defines the trigger condition to monitor for notification.
pricePlanTrigger.payAsYouGo.condition.conditionType 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
  • Aging - rather than usage, trigger will be activated based on how long a device has been on the specified plan
pricePlanTrigger.payAsYouGo.condition.comparator string

The type of comparison to be made against the threshold:

  • gt - Greater Than
  • lt - Less Than

(Required for “Individual” and “AccountLevel” conditionTypes)

pricePlanTrigger.payAsYouGo.condition.threshold integer

The number of units defining the threshold.

(Required for “Individual” and “AccountLevel” conditionTypes)

pricePlanTrigger.payAsYouGo.condition.thresholdUnit string

The units the threshold is measured in:

  • KB - Kilobits
  • MB - Megabits
  • GB - Gigabits
  • TB - Terabits

(Required for “Individual” and “AccountLevel” conditionTypes)

pricePlanTrigger.payAsYouGo.condition.cycletype string

The accumulation cycle of the trigger. Required for “Individual” and “AccountLevel” conditionTypes:

  • Daily
  • Weekly
  • Monthly

Weekly cycles start on Monday, and monthly cycles are based on the account billing cycle

pricePlanTrigger.payAsYouGo.condition.separateOrCombined string

Only applicable for “AccountLevel” conditionType. Determines whether or not to aggregate usage of multiple accounts together, or separate by account:

  • Separate
  • Combined
pricePlanTrigger.payAsYouGo.action
required
object When the trigger activates, this is the action taken.
pricePlanTrigger.payAsYouGo.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

Only applicable for “Individual” and “AccountLevel” conditionType. Suspend and changePlan cannot both be true.

pricePlanTrigger.payAsYouGo.action.suspendDetails array suspendDetails is required if suspend boolean is true
pricePlanTrigger.payAsYouGo.action.suspendDetails.suspendFromAccounts array of strings An array of accountNames to suspend from usage
pricePlanTrigger.payAsYouGo.action.suspendDuration integer

Number of days to suspend service:

  • 30
  • 60
  • 90
  • NextBillCycle
pricePlanTrigger.payAsYouGo.action.suspendOption string

 

  • WithBilling
  • WithoutBilling

 

pricePlanTrigger.payAsYouGo.action.threshold integer

The number of units that cause suspension.

(Required if suspend is true and conditionType is “AccountLevel”)

pricePlanTrigger.payAsYouGo.action.thresholdUnit 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”)

pricePlanTrigger.payAsYouGo.action.changePlan 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

Only applicable for “Individual” conditionType. Suspend and changePlan cannot both be true

pricePlanTrigger.payAsYouGo.action.changePlanDetails object changePlanDetails is required if changePlan boolean is true and conditionType is “Individual”
pricePlanTrigger.payAsYouGo.action.changePlanDetails.toCarrierServicePlanCode string The service plan ID to change the plan of the device to.
pricePlanTrigger.payAsYouGo.action.agingDetails object agingDetails is required if conditionType is “Aging”
pricePlanTrigger.payAsYouGo.action.agingDetails.onNumberOfBillCycle integer Number of bill cycles that a device can be on the price plan before alert is sent
pricePlanTrigger.payAsYouGo.action.agingDetails.toCarrierServicePlanCode string The service plan ID to change the plan of the device to. Only required if changePlan is true.
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 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

With conditionType "Individual"

{
   "triggerName":"user assigned trigger name",
   "ecpdId":"Verizon profile ID",
   "triggerCategory":"PricePlanDataUsage",
   "pricePlanTrigger":{
      "payAsYouGo":{
         "filterCriteria":{
            "carrierServicePlanCode": "Service plan code value",
            "accountNameList": [
                "0000123456-00001"
            ]
         },
         "condition":{
            "conditionType":"Individual",
            "comparator":"gt",
            "threshold":100,
            "thresholdUnit":"KB",
            "cycleType":"Daily"
         },
         "action":{
            "changePlan":true,
            "changePlanDetails":{
               "toCarrierServicePlanCode":"Destination service plan code value",
            }
         }
      }
   },
   "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":"Critical"
   },
   "active":true
}

With conditionType "Aging"

{
   "triggerName":"user assigned trigger name",
   "ecpdId":"Verizon profile ID",
   "triggerCategory":"PricePlanDataUsage",
   "pricePlanTrigger":{
      "payAsYouGo":{
         "filterCriteria":{
            "carrierServicePlanCode": "Service plan code value",
            "accountNameList": [
                "0000123456-00001"
            ]
         },
         "condition":{
            "conditionType":"Aging"
         },
         "action":{
            "changePlan":true,
            "agingDetails":{
               "onNumberOfBillCycle":2,
               "toCarrierServicePlanCode":"Destination service plan code value",
            }
         }
      }
   },
   "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":"Critical"
   },
   "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": "PricePlanDataUsage",
            "accountName": "0000123456-00001",
            "payAsYouGo": {
                "carrierServicePlanCode": "sevice plan code value",
                "servicePlanDescription": "description of the service plan",
                "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 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 Price plan triggers will always have the type   PricePlanDataUsage.
deviceResponse.alertServiceResponse.accountName string The billing ID. Account names are usually numeric and must include the leading zeros.
deviceResponse.alertServiceResponse.payAsYouGo object Details about the Pay As You Go Trigger

deviceResponse.alertServiceResponse.payAsYouGo.

carrierServicePlanCode

string The service plan ID

deviceResponse.alertServiceResponse.payAsYouGo.

servicePlanDescription

string A short description of the service plan.
deviceResponse.alertServiceResponse.payAsYouGo.deviceIds array An array of device ID objects associated with the trigger.
deviceResponse.alertServiceResponse.payAsYouGo.deviceIds.id string The device's ID value.
deviceResponse.alertServiceResponse.payAsYouGo.deviceIds.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)
deviceResponse.alertServiceResponse.payAsYouGo.triggerDateTime string($date-time) The date and time that the trigger was activated.
deviceResponse.alertServiceResponse.payAsYouGo.triggerValue integer The value for when the trigger activates as set by the threshold. 
deviceResponse.alertServiceResponse.payAsYouGo.cycleType string

The accumulation cycle of the trigger. Required for “Individual” and “AccountLevel” conditionTypes:

  • Daily
  • Weekly
  • Monthly

Weekly cycles start on Monday, and monthly cycles are based on the account billing cycle.

deviceResponse.alertServiceResponse.payAsYouGo.threshold integer The number of units measured as a threshold for the trigger.
deviceResponse.alertServiceResponse.payAsYouGo.thresholdUnits string

The units the threshold is measured in:

  • KB - Kilobits
  • MB - Megabits
  • GB - Gigabits
  • TB - Terabits
deviceResponse.alertServiceResponse.payAsYouGo.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!