Create a Trigger for Usage Notifications:

POST /triggers

Create a new trigger that will send an alert callback based on specified device usage.

Contents

See also:
Get Triggers
Update a Trigger
Delete a Trigger
Retrieve Device Usage History
Retrieve Device Connection History
Retrieve Aggregated Device Usage

Uses and Requirements

When a trigger’s condition is met, an alert notification will be sent as a callback message. The account must be registered for the AlertService callbacks to receive these notifications.

Other conditions and limitations:

  • You can set the trigger for the entire account; it is not device specific.
  • The API monitors for other IMEI changes like SIM swaps, which can be used to detect SIM use in a device.
  • The callback response includes both the previous IMEI and the updated IMEI.
  • The API will not create triggers for a device if the preIMEI is different than the postIMEI after OTA is complete.
  • Alerts are sent at 1am UTC (01:00Z) time

Request Components

HTTP Request

POST https://thingspace.verizon.com/api/m2m/v1/triggers

Resource 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 trigger that you want to create.

Parameter Name Data Type Description
name
required
string A unique name for this trigger.
accountName
required
string The Verizon billing account that the trigger will belong to. An account name is usually numeric, and must include any leading zeros.
groupName
required
string The name of a device group, if you want this trigger to only be active for devices in that group. If you do not specify a device group, the trigger will be active for all devices in the account.
triggerCategory
required
string The type of usage that the trigger responds to. Valid values are:
  • AggregateDeviceUsage - The sum of all data usage for all devices on an account.
  • DeviceIMEIChange - The device IMEI change.
  • DeviceSMSUsage - The number of SMS (text) messages sent by and/or to a device.
  • DeviceDataUsage - The amount of data sent by a device.
  • DeviceSessionTime - The duration of session connections.
triggerCycle
required
string The accumulation cycle of the trigger, “Daily”, “Weekly”, or “Monthly”. Not needed for deviceSessionTime triggers.

Weekly cycles start on Monday, and monthly cycles are based on the account billing cycle.
smsTriggerRequest
required when triggerCategory == DeviceSMSUsage
SmsTriggerRequest The details of the DeviceSMSUsage trigger.
smsType
required for smsTriggerRequest
string The type of SMS messages that count toward the trigger criteria:
  • MO = Mobile-Originated (SMS messages sent by devices)
  • MT = Mobile-Terminated (SMS messages sent to devices)
  • MOMT = SMS messages sent by devices and to devices
threshold
required for smsTriggerRequest
string The number of smsType messages required to activate the trigger, based on the comparator.
comparator
required for smsTriggerRequest
string The type of comparison to be made between the number of smsType messages and threshold:

 

  • gt (greater than)
  • lt (less than)
dataTriggerRequest
required when triggerCategory == deviceDataUsage
DataTriggerRequest The details of the deviceDataUsage trigger.
threshold
required for smsTriggerRequest
string The amount of ThresholdUnit data required to activate the trigger, based on the comparator.
thresholdUnit
required for dataTriggerRequest
string Units to be used for counting data usage:
  • KB = Kilobytes
  • MB = Megabytes
  • GB = Gigabytes
comparator
required for dataTriggerRequest
string The type of comparison to be made between actual data usage and threshold:

 

  • gt (greater than)
  • lt (less than)
sessionTriggerRequest
required when triggerCategory == deviceSessionTime
SessionTriggerRequest The details of the deviceSessionTime trigger.
threshold
required for sessionTriggerRequest
string The number of seconds of session time required to activate the trigger, based on the comparator.
comparator
required for sessionTriggerRequest
string The type of comparison to be made between actual session duration and threshold:

 

  • lt (less than)
  • gt (greater than)

Example Request Body

A trigger for devices in the “NV trucks” device group that send more than 100 SMS messages in a week.

{
    "name": "SMS sent by trucks",
    "accountName": "1000012345-00001",
    "groupName": "NV trucks",
    "triggerCategory": "DeviceSMSUsage",
    "triggerCycle": "weekly",
    "smsTriggerRequest": {
        "smsType": "MO",
        "threshold": "100",
        "comparator": "gt"
    }
}

A request body for a trigger for DeviceIMEI change.

 {
    "name": "IMEI Change Alert",
    "accountName": "0342077109-00001",
    "triggerCategory": "DeviceIMEIChange",
    "triggerCycle": "Daily"
}

Success Responses

Status 200

Parameter Name Data Type Description
triggerId string A unique identifier for the new trigger. You must use this ID when making changes or deleting the trigger. All callbacks sent by this trigger will contain this triggerId.

Example Success Response

{
    "triggerId": "595f5c44-c31c-4552-8670-020a1545a84d",
}

Example Callback Messages

This notification identifies the trigger that sent the notification, the definition of the trigger, the device that met the criteria, and the time stamp of when the criteria was met.

{
    "username": "",
    "password": "",
    "requestId": "153531DE-2188-42D2-82F4-469B3A37AFD4",
    "deviceResponse": {
        "alertServiceResponse": {
            "triggerId": "42BD371F-BAD7-465C-BE74-F2EF3C0E58A1",
            "triggerName": "Weekly SMS MOMT Usage",
            "deviceIds": [
                {
                    "id": "6193187404",
                    "kind": "Mdn"
                }
            ],
            "triggerDateTime": "3/7/2018 3:38:32 AM",
            "triggerValue": "26",
            "triggerCycle": "WEEKLY",
            "smsType": "MOMT",
            "threshold": "25"
        }
    },
    "callbackCount": 1,
    "maxCallbackThreshold": 4
}

This notification is for the DeviceIMEI change trigger, which includes pre- and postIMEI:

{
    "preImei": "354196070045875",
    "postImei": "353238060068334"
}

Example callback response after a SIM was moved from device_A to device_B:

{
    "requestId": "74a22cc0-9914-66b6-f194-ab573aa6318e",
    "deviceResponse": {
        "alertServiceResponse": {
            "triggerId": "8adbe8bf-40be-4837-9294-4a0999fcec2c",
            "triggerName": "IMEI Change Alert",
            "deviceIds": [
                {
                    "id": "16124341227",
                    "kind": "Msisdn"
                }
            ],
            "triggerDateTime": "6/30/2020 7:04:11 PM",
            "triggerValue": "0",
            "threshold": "0",
            "message": "IMEI Change Notification. MSISDN: 16124341227. IMEI change from 353238060068334 to 354196070045875"
        }
    },
    "callbackCount": 1,
    "maxCallbackThreshold": 4
}

Failure Responses

Status 400

All error messages are returned in this format:

{
    "errorCode": "error code string",
    "errorMessage": "error message string"
}

Error codes and messages are listed on the Error Messages page, along with explanations and suggestions for corrective actions.

Try It Out!