API Console

Create a Price Plan Trigger (Profile Share)

`POST /v2/triggers`

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

Content

Request Components
Request Examples
Success Responses
- Example Success Response
- Failure Responses
Callback Example
- 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 Profile 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.profileShare required	object	Details of the Profile Share price plan trigger
pricePlanTrigger.profileShare.filterCriteria required	object	Defines separate or combined and the account names associated.
pricePlanTrigger.profileShare. filterCriteria.carrierServicePlanCode required	string	The service plan ID
pricePlanTrigger.profileShare.filterCriteria.accountNameList	array of strings	an array of `accountNames` using the service plan that the trigger will act upon.
pricePlanTrigger.profileShare.condition required	object	Defines the trigger condition to monitor for notification.
pricePlanTrigger.profileShare.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 profile, with respect to the plan pool allowance. Requires the user to have access to all of the accounts in the profile Aging - rather than usage, trigger will be activated based on how long a device has been on the specified plan
pricePlanTrigger.profileShare.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.profileShare.condition.threshold	integer	The number of units defining the threshold. (Required for “Individual” and “AccountLevel” conditionTypes)
pricePlanTrigger.profileShare.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.profileShare.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.profileShare. 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.profileShare.allowanceThreshold	object	Only applicable for “UsageAllowance” conditionType. Defines trigger threshold based on percentage of plan allowance.
pricePlanTrigger.profileShare. allowanceThreshold.percentage50 pricePlanTrigger.profileShare. allowanceThreshold.percentage75 pricePlanTrigger.profileShare. allowanceThreshold.percentage90 pricePlanTrigger.profileShare. 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.profileShare.action required	object	When the trigger activates, this is the action taken.
pricePlanTrigger.profileShare.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.profileShare.action.suspendDetails	array	`suspendDetails` is required if suspend boolean is true
pricePlanTrigger.profileShare.action. suspendDetails.suspendFromAccounts	array of strings	An array of `accountNames` to suspend from usage
pricePlanTrigger.profileShare.action.suspendDuration	integer	Number of days to suspend service: 30 60 90 NextBillCycle
pricePlanTrigger.profileShare.action.suspendOption	string	WithBilling WithoutBilling
pricePlanTrigger.profileShare.action.threshold	integer	The number of units that cause suspension. (Required if suspend is true and conditionType is “AccountLevel”)
pricePlanTrigger.profileShare.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.profileShare.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.profileShare.action.changePlanDetails	object	`changePlanDetails` is required if changePlan boolean is true and conditionType is “Individual”
pricePlanTrigger.profileShare.action. changePlanDetails.toCarrierServicePlanCode	string	The service plan ID to change the plan of the device to.
pricePlanTrigger.profileShare.action.agingDetails	object	`agingDetails` is required if conditionType is “Aging”
pricePlanTrigger.profileShare.action. agingDetails.onNumberOfBillCycle	integer	Number of bill cycles that a device can be on the price plan before alert is sent
pricePlanTrigger.profileShare.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 Requests

{
   "triggerName":"user assigned trigger name",
   "ecpdId":"Verizon profile ID",
   "triggerCategory":"PricePlanDataUsage",
   "pricePlanTrigger":{
      "profileShare":{
         "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":"Email Addresses",
      "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":{
      "profileShare":{
         "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":"Email Addresses",
      "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":{
      "profileShare":{
         "filterCriteria":{
            "carrierServicePlanCode": "Service plan code value"
         },
         "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":"Email Addresses",
      "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",
            "profileShare": {
                "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!