Create a Price Plan Trigger (Account Share)

POST /v2/triggers

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

 

See also:
Update price plan triggers (Account share)
Create Price Plan Triggers (Pay as you Go)
Create Price Plan Triggers (Stand alone)
Create Price Plan Triggers (Profile 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 information about the Account 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.accountShare
object

Details of the Account Share price plan trigger

pricePlanTrigger.accountShare.filterCriteria
object

Defines separate or combined and the account names associated

pricePlanTrigger.accountShare.

filterCriteria.carrierServicePlanCode

integer The Service Plan ID
pricePlanTrigger.accountShare.filterCriteria.accountNameList array of strings

an array of accountNames using the service plan that the trigger will act upon.

pricePlanTrigger.accountShare.condition
required
object Defines the trigger condition to monitor for notification
pricePlanTrigger.accountShare.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
  • 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
pricePlanTrigger.accountShare.condition.comparator 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

(Required for Individual and AccountLevel conditionTypes)

pricePlanTrigger.accountShare.condition.threshold integer

The number of units defining the threshold

(Required for Individual and AccountLevel conditionTypes)

pricePlanTrigger.accountShare.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.accountShare.separateOrCombined string

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

  • Separate
  • Combined

pricePlanTrigger.accountShare.

allowanceThreshold.percentage50

pricePlanTrigger.accountShare.

allowanceThreshold.percentage75

pricePlanTrigger.accountShare.

allowanceThreshold.percentage90

pricePlanTrigger.accountShare.

allowanceThreshold.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.accountShare.action
required
object When the trigger activates, this is the action taken
pricePlanTrigger.accountShare.action.suspend 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

(Only applicable for Individual and AccountLevel conditionType. Suspend and changePlan cannot both be true)

pricePlanTrigger.accountShare.action.suspendDetails object suspendDetails is required if the suspend boolean is true

pricePlanTrigger.accountShare.action.

suspendDetails.suspendFromAccounts

array of strings An array of accountNames to suspend from usage

pricePlanTrigger.accountShare.action.

suspendDetails.suspendDuration

string

Number of days to suspend service:

  • 30
  • 60
  • 90
  • NextBillCycle

pricePlanTrigger.accountShare.action.

suspendDetails.suspendOption

string
  • WithBilling
  • WithoutBilling

pricePlanTrigger.accountShare.action.

suspendDetails.threshold

integer

The number of units that cause suspension

(Required if suspend is true and conditionType is AccountLevel)

pricePlanTrigger.accountShare.action.

suspendDetails.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.accountShare.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.accountShare.action.changePlanDetails object changePlanDetails is required if changePlan boolean is true and conditionType is Individual

pricePlanTrigger.accountShare.action.

changePlanDetails.toCarrierServicePlanCode

string The service plan ID to change the plan of the device to
pricePlanTrigger.accountShare.action.agingDetails object agingDetails is required if conditionType is Aging

pricePlanTrigger.accountShare.action.

agingDetails.onNumberOfBillCycle

integer Number of bill cycles that a device can be on the price plan before alert is sent

pricePlanTrigger.accountShare.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 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 Requests

{
   "triggerName":"user assigned trigger name",
   "ecpdId":"Verizon profile ID",
   "triggerCategory":"PricePlanDataUsage",
   "pricePlanTrigger":{
      "accountShare":{
         "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
}

{
   "triggerName":"user assigned trigger name",
   "ecpdId":"Verizon profile ID",
   "triggerCategory":"PricePlanDataUsage",
   "pricePlanTrigger":{
      "accountShare":{
         "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
}

{
   "triggerName":"user assigned trigger name",
   "ecpdId":"Verizon profile ID",
   "triggerCategory":"PricePlanDataUsage",
   "pricePlanTrigger":{
      "accountShare":{
         "filterCriteria":{
            "carrierServicePlanCode": "Service plan code value",
            "accountNameList": [
                "0000123456-00001"
            ]
         },
         "condition":{
            "conditionType":"UsageAllowance",
            "allowanceThreshold":{
            "percentage50":true,
            "percentage75":false,
            "percentage90":false,
            "percentage100":true
}
         },
         "action":{}
      }
   },
   "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": "dfc0dc3e-ebed-46eb-b36f-1a7d4bf588ac",
            "triggerName": "user assigned trigger name",
            "triggerCategory": "PricePlanDataUsage",
            "accountName": "0000123456-00001",
            "accountShare": {
                "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.accountShare object Details about the Pay As You Go Trigger

deviceResponse.alertServiceResponse.accountShare.

carrierServicePlanCode

string The service plan ID

deviceResponse.alertServiceResponse.accountShare.

servicePlanDescription

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

The units the threshold is measured in:

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