API Console

Create Price Plan Triggers (Account Group Share)

`POST /v2/triggers`

Create a new trigger to send an alert based on Account Group Share price plan usage. The trigger may also suspend usage or change the service plan of specified devices. Access to all of the accounts in the profile is required for Account Group Share triggers.

Content

Request Components
Request Example
Success Responses
- Example Success Response
- Failure Responses
Callback Examples
- Callback Body Parameters

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 information about the Account Group Share 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.accountGroupShare.accountGroupShareIndividual	object	The parameters and actions for the Individual Line Account Group Share trigger.
pricePlanTrigger.accountGroupShare.accountGroupShareIndividual.filterCriteria	object	Details of the service plan group that the trigger will act on.
pricePlanTrigger.accountGroupShare.accountGroupShareIndividual. filterCriteria.ratePlanGroupId	integer	The ID of the Service Plan Group.
pricePlanTrigger.accountGroupShare.accountGroupShareIndividual.condition	object	Defines the trigger action to be taken at the time of activation
pricePlanTrigger.accountGroupShare.accountGroupShareIndividual. condition.action	string	The action to take when the trigger is activated: notify - Send notification with no further action. suspend - Send notification and suspend the device. changePricePlan - Send notification and change the plan of the device
pricePlanTrigger.accountGroupShare.accountGroupShareIndividual.action	object	The action to take when the trigger is activated
pricePlanTrigger.accountGroupShare.accountGroupShareIndividual. action.notify	object	Details of the Notify action for the trigger
pricePlanTrigger.accountGroupShare.accountGroupShareIndividual. action.notify.alertType	string	How the thresholds should be applied: individualpriceplan - Define thresholds separately for each plan in the group allpriceplans - Define the same thresholds for all plans in the group
pricePlanTrigger.accountGroupShare.accountGroupShareIndividual. action.notify.threshold	array of objects	Define the thresholds for the notify action
pricePlanTrigger.accountGroupShare.accountGroupShareIndividual. action.notify.threshold.carrierCode	string	The plan that the percentage will be applied to. Only applicable for the alertType individualpriceplan
pricePlanTrigger.accountGroupShare.accountGroupShareIndividual. action.notify.threshold.percentage	object	Details of the notification threshold
pricePlanTrigger.accountGroupShare.accountGroupShareIndividual. action.notify.threshold.percentage.percentage50 pricePlanTrigger.accountGroupShare.accountGroupShareIndividual. action.notify.threshold.percentage.percentage75 pricePlanTrigger.accountGroupShare.accountGroupShareIndividual. action.notify.threshold.percentage.percentage90 pricePlanTrigger.accountGroupShare.accountGroupShareIndividual. action.notify.threshold.percentage.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
pricePlanTrigger.accountGroupShare.accountGroupSharePool. action.automation	string	How the price plans will be optimized: customerAutomation - User will define that plan changes that need to take place verizonAutomation - Verizon will determine the plan changes that will take place
pricePlanTrigger.accountGroupShare.accountGroupSharePool. action.changePlan	object	Only required if customerAutomation is selected
pricePlanTrigger.accountGroupShare.accountGroupSharePool. action.changePlan.changePlanGT	object	Defines the plan changes that will take place if usage is greater than 100% of the total pool allowance during trigger activation
pricePlanTrigger.accountGroupShare.accountGroupSharePool. action.changePlan.changePlanGT.changePlan	array of objects	Array of the plan changes to take when the usage is greater than 100% of the total pool allowance during trigger activation
pricePlanTrigger.accountGroupShare.accountGroupSharePool. action.changePlan.changePlanGT.changePlan.fromCarrierCode	string	The service plan ID of the devices that will have their plans changed
pricePlanTrigger.accountGroupShare.accountGroupSharePool.action. changePlan.changePlanGT.changePlan.toCarrierCode	string	The service plan ID to change the plan to
pricePlanTrigger.accountGroupShare.accountGroupSharePool. action.changePlan.changePlanGT.dataPoolOverageBuffer	integer	The percentage to increase the total pool allowance by after the price plan optimization: 5 - increase total pool allowance by 5% 10 - increase total pool allowance by 10% 15 - increase total pool allowance by 15% 20 - increase total pool allowance by 20%
pricePlanTrigger.accountGroupShare.accountGroupSharePool. action.changePlan.changePlanGT.triggerDate	string	When the plan change should take effect: CurrentDate BackDate
pricePlanTrigger.accountGroupShare.accountGroupSharePool. action.changePlan.changePlanLT	object	Details of the plan changes that will take place if usage is less than 100% of the total pool allowance during trigger activation
pricePlanTrigger.accountGroupShare.accountGroupSharePool. action.changePlan.changePlanLT.changePlan.fromCarrierCode	string	The service plan ID of the devices that will have their plans changed
pricePlanTrigger.accountGroupShare.accountGroupSharePool. action.changePlan.changePlanLT.changePlan.toCarrierCode	string	The service plan ID to change the plan to
pricePlanTrigger.accountGroupShare.accountGroupSharePool. action.changePlan.changePlanLT.dataPoolOverageBuffer	integer	The percentage to decrease the total pool allowance to after the price plan optimization: 95 - decrease the total pool allowance to 95% 90 - decrease the total pool allowance to 90% 85 - decrease the total pool allowance to 85% 80 - decrease the total pool allowance to 80%
pricePlanTrigger.accountGroupShare.accountGroupSharePool. action.changePlan.changePlanLT.triggerDate	string	When the plan change should take effect: CurrentDate FutureDate

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 activeThe plan that the percentage will be applied to. Only applicable for the alertType “individualpriceplans”

Example Request

{
   "triggerName":"user assigned trigger name",
   "ecpdId":"Verizon profile ID",
   "triggerCategory":"PricePlanDataUsage",
   "pricePlanTrigger":{
      "accountGroupShare":{
         "accountGroupShareIndividual":{
            "filterCriteria":{
               "ratePlanGroupId":73
            },
            "condition":{
               "action":"notify"
            },
            "action":{
               "notify":{
                  "alertType":"individualpriceplan",
                  "threshold":[
                     {
                        "carrierCode":"Service plan code value 1",
                        "percentage":{
                           "percentage50":false,
                           "percentage75":false,
                           "percentage90":true,
                           "percentage100":true
                        }
                     },
                     {
                        "carrierCode":"Service plan code value 2",
                        "percentage":{
                           "percentage50":false,
                           "percentage75":false,
                           "percentage90":true,
                           "percentage100":true
                        }
                     }
                  ]
               }
            }
         }
      }
   },
   "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
}

{
   "triggerName":"user assigned trigger name",
   "ecpdId":"Verizon profile ID",
   "triggerCategory":"PricePlanDataUsage",
   "pricePlanTrigger":{
      "accountGroupShare":{
         "accountGroupShareIndividual":{
            "filterCriteria":{
               "ratePlanGroupId":73
            },
            "condition":{
               "action":"suspend"
            },
            "action":{
               "suspend":{
                  "suspendDuration":"NextBillCycle",
                  "suspendOption":"withoutBilling",
                  "alertType":"individualpriceplan",
                  "threshold":[
                     {
                        "carrierCode":"Service plan code value 1",
                        "usagePercentage":50
                     },
                     {
                        "carrierCode":"Service plan code value 2",
                        "usagePercentage":90
                     }
                  ]
               }
            }
         }
      }
   },
   "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
}

{
   "triggerName":"user assigned trigger name",
   "ecpdId":"Verizon profile ID",
   "triggerCategory":"PricePlanDataUsage",
   "pricePlanTrigger":{
      "accountGroupShare":{
         "accountGroupShareIndividual":{
            "filterCriteria":{
               "ratePlanGroupId":73
            },
            "condition":{
               "action":"changePricePlan"
            },
            "action":{
               "changePlan":{
                  "sharePlan":[
                     {
                        "fromCarrierCode":"Service plan code value 1",
                        "toCarrierCode":"Service plan code value 2",
                        "criteriaPercentage":50
                     },
                     {
                        "fromCarrierCode":"Service plan code value 2",
                        "toCarrierCode":"Service plan code value 3",
                        "criteriaPercentage":75
                     }
                  ],
                  "triggerDate":"BackDate"
               }
            }
         }
      }
   },
   "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
}{
   "triggerName":"user assigned trigger name",
   "ecpdId":"Verizon profile ID",
   "triggerCategory":"PricePlanDataUsage",
   "pricePlanTrigger":{
      "accountGroupShare":{
         "accountGroupSharePool":{
            "filterCriteria":{
               "ratePlanGroupId":73
            },
            "condition":{
               "action":"notify"
            },
            "action":{
               "notify":{
                  "threshold":[
                     {
                        "percentage":{
                           "percentage50":false,
                           "percentage75":false,
                           "percentage90":true,
                           "percentage100":true
                        }
                     }
                  ]
               }
            }
         }
      }
   },
   "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
}

{
   "triggerName":"user assigned trigger name",
   "ecpdId":"Verizon profile ID",
   "triggerCategory":"PricePlanDataUsage",
   "pricePlanTrigger":{
      "accountGroupShare":{
         "accountGroupSharePool":{
            "filterCriteria":{
               "ratePlanGroupId":73
            },
            "condition":{
               "action":"changePricePlan"
            },
            "action":{
               "automation":"customerAutomation",
               "changePlan":{
                  "changePlanGT":{
                     "changePlan":[
                        {
                           "fromCarrierCode":"Service plan code value 1",
                           "toCarrierCode":"Service plan code value 2"
                        },
                        {
                           "fromCarrierCode":"Service plan code value 2",
                           "toCarrierCode":"Service plan code value 3"
                        }
                     ],
                     "dataPoolOverageBuffer":15,
                     "triggerDate":"CurrentDate"
                  },
                  "changePlanLT":{
                     "changePlan":[
                        {
                           "fromCarrierCode":"Service plan code value 3",
                           "toCarrierCode":"Service plan code value 2"
                        },
                        {
                           "fromCarrierCode":"Service plan code value 2",
                           "toCarrierCode":"Service plan code value 1"
                        }
                     ],
                     "dataPoolOverageBuffer":95,
                     "triggerDate":"CurrentDate"
                  }
               }
            }
         }
      }
   },
   "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
}

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	Account level 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.accountGroupShare	object	Details about the Account Group Share Trigger
deviceResponse.alertServiceResponse.accountGroupShare. carrierServicePlanCode	string	The service plan ID. This is only included for Individual Line triggers
deviceResponse.alertServiceResponse.accountGroupShare. servicePlanDescription	string	A short description of the service plan.This is only included for Individual Line triggers
deviceResponse.alertServiceResponse.accountGroupShare. servicePlanGroupId	integer	The ID of the Service Plan Group
deviceResponse.alertServiceResponse.standalone. accountGroupShare.deviceIds	array	An array of device ID objects associated with the trigger. This is only included for Individual Line triggers
deviceResponse.alertServiceResponse.standalone. accountGroupShare.deviceIds.id	string	The device's ID value.
deviceResponse.alertServiceResponse.standalone. accountGroupShare.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. accountGroupShare.allowance	integer	The allowance of the service plan in bytes
deviceResponse.alertServiceResponse. accountGroupShare.message	string	A message to be sent once the trigger activates
deviceResponse.alertServiceResponse.accountGroupShare.action	object	Details of the action taken after the trigger is activated
deviceResponse.alertServiceResponse.accountGroupShare.action.suspendDetails	object	Details of the suspend action
deviceResponse.alertServiceResponse.accountGroupShare.action. suspendDetails.suspendDuration	string	Number of days the device will be suspended for
deviceResponse.alertServiceResponse.accountGroupShare.action. suspendDetails.suspendOption	string	Whether the device was suspended with billing or without billing
deviceResponse.alertServiceResponse.accountGroupShare. action.changePlan	object	Details of the change plan action
deviceResponse.alertServiceResponse.accountGroupShare. action.changePlan.fromCarrierServicePlanCode	string	The service plan ID that the device was originally on. This is only included in the Individual Line Change Plan
deviceResponse.alertServiceResponse.accountGroupShare. action.changePlan.fromServicePlanDescription	string	The description of the service plan that the device was originally on. This is only included in the Individual Line Change Plan
deviceResponse.alertServiceResponse.accountGroupShare. action.changePlan.toCarrierServicePlanCode	string	The service plan ID of the plan that the device is being moved to. This is only included in the Individual Line Change Plan
deviceResponse.alertServiceResponse.accountGroupShare. action.changePlan.toServicePlanDescription	string	The description of the service plan that the device is being moved to. This is only included in the Individual Line Change Plan
deviceResponse.alertServiceResponse.accountGroupShare. action.changePlan.effectiveDate	string	When the plan change is taking effect. This is only included in the Individual Line Change Plan
deviceResponse.alertServiceResponse.accountGroupShare. action.changePlan.changePlanAutomation	string	Whether the change plan for the pool usage is Verizon Automation or Customer Automation
deviceResponse.alertServiceResponse.accountGroupShare. action.changePlan.moreThan100Percentage deviceResponse.alertServiceResponse.accountGroupShare. action.changePlan.lessThan100Percentage	object	Details about the plan change action for the Pool Usage trigger
deviceResponse.alertServiceResponse.accountGroupShare. action.changePlan.moreThan100Percentage.effectiveDate deviceResponse.alertServiceResponse.accountGroupShare. action.changePlan.lessThan100Percentage.effectiveDate	string	When the plan change is taking effect
deviceResponse.alertServiceResponse.accountGroupShare. action.changePlan.moreThan100Percentage.bufferAdded	string	The percentage that the total pool allowance was increased by after the plan changes
deviceResponse.alertServiceResponse.accountGroupShare. action.changePlan.lessThan100Percentage.bufferReduced	string	The percentage that the total pool allowance was reduced to after the plan changes
deviceResponse.alertServiceResponse.accountGroupShare. action.changePlan.moreThan100Percentage.devicePerPricePlan deviceResponse.alertServiceResponse.accountGroupShare. action.changePlan.lessThan100Percentage.devicePerPricePlan	array of objects	Details about the change plans that were initiated after the trigger was activated
deviceResponse.alertServiceResponse.accountGroupShare. action.changePlan.moreThan100Percentage.devicePerPricePlan.deviceCount deviceResponse.alertServiceResponse.accountGroupShare. action.changePlan.lessThan100Percentage.devicePerPricePlan.deviceCount	integer	The number of devices that are performing the specified plan change
deviceResponse.alertServiceResponse.accountGroupShare.action.changePlan. moreThan100Percentage.devicePerPricePlan.fromCarrierServicePlanCode deviceResponse.alertServiceResponse.accountGroupShare.action.changePlan. lessThan100Percentage.devicePerPricePlan.fromCarrierServicePlanCode	string	The service plan ID that the devices were originally on
deviceResponse.alertServiceResponse.accountGroupShare.action.changePlan. moreThan100Percentage.devicePerPricePlan.fromServicePlanDescription deviceResponse.alertServiceResponse.accountGroupShare.action.changePlan. lessThan100Percentage.devicePerPricePlan.fromServicePlanDescription	string	The description of the service plan that the devices were originally on
deviceResponse.alertServiceResponse.accountGroupShare.action.changePlan. moreThan100Percentage.devicePerPricePlan.toCarrierServicePlanCode deviceResponse.alertServiceResponse.accountGroupShare.action.changePlan. lessThan100Percentage.devicePerPricePlan.toCarrierServicePlanCode	string	The service plan ID of the plan that the devices are being moved to
deviceResponse.alertServiceResponse.accountGroupShare.action.changePlan. moreThan100Percentage.devicePerPricePlan.toServicePlanDescription deviceResponse.alertServiceResponse.accountGroupShare.action.changePlan. lessThan100Percentage.devicePerPricePlan.toServicePlanDescription	string	The description of the service plan that the devices are being moved to
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!